SMS Nitro API documentation
Everything you need to buy a temporary number, read the verification code and close the order from your own code. JSON over HTTPS, one API key, the same prices and billing rule as the dashboard.
How does the SMS Nitro API work?
You send POST /v1/orders with an app and a country and get a phone number back. You poll GET /v1/orders/{id} every 3 to 5 seconds until the SMS appears in messages, then call finish. If no SMS arrives, cancel and the frozen amount returns to your balance: you pay only for codes that arrive.
Quickstart in four calls
Get a key
Top up once, open Dashboard > API and generate your key. Send it in the X-Api-Key header.
Buy a number
POST /v1/orders with product and country. The price is frozen on your balance.
Read the code
Poll GET /v1/orders/{id} every 3 to 5 seconds until messages has the SMS.
Close the order
POST finish when the code worked, or cancel when nothing arrived to get a refund.
The API at a glance
| Item | Value |
|---|---|
| Base URL | https://smsnitro.com/api/v1 |
| Format | JSON over HTTPS, UTF-8. Prices are decimal strings in USD, dates are ISO 8601 in UTC |
| Authentication | X-Api-Key header, or Authorization: Bearer |
| Billing | Price frozen at purchase, charged only when the SMS arrives, refunded otherwise |
| Number lifetime | Up to 20 minutes per activation |
| Rate limits | 500 purchases per minute, 30 resend requests per minute |
| Live spec | OpenAPI 3.1 at /developers/openapi.json |
Your first request
Check that the key works by reading your balance. A 200 response with balance and frozen means you are ready to buy numbers. Frozen is the amount reserved by orders that are still waiting for an SMS.
curl https://smsnitro.com/api/v1/balance \
-H "X-Api-Key: $SMSNITRO_API_KEY"{
"balance": "12.50",
"frozen": "0.45",
"currency": "USD"
}All articles
- AuthenticationHow to authenticate to the SMS Nitro API: where to get the key, the X-Api-Key and Bearer headers, key rotation and how to keep the key out of client code.
- Endpoints referenceEvery endpoint of the SMS Nitro REST API v1: balance, services, countries, orders, finish, cancel, resend and ban, with parameters, curl requests and JSON responses.
- Order lifecycle and billingWhat each SMS Nitro order status means, when the balance is charged or refunded, how long a number lasts and when you can finish, cancel, resend or return it.
- Errors and rate limitsHTTP status codes returned by the SMS Nitro API (400, 401, 402, 404, 409, 429, 502), what each one means, the rate limits and a retry strategy that works.
- SMS verification in PythonReceive SMS verification codes from Python with the SMS Nitro API and requests: buy a number, poll for the OTP, finish or cancel. Complete, copy-paste script.
- SMS verification in Node.jsReceive SMS verification codes in Node.js 18+ with fetch and the SMS Nitro API: buy a number, poll for the OTP, finish or cancel. Includes TypeScript types.
- SMS verification in PHPReceive SMS verification codes in PHP 8 with cURL and the SMS Nitro API: buy a number, poll for the OTP, finish or cancel. Complete, copy-paste script.
Frequently asked questions
Is there a sandbox?
No. Requests run against the live catalog, but nothing is charged unless an SMS arrives, so testing the full flow costs only the codes you actually receive.
Do API prices differ from the dashboard?
No. The API uses the same catalog, prices and balance as the website, with no surcharge.
Where is the machine-readable spec?
The OpenAPI 3.1 document of the public endpoints is at https://smsnitro.com/developers/openapi.json. Import it into Postman, Insomnia or a code generator.
How do I get an API key?
Create an account, make your first top-up and generate the key in Dashboard > API. Each account has one active key.
Get your verification code now
Top up from $5, pick an app and a country, and read the SMS in your browser. Charged only when the code arrives.
Get a number+1 (415) 555-0132