Endpoints reference
Ten endpoints cover the whole flow: check your balance, browse apps and countries, buy a number, read the SMS and close the order.
What endpoints does the SMS Nitro API have?
GET /v1/balance, GET /v1/services, GET /v1/services/{product}/countries, POST /v1/orders, GET /v1/orders, GET /v1/orders/{id}, and POST /v1/orders/{id}/finish, /cancel, /resend and /ban. All live under https://smsnitro.com/api and need the X-Api-Key header.
All endpoints
| Endpoint | What it does |
|---|---|
| GET /v1/balance | Available balance and the amount frozen by open orders (USD) |
| GET /v1/services | Apps you can verify with their starting price. Optional: country, server (1 or 2), search |
| GET /v1/services/{product}/countries | Countries for one app with price, success rate and dial code. Optional: server |
| POST /v1/orders | Buy a number. Body: product (required), country, operator, server |
| GET /v1/orders | Your orders, newest first. Optional: limit (1 to 100, default 50), offset |
| GET /v1/orders/{id} | One order, synced in real time: this is where the SMS shows up |
| POST /v1/orders/{id}/finish | Close the activation after using the code |
| POST /v1/orders/{id}/cancel | Cancel before any SMS and refund the frozen amount |
| POST /v1/orders/{id}/resend | Ask for another SMS on the same number, after the first code |
| POST /v1/orders/{id}/ban | Return a number the app reports as already used |
Browse apps and countries
Use the catalog endpoints to pick what to buy. The product value (for example telegram) is the id you send when buying. In the country list, rate3 and rate24 are the recent delivery success rates in percent, and offers shows each server's price.
curl "https://smsnitro.com/api/v1/services?country=usa" \
-H "X-Api-Key: $SMSNITRO_API_KEY"[
{ "product": "telegram", "price": "0.30", "count": 850,
"rate": null, "countries": [], "countries_count": 120 }
]curl https://smsnitro.com/api/v1/services/telegram/countries \
-H "X-Api-Key: $SMSNITRO_API_KEY"[
{
"country": "usa", "name": "United States", "iso": "us", "dial_code": "+1",
"price": "0.45", "count": 1200, "rate3": 95.0, "rate24": null, "server": 1,
"offers": [
{ "server": 1, "price": "0.45", "count": 1200, "rate3": 95.0 },
{ "server": 2, "price": "0.52", "count": 300, "rate3": 88.0 }
]
}
]Buy a number
Send product and country. Country accepts the catalog id (usa, england), an ISO code (gb) or the English name, and defaults to usa. Leave server out to let the API pick the best one. The response is the order with status PENDING and the phone number to enter in the app.
| Field | Description |
|---|---|
| product | Required. App id from GET /v1/services |
| country | Optional. Catalog id, ISO 3166-1 alpha-2 or English name. Default: usa |
| operator | Optional. Carrier, default any |
| server | Optional. 1 or 2. Omitted: automatic |
curl -X POST https://smsnitro.com/api/v1/orders \
-H "X-Api-Key: $SMSNITRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"product": "telegram", "country": "usa"}'{
"id": 123456,
"provider_order_id": "987654321",
"country": "usa",
"operator": "any",
"product": "telegram",
"phone": "+12025550123",
"status": "PENDING",
"price": "0.45",
"created_at": "2026-10-24T12:00:00Z",
"expires": "2026-10-24T12:20:00Z",
"messages": [],
"awaiting_resend": false,
"server": 1
}Read the SMS
Poll the order every 3 to 5 seconds. When the SMS arrives the status turns RECEIVED and messages holds the sender, the full text and the extracted code. Use code when it is not empty, otherwise read text.
curl https://smsnitro.com/api/v1/orders/123456 \
-H "X-Api-Key: $SMSNITRO_API_KEY"{
"id": 123456,
"phone": "+12025550123",
"status": "RECEIVED",
"price": "0.45",
"expires": "2026-10-24T12:20:00Z",
"messages": [
{
"sender": "Telegram",
"text": "Telegram code: 48291",
"code": "48291",
"received_at": "2026-10-24T12:01:10Z"
}
],
"awaiting_resend": false,
"server": 1
}Finish, cancel, resend or return
Each action returns the updated order. The rules for when each one is allowed are in the order lifecycle page.
# Done: the code worked
curl -X POST https://smsnitro.com/api/v1/orders/123456/finish -H "X-Api-Key: $SMSNITRO_API_KEY"
# No SMS: cancel and get the frozen amount back
curl -X POST https://smsnitro.com/api/v1/orders/123456/cancel -H "X-Api-Key: $SMSNITRO_API_KEY"
# Another SMS on the same number (after the first code, no extra cost)
curl -X POST https://smsnitro.com/api/v1/orders/123456/resend -H "X-Api-Key: $SMSNITRO_API_KEY"
# The app says the number is already used: return it
curl -X POST https://smsnitro.com/api/v1/orders/123456/ban -H "X-Api-Key: $SMSNITRO_API_KEY"List your orders
curl "https://smsnitro.com/api/v1/orders?limit=20&offset=0" \
-H "X-Api-Key: $SMSNITRO_API_KEY"Frequently asked questions
Is there a webhook when the SMS arrives?
No. Poll GET /v1/orders/{id} every 3 to 5 seconds; the SMS is returned as soon as it arrives.
What is the server field?
Numbers come from two supply servers. Server 1 is the main one; server 2 is the alternative. Leave it out and the API chooses; set it to compare prices or retry on the other one.