# SMS Activate App API changelog

The rule: **v1 only grows.** A route, a field or an error code an integration reads is never removed, renamed or given another type inside `/v1`; new routes, fields and optional parameters are added. Anything else would be `/v2`, with `/v1` kept answering beside it. Key holders are told about new capabilities in the Telegram bot.

Documentation: https://sms-activate.app/api · OpenAPI: https://sms-activate.app/openapi.json

## 2026-11-04

- Every answer to a key carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (the tighter limit when two count the request); every `429` carries `Retry-After`; a `401` carries `WWW-Authenticate: Bearer realm="api.sms-activate.app"`. Added, nothing removed. The key's owner gets a bot message 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).
- Calls arrive as text: every call in `GET /v1/me/numbers/{id}/calls`, the `recording.ready` webhook and the live event carry `transcript`, `code` (the verification code read out in the call, or `null`) and `transcriptStatus` (`done`, `empty`, `failed`, `too_long`, `over_budget`, `off`; `null` before this day). A recording of up to one minute is transcribed when it arrives; the text stays after the audio link expires.
- A key buys a number that needs verification once the verification is approved (`POST /v1/me/number-orders` with `Idempotency-Key`, `GET`, `DELETE /v1/me/number-orders/{id}`; `409 verification_first` before), and reads the partner cabinet (`GET /v1/me/partner`, `GET /v1/me/partner/links`) and the withdrawals (`GET /v1/me/withdrawals`, `GET /v1/me/withdrawals/preview`). Filing the verification, changing the cabinet and withdrawing stay with the account's own session.
- Refused to a key (403), so a leaked key cannot outlive being revoked: `POST /v1/me/api-keys` (listing and revoking keys stay open), `POST /v1/me/password`, `POST /v1/auth/link/telegram`. No key had called any of the three in the 60 days before.

## 2026-11-02

- Inbound calls (per minute) and inbound SMS on a number are charged to the balance. `usagePricing` (`{ callCents, smsCents, advanceUsd }`) says what they cost on `GET /v1/public/countries`, on every number of `GET /v1/public/numbers/search`, and on your own numbers (`GET /v1/public/numbers`, `GET /v1/public/numbers/{id}`). A `null` figure is not known yet, never free; `usagePricing: null` means calls and SMS are not charged.
- The charges appear in `GET /v1/me/movements` as `source: "usage_charge"`, with `meta.usage_calls` and `meta.usage_sms`. With an empty balance a number keeps working up to a $1 advance; past it its inbound calls are refused until a top-up, and SMS keep arriving.

## 2026-10-28

- Account webhook tools: `POST /v1/me/webhook-secret` issues a signing secret and shows it once (`whsec_…`, the HMAC key as UTF-8 bytes), `POST /v1/me/webhook-test` sends a `webhook.test` event, and `GET /v1/me/webhook-deliveries` lists the recent deliveries without their bodies.
- A key may read `GET /v1/me/kyc` (verification status) and `GET /v1/me/transfers` (`?state=all` adds sent and received transfers with `direction` and `claimedAt`). Making, cancelling or taking a transfer and filing a verification stay with the account's own session.
- Verification events: `kyc.filed` and `kyc.decided` arrive on the account's event stream and at a verified account webhook.

## 2026-10-27

- Account routes are part of the API: the `/v1/me` routes a key already reached (calls, inbox, statement and movements, watches, top-up, buying back a released number, notification settings, release preview) now follow the same v1 rule as `/v1/public`.
- New country: the Netherlands (`NL`, mobile, SMS and calls, no documents), in `GET /v1/public/countries` and `GET /v1/public/numbers/search?country=NL`.
- `GET /v1/public/numbers/search` returns only numbers that receive SMS unless asked otherwise: `sms=any` returns voice-only numbers too. A new `type` filter (`local`, `mobile`, `tollFree`, `national`) asks for one number type, and a number sold with documents carries `verification`.

## 2026-10-17

- Only long-term numbers are sold: a new order on `/v1/public/products/*` answers `501`. What a key already holds under `/v1/public/activations` keeps its status, SMS and cancel.

## 2026-09-02

- `Idempotency-Key` is required on `POST /v1/public/numbers` and `POST /v1/public/products/order`; without it the answer is `400 validation_failed`. The one breaking change v1 has had, made to stop retries from charging twice.
