> For the complete documentation index, see [llms.txt](https://docs.sms4sats.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sms4sats.com/getting-started/getting-started.md).

# Quickstart

Create, pay, and poll your first sms4sats API v2 order.

This example uses the bearer-token receive-SMS API. It is the simplest integration for web apps, mobile apps, backend services, and bots.

## 1. Discover a service

```bash
curl -sS 'https://api.sms4sats.com/v2/receive-sms/catalog?country=auto'
```

Use a `services[].code` value in the next requests. `country=auto` lets sms4sats select a route using live availability and recent delivery performance.

## 2. Request a live quote

```bash
curl -sS -X POST https://api.sms4sats.com/v2/receive-sms/quote \
  -H 'Content-Type: application/json' \
  -d '{"country":"auto","service":"tg"}'
```

```json
{
  "type": "receive-sms",
  "country": "151",
  "service": "tg",
  "durationMinutes": null,
  "availability": 120,
  "priceSats": 350
}
```

A quote is side-effect free: it does not create an invoice or reserve inventory. Price and availability may change before creation.

## 3. Create the order

Generate a new UUID v4 once and reuse it only when retrying this exact request.

```bash
curl -sS -X POST https://api.sms4sats.com/v2/receive-sms/orders \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 17165eb7-d770-4a21-abd4-90295ac15252' \
  -d '{"country":"auto","service":"tg"}'
```

```json
{
  "orderId": "<payment-hash>",
  "accessToken": "<opaque-token>",
  "orderReference": "<payment-hash>.<opaque-token>",
  "invoice": "lnbc...",
  "priceSats": 350,
  "status": "pending_payment"
}
```

{% hint style="danger" %}
Store `accessToken` securely when it is returned. Treat it like a password: anyone who has it can read or cancel that order. Do not log it, place it in a URL, or expose it in analytics.
{% endhint %}

## 4. Pay and poll

Pay `invoice` with a Lightning wallet, then poll every 5–10 seconds:

```bash
curl -sS https://api.sms4sats.com/v2/receive-sms/orders/ORDER_ID \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

A successful order normally progresses through:

```
pending_payment → paid → allocating → waiting_for_sms → code_received → completed
```

The assigned `phoneNumber` appears after allocation. Delivered SMS content appears in `messages`.

## 5. Handle completion or cancellation

Stop polling on `completed`, `cancelled`, `expired`, or `failed`. If no message arrives, use the response's `cancellation.eligible` and `cancellation.availableAt` fields rather than a client-side guess.

```bash
curl -sS -X POST \
  https://api.sms4sats.com/v2/receive-sms/orders/ORDER_ID/cancel \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

Continue with [Catalog & Quotes](/api-reference/catalog-and-quotes.md) or review [Errors, Limits & Retries](/api-reference/errors.md) before shipping.