---
name: sms-activate-api
description: Use the SMS Activate App REST API to buy long-term virtual phone numbers and read the SMS and calls they receive, with a personal API key. Trigger when a task needs a phone number to receive an SMS code, complete a phone verification or automate SMS-based 2FA.
---

# SMS Activate App API skill

You can call the SMS Activate App REST API to buy virtual phone numbers (28 days, auto-renewal on by
default) and read the SMS verification codes they receive.

## Base URL

`https://api.sms-activate.app/v1/public`

Human docs: https://sms-activate.app/api ; OpenAPI 3.1 spec: https://sms-activate.app/openapi.json ; changelog: https://sms-activate.app/api-changelog.md

## Authentication

**Every request needs a personal API key**, catalog included:

```
Authorization: Bearer vpn_xxx
```

The user creates the key in the account (API keys tab) at <https://sms-activate.app/account?tab=api-keys> or in the
Telegram bot. A key acts for the user's account and spends its balance. Keep it server-side, read it from
an environment variable, never print or commit it, and ask the user for it instead of inventing one.

## Conventions

- Money is **integer USD cents** (`balanceCents: 2000` is $20.00).
- `POST /v1/public/numbers` requires an `Idempotency-Key` header (8 to 200 characters of
  letters, digits, `_`, `-`, `:`). One key per purchase; resend the same key on a retry and the first
  answer comes back instead of a second charge. A new key is a new purchase.
  Without one the answer is `400 validation_failed`.
- Limits: at least 120 requests a minute per account, shared by its keys, and at least
  30 a minute for purchases. Over them: `429 rate_limited` with `Retry-After`. Handle 429 even below the stated rate.
- Every answer to a key carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds); slow down
  as `RateLimit-Remaining` nears 0, and on a 429 wait `Retry-After` seconds. A `401` carries
  `WWW-Authenticate: Bearer realm="api.sms-activate.app"`: send `Authorization: Bearer <key>`.
- The key's owner gets a message in the Telegram bot when requests are refused for balance (at most once
  in 5 minutes) and a summary of the key's errors (at most once in 30 minutes).
- Errors are `{ "error": "<code>", "message": "...", "details"?: {...}, "reqId": "..." }`.
  **Branch on the error code, never on the HTTP status.**
- SMS feeds are cursor-paginated (`?limit=&cursor=`, `nextCursor` is null on the last page). Poll
  roughly every 5 to 15 s with a timeout, or set a webhook (below).

## Refusals on a purchase

- `409 number_unavailable`: the number was sold or is no longer for sale; search again.
- `409 no_numbers`: nothing can be bought in that country now; try later or another country.
- `409 price_exceeded`: the price rose above your cap; search again for the current price.
- `409 insufficient_balance`: the balance is short (details.requiredCents); top up, then retry.
- `409 idempotent_replay`: the same Idempotency-Key came with another body or is still in flight; wait, or send a new key for a new purchase.
- `429 rate_limited`: wait as long as Retry-After says, then retry.
- `503 provider_unavailable`: a temporary failure; retry later with backoff.
- `502 provider_failure`: the purchase did not complete; check your numbers before buying again.

## Endpoints

Paths are written in full from `https://api.sms-activate.app`.

| Method & path | Purpose |
| --- | --- |
| `GET /v1/public/countries` | Countries with availability and the price range. |
| `GET /v1/public/numbers/search` | Live numbers for sale in a country, with your price. |
| `POST /v1/public/numbers` | Buy a number from the search, for 28 days. |
| `GET /v1/public/numbers` | Your numbers. |
| `GET /v1/public/numbers/:id` | One of your numbers. |
| `PATCH /v1/public/numbers/:id` | Note, webhook, Telegram chat, auto-renew, notifications. |
| `DELETE /v1/public/numbers/:id` | Release a number. |
| `GET /v1/public/numbers/:id/sms` | SMS received by one number. |
| `GET /v1/public/sms` | SMS received by all your numbers. |
| `GET /v1/public/balance` | Your balance in cents. |

The same key also reaches these account routes:

