Skip to main content
Code Example Language:
REST API v1

AccsGold API Documentation

Welcome to the AccsGold REST API reference. The API enables automated purchasing of temporary virtual phone numbers, real-time incoming SMS retrieval, programmatic session cancellation, and webhook notification delivery.

Base URL: https://api.accsgold.com/v1

All requests must be served over HTTPS. Requests sent over HTTP will be redirected. AccsGold abstracts multi-supplier upstream carriers (5SIM and Grizzly SMS); client apps should exclusively interface with AccsGold endpoints.

Authentication

Authenticate your API requests by including your secret API token in the Authorization header as a Bearer token.

HTTP Header Example
Authorization: Bearer ag_live_9f4b2c8e1d704a33b6e5c018d2a7f491
GET/services

Returns a list of all currently supported platforms, price multipliers, and voice verification support flags.

200 OK — Response Body
{
  "status": "success",
  "data": [
    {
      "id": "whatsapp",
      "name": "WhatsApp",
      "category": "Messaging",
      "supports_voice": true,
      "starting_price": 0.19
    },
    {
      "id": "telegram",
      "name": "Telegram",
      "category": "Messaging",
      "supports_voice": true,
      "starting_price": 0.17
    }
  ]
}
GET/countries

Retrieve supported international countries, dial codes, and current pool inventory counts.

{
  "status": "success",
  "data": [
    {
      "id": "us",
      "name": "United States",
      "iso": "US",
      "dial_code": "+1",
      "available_count": 12480,
      "starting_price": 0.45
    },
    {
      "id": "gb",
      "name": "United Kingdom",
      "iso": "GB",
      "dial_code": "+44",
      "available_count": 8920,
      "starting_price": 0.52
    }
  ]
}
GET/prices?service=whatsapp&country=us

Query real-time unit quotes before reserving a number.

{
  "service": "whatsapp",
  "country": "us",
  "price": 0.45,
  "currency": "USD",
  "available": 12480,
  "supports_voice": true
}
POST/activations

Reserve a virtual phone number from the supplier pool. Deducts the price from your wallet balance and begins the 20-minute expiration countdown.

Request Payload (CURL)
curl -X POST https://api.accsgold.com/v1/activations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "whatsapp",
    "country": "us",
    "number_type": "sms"
  }'
201 Created — Response Payload
{
  "id": "A98231",
  "service": "whatsapp",
  "country": "us",
  "dial_code": "+1",
  "phone_number": "+12025550148",
  "status": "waiting_sms",
  "price": 0.45,
  "currency": "USD",
  "code": null,
  "expires_in_seconds": 1200,
  "created_at": "2026-11-17T07:42:00Z"
}
GET/activations/:id

Poll the status of an ongoing verification session. Returns the extracted verification code once detected.

{
  "id": "A98231",
  "status": "code_received",
  "phone_number": "+12025550148",
  "code": "674921",
  "sms_text": "Your WhatsApp verification code: 674-921. Do not share.",
  "expires_in_seconds": 1042
}

Webhooks (Instant Delivery)

Rather than polling /activations/:id, configure an HTTPS webhook URL in your settings to receive an event immediately upon code arrival.

Webhook POST Payload delivered to your server
{
  "event": "sms.received",
  "activation_id": "A98231",
  "service": "whatsapp",
  "country": "us",
  "phone_number": "+12025550148",
  "code": "674921",
  "raw_text": "Your WhatsApp code is 674-921",
  "timestamp": 1794862920
}
POST/activations/:id/cancel

Cancel an active verification before code arrival. Instantly credits 100% of the purchase price back to your wallet ledger.

{
  "id": "A98231",
  "status": "cancelled",
  "refunded": true,
  "refund_amount": 0.45,
  "currency": "USD"
}

Errors & Status Codes

Standard HTTP status codes paired with machine-readable error identifiers.

CodeError ConstantDescription
401UNAUTHORIZEDMissing or invalid API token header.
402INSUFFICIENT_BALANCEWallet credits are lower than the quoted number price.
404NOT_FOUNDActivation ID does not exist or expired.
409NO_NUMBERS_AVAILABLEAll carrier routes for this country/platform are currently exhausted.
429RATE_LIMIT_EXCEEDEDRequest count exceeded the standard 120 req/min limit.

Rate Limits

Default API keys operate on a token bucket algorithm with a limit of 120 requests per minute and a burst capability of 200 requests.

Response headers reflect remaining token allowances:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 114
X-RateLimit-Reset: 1794862980