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

**Apps available in a country**

```bash
curl "https://smsnitro.com/api/v1/services?country=usa" \
  -H "X-Api-Key: $SMSNITRO_API_KEY"
```

**Response**

```json
[
  { "product": "telegram", "price": "0.30", "count": 850,
    "rate": null, "countries": [], "countries_count": 120 }
]
```

**Countries for one app**

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

**Response**

```json
[
  {
    "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 |

**Request**

```bash
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"}'
```

**Response (201 Created)**

```json
{
  "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.

**Request**

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

**Response after the SMS**

```json
{
  "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.

**Order actions**

```bash
# 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

**Request**

```bash
curl "https://smsnitro.com/api/v1/orders?limit=20&offset=0" \
  -H "X-Api-Key: $SMSNITRO_API_KEY"
```

## FAQ

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

Source: https://smsnitro.com/developers/endpoints