Introduction
Welcome to the NumsGo API. Programmatically purchase virtual phone numbers, receive SMS verification codes, and manage your account.
Base URL
"https://api.numsgo.com/v1"All requests must be made over HTTPS. Responses are JSON.
Response Format
{
"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/ordersGenerate API keys from Dashboard → API Keys. Keep them secret and rotate if compromised.
Error Handling
The API uses standard HTTP status codes.
| Code | Meaning |
|---|---|
| 200 | Success |
| 201 | Created (new resource) |
| 400 | Bad request — check parameters |
| 401 | Unauthorized — invalid or missing API key |
| 404 | Not found |
| 422 | Validation error — see message |
| 429 | Rate limit exceeded |
| 500 | Server error — try again later |
{
"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
/v1/accountAUTHGet your balance and profilecurl "https://api.numsgo.com/v1/account" \
-H "Authorization: Bearer __API_KEY__" \
-H "Accept: application/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
/v1/account/transactionsAUTHList your wallet ledgerParameters
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"{
"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
/v1/countriesList available countriesParameters
productstringFilter countries by product (e.g. telegram)curl "https://api.numsgo.com/v1/countries?product=telegram"{
"data": [
{
"id": 1,
"name": "usa",
"display_name": "USA",
"iso_code": "us",
"phone_prefix": "+1"
}
]
}Products
/v1/productsList available servicesParameters
popularflagInclude to filter only popular servicescategorystringFilter by category (e.g. activation)curl "https://api.numsgo.com/v1/products?popular&category=activation"{
"data": [
{
"id": 1,
"name": "telegram",
"display_name": "Telegram",
"category": "activation",
"icon": null,
"is_popular": true
}
]
}Prices
/v1/prices/{country}/{product}Get pricing for a country/product paircurl "https://api.numsgo.com/v1/prices/usa/telegram"{
"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
/v1/ordersAUTHPurchase a virtual numberParameters
countrystringrequiredCountry name (e.g. usa, england)productstringrequiredService name (e.g. telegram, whatsapp)operatorstringSpecific operator, or omit for best availablecurl -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"}'{
"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
/v1/ordersAUTHList your ordersParameters
statusstringFilter: PENDING, RECEIVED, FINISHED, CANCELED, TIMEOUT, BANNEDper_pageintegerResults per page (default 20, max 100)pageintegerPage numbercurl "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.
/v1/orders/{id}/checkAUTHPoll for SMS codecurl "https://api.numsgo.com/v1/orders/550e8400-e29b-41d4-a716-446655440000/check" \
-H "Authorization: Bearer __API_KEY__" \
-H "Accept: application/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.
/v1/orders/{id}/finishAUTHConfirm SMS received, complete ordercurl -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.
/v1/orders/{id}/cancelAUTHCancel order and get refundcurl -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.
/v1/orders/{id}/banAUTHReport number as unusablecurl -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.
/v1/orders/{id}/reuseAUTHRe-purchase the same numbercurl -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.
/v1/rentals/plansAUTHList available rental servicescurl "https://api.numsgo.com/v1/rentals/plans" -H "Authorization: Bearer __API_KEY__"{
"data": [
{ "service_code": 1, "name": "Full Access", "available": 12, "sell_price": 9.99 }
]
}Rent a Number
/v1/rentalsAUTHRent a monthly numberParameters
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}'{
"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
/v1/rentalsAUTHList your rentalsParameters
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.
/v1/rentals/{id}/messagesAUTHGet stored rental messages/v1/rentals/{id}/checkAUTHPoll provider for new messagescurl "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.
/v1/rentals/{id}/cancelAUTHCancel a rentalcurl -X POST "https://api.numsgo.com/v1/rentals/7f1e.../cancel" -H "Authorization: Bearer __API_KEY__"Auto-Renew
/v1/rentals/{id}/auto-renewAUTHEnable or disable auto-renewParameters
is_renewablebooleanrequiredtrue to enable monthly auto-renewcurl -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.
/v1/rentals/{id}/transferAUTHCreate a one-time transfer code for a rentalcurl -X POST "https://api.numsgo.com/v1/rentals/RENTAL_ID/transfer" -H "Authorization: Bearer __API_KEY__"{
"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).
/v1/rentals/claimAUTHClaim a transferred numberParameters
codestringrequiredThe NUMS-… transfer codecurl -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
/v1/rentals/transfersAUTHList your pending outgoing transfers/v1/rentals/transfers/{id}/revokeAUTHRevoke a pending transfercurl "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
/profile/api-keysAUTHList your API keys/profile/api-keysAUTHGenerate a new API keyParameters
namestringrequiredKey name (e.g. Production)The full API key is only shown once. Save it securely.
/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"}'