| Method & path | Purpose |
| --- | --- |
| `GET /v1/me/numbers/:id/calls` | Calls received by a number, with the recording's text and the code read out in it. |
| `GET /v1/me/inbox` | All SMS and calls, newest first. |
| `GET /v1/me/numbers/:id/release-preview` | What releasing a number returns. |
| `GET /v1/me/recoverable` | Released numbers you can buy back. |
| `POST /v1/me/recoverable/:id/recover` | Buy back a released number. |
| `GET /v1/me/transactions` | Your statement. |
| `GET /v1/me/movements` | Balance movements. |
| `GET /v1/me/topup/options` | Ways and amounts to top up. |
| `POST /v1/me/topup` | Start a top-up. |
| `GET /v1/me/topup/:invoiceId` | A top-up's status. |
| `GET /v1/me/notifications` | Notification settings. |
| `PUT /v1/me/notifications` | Change notification settings. |
| `GET /v1/me/watches` | Your watches. |
| `GET /v1/me/watches/quote` | What a watch costs. |
| `POST /v1/me/watches` | Watch for a number to come into stock. |
| `PATCH /v1/me/watches/:id` | Pause, resume or change a watch. |
| `DELETE /v1/me/watches/:id` | Delete a watch. |
| `GET /v1/me/kyc` | Identity verification status, and the numbers that still need it. |
| `GET /v1/me/transfers` | Transfers you sent or received; `?state=all` for the history. |
| `POST /v1/me/webhook-secret` | A new webhook signing secret, shown once. |
| `POST /v1/me/webhook-test` | Send a test event to your webhook. |
| `GET /v1/me/webhook-deliveries` | Recent webhook deliveries, without bodies. |
| `POST /v1/me/number-orders` | Buy a number that needs verification, once the verification is approved (409 verification_first before). |
| `GET /v1/me/number-orders` | Your orders for numbers that need verification. |
| `DELETE /v1/me/number-orders/:id` | Cancel such an order. |
| `GET /v1/me/partner` | Partner earnings, read only. |
| `GET /v1/me/partner/links` | Partner links, read only. |
| `GET /v1/me/withdrawals` | Your USDT withdrawals, read only. |
| `GET /v1/me/withdrawals/preview` | What a withdrawal of an amount would cost. |
| `GET /v1/me/free-numbers` | Free shared numbers. |
| `GET /v1/me/free-numbers/:id/sms` | SMS of a free shared number. |
| `GET /v1/me` | Your profile: balance, discount, webhook. |
| `PATCH /v1/me` | Change the display name, language or account webhook. |
| `POST /v1/me/numbers` | Buy a number (the account route; the same purchase as POST /v1/public/numbers). |
| `PATCH /v1/me/numbers/:id` | A number's settings (the account route). |
| `POST /v1/me/numbers/:phone/reserve` | Hold a number for you for up to 10 minutes before buying. |
| `POST /v1/me/topup/:invoiceId/recheck` | Re-check a top-up's payment now; with `intent`, the purchase it pays for runs once paid. |

Closed to a key on purpose (403): making, cancelling or taking a transfer, withdrawing, filing an identity verification and its form, changing the partner cabinet (rules, links, claims), the Telegram link (`POST /v1/auth/link/telegram`), free-number access (`GET /v1/me/free-numbers/access`), creating an API key (`POST /v1/me/api-keys`; listing and revoking stay open), setting a password (`POST /v1/me/password`).

The public catalog also answers without a key (no account price): `GET /v1/countries`, `GET /v1/numbers`, `GET /v1/numbers/pick`, `GET /v1/numbers/:phone`, `GET /v1/pricing/:country`, `GET /v1/platforms`.

## Recommended flow (verify an account)

1. `GET /v1/public/countries` to confirm the country has numbers.
2. `GET /v1/public/numbers/search?country=US&limit=5` and take a `phoneNumber`.
3. `POST /v1/public/numbers` with `{ "phone": "<phoneNumber>", "country": "US" }` and an Idempotency-Key.
4. Use the number on the target platform to trigger the SMS.
5. Poll `GET /v1/public/numbers/:id/sms` until the code arrives (respect a timeout).
6. `DELETE /v1/public/numbers/:id` when the number is no longer needed.

## Webhooks instead of polling

`PATCH /v1/public/numbers/:id` with `{ "forwardWebhookUrl": "https://your-app.example.com/sms" }` and every SMS and call on that
number is POSTed there. The URL is pinged with `{"event":"ping"}` before it is stored and must answer 2xx.
Requests carry `x-vpn-event`, `x-vpn-timestamp` and `x-vpn-signature`: HMAC-SHA256 of
`v1.<timestamp>.<raw body>` with your webhook secret. Reject a timestamp more than 5 minutes off.

## Number Watcher (availability alerts and auto-buy)

`POST /v1/me/watches` with `{ "watchType": "pattern", "country": "US", "pattern": "7777", "autoPurchase": true, "maxPriceCents": 1500 }`
watches for a number to come into stock and can buy it under the cap. `watchType: "exact"` watches one
`targetPhone`; `country: "*"` watches every country on sale (digit patterns only). `GET /v1/me/watches/quote` says what a watch costs.

## Only numbers are sold

Only long-term numbers are sold. Do not build on `/products/*` or `/activations`: since 2026-10-17 a new
order there answers 501, and they remain only for keys that read what they already hold.

## Partner programme

The affiliate programme has **no endpoints in this API in v1**: it is browser session-only. Read it at
<https://sms-activate.app/affiliate> (rules: <https://sms-activate.app/affiliate/rules>) and do not build against a path that is not in the OpenAPI spec.

## Example (curl)

```bash
BASE="https://api.sms-activate.app/v1/public"
curl "$BASE/numbers/search?country=US&limit=1" -H "Authorization: Bearer $SMS_ACTIVATE_API_KEY"

curl -X POST "$BASE/numbers" \
  -H "Authorization: Bearer $SMS_ACTIVATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+15551234567","country":"US"}'

curl "$BASE/sms?limit=20" -H "Authorization: Bearer $SMS_ACTIVATE_API_KEY"
```

Always follow the OpenAPI spec at https://sms-activate.app/openapi.json for exact request and response shapes.
