# 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

1. **Get a key** Top up once, open Dashboard > API and generate your key. Send it in the X-Api-Key header.
2. **Buy a number** POST /v1/orders with product and country. The price is frozen on your balance.
3. **Read the code** Poll GET /v1/orders/{id} every 3 to 5 seconds until messages has the SMS.
4. **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.

**Request**

```bash
curl https://smsnitro.com/api/v1/balance \
  -H "X-Api-Key: $SMSNITRO_API_KEY"
```

**Response**

```json
{
  "balance": "12.50",
  "frozen": "0.45",
  "currency": "USD"
}
```

## FAQ

**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.

## Articles

- [Authentication](https://smsnitro.com/developers/authentication): How 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 reference](https://smsnitro.com/developers/endpoints): Every 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 billing](https://smsnitro.com/developers/order-lifecycle): What 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 limits](https://smsnitro.com/developers/errors): HTTP 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 Python](https://smsnitro.com/developers/python): Receive 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.js](https://smsnitro.com/developers/nodejs): Receive 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 PHP](https://smsnitro.com/developers/php): Receive 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.

Source: https://smsnitro.com/developers