Introduction

Welcome to the NumsGo API. Programmatically purchase virtual phone numbers, receive SMS verification codes, and manage your account.

Base URL

Response (JSON)
"https://api.numsgo.com/v1"

All requests must be made over HTTPS. Responses are JSON.

Response Format

Response (JSON)
{
  "data": { ... },
  "message": "Success"
}

Authentication

The API uses Bearer token authentication. Include your API key in the Authorization header.

curl -H "Authorization: Bearer __API_KEY__" \
     -H "Accept: application/json" \
     https://api.numsgo.com/v1/orders

Generate API keys from Dashboard → API Keys. Keep them secret and rotate if compromised.

Error Handling

The API uses standard HTTP status codes.

CodeMeaning
200Success
201Created (new resource)
400Bad request — check parameters
401Unauthorized — invalid or missing API key
404Not found
422Validation error — see message
429Rate limit exceeded
500Server error — try again later
Response (JSON)
{
  "message": "Insufficient balance.",
  "errors": {
    "country": ["The country field is required."]
  }
}

Rate Limits

Limits are enforced per API key (or per IP for public endpoints). Exceeding a limit returns 429 Too Many Attempts with a Retry-After header.

  • General endpoints: 60 requests/minute
  • Number purchases (buy / reuse / rent): 10 requests/minute

Balance

GET/v1/accountAUTHGet your balance and profile
curl "https://api.numsgo.com/v1/account" \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Accept: application/json"
Response (JSON)
{
  "data": {
    "email": "[email protected]",
    "name": "You",
    "balance": 25.50,
    "currency": "USD",
    "total_earned": 0,
    "total_withdrawn": 0,
    "member_since": "2026-01-01T00:00:00+00:00"
  }
}

Transactions

GET/v1/account/transactionsAUTHList your wallet ledger

Parameters

per_pageintegerResults per page (default 20, max 100)
curl "https://api.numsgo.com/v1/account/transactions" \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Accept: application/json"
Response (JSON)
{
  "data": [
    {
      "id": "9b2c...",
      "type": "sms_purchase",
      "amount": -0.12,
      "balance_after": 25.38,
      "description": "SMS activation: telegram (england)",
      "created_at": "2026-03-20T12:15:00+00:00"
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 20, "total": 1 }
}

Countries

GET/v1/countriesList available countries

Parameters

productstringFilter countries by product (e.g. telegram)
curl "https://api.numsgo.com/v1/countries?product=telegram"
Response (JSON)
{
  "data": [
    {
      "id": 1,
      "name": "usa",
      "display_name": "USA",
      "iso_code": "us",
      "phone_prefix": "+1"
    }
  ]
}

Products

GET/v1/productsList available services

Parameters

popularflagInclude to filter only popular services
categorystringFilter by category (e.g. activation)
curl "https://api.numsgo.com/v1/products?popular&category=activation"
Response (JSON)
{
  "data": [
    {
      "id": 1,
      "name": "telegram",
      "display_name": "Telegram",
      "category": "activation",
      "icon": null,
      "is_popular": true
    }
  ]
}

Prices

GET/v1/prices/{country}/{product}Get pricing for a country/product pair
curl "https://api.numsgo.com/v1/prices/usa/telegram"
Response (JSON)
{
  "data": [
    {
      "country": "usa",
      "product": "telegram",
      "operator": "t-mobile",
      "price": 0.0833,
      "count": 327,
      "rate": null
    }
  ]
}

price is what you pay (USD). count is available numbers — use it as the availability signal. rate is the provider success-rate sample when available, otherwise null.

Buy Number

POST/v1/ordersAUTHPurchase a virtual number

Parameters

countrystringrequiredCountry name (e.g. usa, england)
productstringrequiredService name (e.g. telegram, whatsapp)
operatorstringSpecific operator, or omit for best available
curl -X POST "https://api.numsgo.com/v1/orders" \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"country": "usa", "product": "telegram"}'
Response (JSON)
{
  "message": "Number purchased successfully.",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "phone": "+12025551234",
    "product": "Telegram",
    "country": "USA",
    "country_code": "us",
    "status": "RECEIVED",
    "status_label": "Number Ready",
    "price": 0.0833,
    "sms_code": null,
    "expires_at": "2026-03-20T12:30:00+00:00",
    "created_at": "2026-03-20T12:15:00+00:00"
  }
}

List Orders

GET/v1/ordersAUTHList your orders

Parameters

statusstringFilter: PENDING, RECEIVED, FINISHED, CANCELED, TIMEOUT, BANNED
per_pageintegerResults per page (default 20, max 100)
pageintegerPage number
curl "https://api.numsgo.com/v1/orders?status=RECEIVED&per_page=10" \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Accept: application/json"

Check SMS

Poll every 3-5 seconds to check if an SMS has arrived. When sms_code is not null, the verification code is ready.

GET/v1/orders/{id}/checkAUTHPoll for SMS code
curl "https://api.numsgo.com/v1/orders/550e8400-e29b-41d4-a716-446655440000/check" \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Accept: application/json"
Response (JSON)
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "RECEIVED",
    "sms_code": "482910",
    "sms_text": "Your Telegram code: 482910",
    "phone": "+12025551234"
  }
}

Finish Order

Call after you have successfully used the verification code. Marks the order as complete.

