Skip to content

API Reference

Two ways in: a clean REST v1 for new integrations, and an SMS-Activate-compatible handler so existing bots migrate by changing the host. Both use the same API keys.

Authentication

Create an API key on the Developer page (max 5 per account; the full key is shown once). Pass it either way:

# Bearer header (preferred)
Authorization: Bearer sk_abc123...

# or query parameter
https://sms-go.pro/api/v1/balance?api_key=sk_abc123...

Keys are stored as SHA-256 hashes. Rate limit is 1,000 requests/minute per key (see rate limits).

Error format

Errors return success: false with a machine-readable code and a human message:

{
  "success": false,
  "error_code": "NO_BALANCE",
  "error_msg": "Insufficient balance, please recharge first"
}
error_codeHTTPMeaning
BAD_KEY401Missing or invalid API key
RATE_LIMITED429Over 1,000 req/min for this key
BAD_SERVICE404No active service matches the name/country
NO_BALANCE402Balance too low for this purchase
NO_NUMBERS503Supplier could not allocate a number
NO_ACTIVATION404Number not found (or not yours)
BAD_STATUS409Number already delivered / already refunded

REST v1

Base URL: https://sms-go.pro/api/v1

GET/api/v1/pricesno auth

Live price catalog. No API key required — compare prices before you deposit. Same data the landing stock sheet shows.

curl https://sms-go.pro/api/v1/prices
{
  "success": true,
  "demo": false,
  "data": [
    { "service": "Telegram", "country": "US", "durationDays": 30,
      "price": 2.00, "stock": 48200 }
  ]
}
GET/api/v1/balanceAPI key

Your available balance.

curl https://sms-go.pro/api/v1/balance \
  -H "Authorization: Bearer sk_..."
{ "success": true, "data": { "balance": 10.00, "currency": "USDT" } }
POST/api/v1/numbersAPI key

Buy one or more numbers. This is a rental— the number is yours for the service's duration with unlimited incoming SMS. Charges your balance at the live price.

Body fieldTypeNotes
servicestringRequired. Matched against active services, e.g. "Telegram"
countrystringOptional. Default "US"
quantitynumberOptional. 1–500. Default 1
curl -X POST https://sms-go.pro/api/v1/numbers \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"service":"Telegram","country":"US","quantity":1}'

Send an Idempotency-Key header to make the purchase safe to retry (replays return the same result for 24h without double-charging).

{
  "success": true,
  "data": {
    "orders": [ { "id": "...", "orderNumber": "ORD..." } ],
    "numbers": [
      { "id": "num_...", "phoneNumber": "+1...",
        "serviceName": "Telegram", "ourToken": "tk_...",
        "expiryDate": "2026-09-29T00:00:00.000Z" }
    ],
    "totalPrice": 2.00,
    "balanceAfter": 8.00
  }
}
GET/api/v1/numbers/:id/smsAPI key

Messages received on one rented number (newest first). Includes a parsed otp field when a code is detected.

curl https://sms-go.pro/api/v1/numbers/num_.../sms \
  -H "Authorization: Bearer sk_..."
{
  "success": true,
  "data": {
    "numberId": "num_...",
    "phoneNumber": "+1...",
    "status": "active",
    "expiryDate": "2026-09-29T00:00:00.000Z",
    "messages": [
      { "sender": "Telegram", "content": "Your code: 123456",
        "otp": "123456", "receivedAt": "2026-08-30T12:00:00.000Z" }
    ]
  }
}
DELETE/api/v1/numbers/:idAPI key

Cancel a number and refund the charge to your balance. Refunds only while no SMS has arrived — a number that delivered a code is final. (The auto-refund watchdog also handles this at the 20-minute mark if you take no action.)

curl -X DELETE https://sms-go.pro/api/v1/numbers/num_... \
  -H "Authorization: Bearer sk_..."

{ "success": true, "data": { "status": "refunded", "balanceAfter": 10.00 } }

SMS-Activate compatibility

Drop-in endpoint for bots built against the SMS-Activate protocol. Same actions, plain-text responses. Pass the key as ?api_key=sk_....

https://sms-go.pro/api/handler_api.php?action=getNumber&service=tg&country=187&api_key=sk_...
actionWhat it doesExample response
getBalanceYour balanceACCESS_BALANCE:10.00
getPricesPrice catalog (JSON){"tg":...}
getNumberBuy a numberACCESS_NUMBER:num_id:+1...
getStatusCheck for the codeSTATUS_OK:123456 or STATUS_WAIT_CODE
setStatus6 = finish, 8 = cancel+refundSTATUS_CANCEL / STATUS_OK

Honest delta from SMS-Activate: SMS-Activate sells one-shot activations; SMS-GO sells 30-day rentals. getNumber buys a rental, and setStatus=8 cancels with a refund only while no SMS has arrived.

Service codeService
tgTelegram
waWhatsApp
goGoogle
oaOpenAI
igInstagram
fbFacebook
ttTikTok
dsDiscord
amAmazon
ebeBay
ppPayPal
tw / xTwitter
msMicrosoft
apApple

Webhooks

Instead of polling /numbers/:id/sms, register an HTTPS endpoint and we push events to it. Configure it on the Push settings page (must be a public https:// URL).

EventWhen it fires
sms.receivedAn SMS lands on one of your numbers
number.refundedA number was auto-refunded or you cancelled it
number.expiredA rental reached its expiry

Every delivery includes the event name and an HMAC signature so you can verify it came from us:

# Headers
X-SMSGO-Event: sms.received
X-SMSGO-Signature: sha256=<hmac of the body>

# Body
{
  "event": "sms.received",
  "number_id": "num_...",
  "phone": "+1...",
  "sender": "Telegram",
  "content": "Your code: 123456",
  "otp": "123456",
  "sent_at": "2026-08-30T12:00:00.000Z"
}

Rate limits

1,000 requests/minute per API key, measured as a sliding window. When you exceed it you get HTTP 429 with an error_code: RATE_LIMITED and a Retry-After header.

Need a higher limit for a large pipeline? Contact support@sms-go.pro.

Need help integrating?

Questions about the API, or a pipeline you are moving over from another provider? Reach us at support@sms-go.pro or @sms_go_support.