POST/v1/orders/{id}/finishAUTHConfirm SMS received, complete order
curl -X POST "https://api.numsgo.com/v1/orders/550e8400-.../finish" \
  -H "Authorization: Bearer __API_KEY__"

Cancel Order

Only available if no SMS has been received. The full amount is refunded to your wallet.

POST/v1/orders/{id}/cancelAUTHCancel order and get refund
curl -X POST "https://api.numsgo.com/v1/orders/550e8400-.../cancel" \
  -H "Authorization: Bearer __API_KEY__"

Report Number

Report if the number was already used or not working. The amount is refunded.

POST/v1/orders/{id}/banAUTHReport number as unusable
curl -X POST "https://api.numsgo.com/v1/orders/550e8400-.../ban" \
  -H "Authorization: Bearer __API_KEY__"

Reuse Number

Attempt to re-purchase the same phone number. Not guaranteed -- the number may no longer be available. You are only charged if successful.

POST/v1/orders/{id}/reuseAUTHRe-purchase the same number
curl -X POST "https://api.numsgo.com/v1/orders/550e8400-.../reuse" \
  -H "Authorization: Bearer __API_KEY__"

Rental Plans

Long-term (monthly) numbers that keep receiving SMS. List the available services and their monthly price.

GET/v1/rentals/plansAUTHList available rental services
curl "https://api.numsgo.com/v1/rentals/plans" -H "Authorization: Bearer __API_KEY__"
Response (JSON)
{
  "data": [
    { "service_code": 1, "name": "Full Access", "available": 12, "sell_price": 9.99 }
  ]
}

Rent a Number

POST/v1/rentalsAUTHRent a monthly number

Parameters

service_codeintegerrequiredFrom /rentals/plans. Price is resolved server-side.
curl -X POST "https://api.numsgo.com/v1/rentals" \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Content-Type: application/json" \
  -d '{"service_code": 1}'
Response (JSON)
{
  "message": "Number rented successfully.",
  "data": {
    "id": "7f1e...",
    "phone": "+447700900123",
    "service_name": "Full Access",
    "sell_price": 9.99,
    "status": "ACTIVE",
    "is_auto_renew": false,
    "expires_at": "2026-04-20T12:00:00+00:00"
  }
}

List Rentals

GET/v1/rentalsAUTHList your rentals

Parameters

per_pageintegerResults per page (default 20, max 100)
curl "https://api.numsgo.com/v1/rentals" -H "Authorization: Bearer __API_KEY__"

Rental Messages

Fetch stored SMS for a rental. Use POST /rentals/{id}/check to poll the provider for new ones.

GET/v1/rentals/{id}/messagesAUTHGet stored rental messages
POST/v1/rentals/{id}/checkAUTHPoll provider for new messages
curl "https://api.numsgo.com/v1/rentals/7f1e.../messages" -H "Authorization: Bearer __API_KEY__"

Cancel Rental

Rentals are final and non-refundable; cancelling stops auto-renew and releases the number.

POST/v1/rentals/{id}/cancelAUTHCancel a rental
curl -X POST "https://api.numsgo.com/v1/rentals/7f1e.../cancel" -H "Authorization: Bearer __API_KEY__"

Auto-Renew

POST/v1/rentals/{id}/auto-renewAUTHEnable or disable auto-renew

Parameters

is_renewablebooleanrequiredtrue to enable monthly auto-renew
curl -X POST "https://api.numsgo.com/v1/rentals/7f1e.../auto-renew" \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Content-Type: application/json" \
  -d '{"is_renewable": true}'

Create Transfer

Generate a one-time code to hand a rental number to another user. The code is shown once and expires in 7 days. Auto-renew is turned off when the number is claimed.

POST/v1/rentals/{id}/transferAUTHCreate a one-time transfer code for a rental
curl -X POST "https://api.numsgo.com/v1/rentals/RENTAL_ID/transfer" -H "Authorization: Bearer __API_KEY__"
Response (JSON)
{
  "message": "Transfer code created. Share it with the recipient — it is shown only once.",
  "data": { "transfer_id": "…", "code": "NUMS-XXXXXXXXXX", "expires_at": "2026-07-29T12:00:00+00:00" }
}

Claim Number

Redeem a transfer code to take ownership of the number. Any account can claim (create one first if needed).

POST/v1/rentals/claimAUTHClaim a transferred number

Parameters

codestringrequiredThe NUMS-… transfer code
curl -X POST "https://api.numsgo.com/v1/rentals/claim" \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Content-Type: application/json" \
  -d '{"code": "NUMS-XXXXXXXXXX"}'

List / Revoke Transfers

GET/v1/rentals/transfersAUTHList your pending outgoing transfers
POST/v1/rentals/transfers/{id}/revokeAUTHRevoke a pending transfer
curl "https://api.numsgo.com/v1/rentals/transfers" -H "Authorization: Bearer __API_KEY__"
curl -X POST "https://api.numsgo.com/v1/rentals/transfers/TRANSFER_ID/revoke" -H "Authorization: Bearer __API_KEY__"

API Keys

GET/profile/api-keysAUTHList your API keys
POST/profile/api-keysAUTHGenerate a new API key

Parameters

namestringrequiredKey name (e.g. Production)

The full API key is only shown once. Save it securely.

DELETE/profile/api-keys/{id}AUTHRevoke an API key
# Create a key
curl -X POST "https://api.numsgo.com/v1/profile/api-keys" \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production"}'