# Migrating from the SMS-Activate API: method mapping for Hush SMS

Источник: https://hush-sms.com/en/blog/migrate-from-sms-activate-api/
Обновлено: 2026-10-29

> Replacing the SMS-Activate API: what to use instead of getNumber, getStatus and setStatus in the Hush SMS REST API, order statuses, cancellation, webhooks and a no-downtime plan.

In short

The Hush SMS API is REST with JSON rather than text responses like ACCESS_NUMBER. The logic is the same: buy a number, wait for the code, finish or cancel the order. The mapping: `getNumber` → `POST /v1/numbers`, `getStatus` → `GET /v1/numbers/{id}`, `setStatus` 6 and 8 → finish and cancel. You get the key in the API section of the bot [@HushNumBot](https://t.me/HushNumBot?start=landing) or in the web account settings.

When SMS-Activate stopped working, many integrations were left without a number provider. If your code talked to the SMS-Activate handler API, moving it to Hush SMS is quick: the ideas are the same, while the addresses, the response format and a few rules change. The same mapping works for any provider built on the SMS-Activate protocol.

## What changes overall

- REST and JSON instead of one address with an `action` parameter and text responses;
- the key goes in the `Authorization: Bearer` header, not in the query string;
- a purchase needs an `Idempotency-Key` header: repeating the request with the same key returns the same order instead of buying a second number;
- codes can arrive through webhooks, not only by polling the status.

## Method mapping

| SMS-Activate | Hush SMS API |
| --- | --- |
| `getBalance` | `GET /v1/me`: profile and balance |
| `getNumber` | `POST /v1/numbers` with a `{"service", "country"}` body and an `Idempotency-Key` header |
| `getStatus` | `GET /v1/numbers/{order_id}`: status and codes; `GET /v1/orders/{order_id}/sms`: every SMS of the order |
| `setStatus`, status=6 | `POST /v1/orders/{order_id}/finish`: finish the order |
| `setStatus`, status=8 | `POST /v1/numbers/{order_id}/cancel`: cancel the order |
| `setStatus`, status=3 | No separate method; request another code in the bot or the web account |
| `getPrices`, `getNumbersStatus` | `GET /v1/services`, `GET /v1/services/{code}/countries`, `GET /v1/services/{code}/offers` |
| Active orders and history | `GET /v1/numbers` and `GET /v1/orders/history` |

## Order statuses

| SMS-Activate | Hush SMS API |
| --- | --- |
| `STATUS_WAIT_CODE` | `pending`: the number is issued, waiting for the SMS |
| `STATUS_OK:code` | `sms_received`: the code has arrived and is in the order response |
| `STATUS_CANCEL` | `canceled`, then `refunded`: the order is cancelled and the money is back on the balance |
| Order completed | `finished` |

Do not copy service codes and country IDs from the old integration blindly: take them from `GET /v1/services` and `GET /v1/services/{code}/countries`. The full reference with examples is in the [API documentation](https://docs.hush-sms.com/en/).

## Rules worth knowing

- an order can be cancelled while it has no SMS and no earlier than 2 minutes after purchase; before that the API answers `409 too_early` with the seconds left;
- on `503` and `504` responses, check the order status first and only then repeat the action on the same order;
- if the supplier's price changed during the purchase, the response includes `price_changed` and the previous price;
- prices and the balance in API responses are in rubles.

## Webhooks instead of polling

Set the webhook address in the API section of the Telegram bot. When an SMS arrives, Hush SMS sends a POST request with the code to that address, and status polling can stay as a fallback. The request format is described in the [Webhooks](https://docs.hush-sms.com/en/#webhooks) section of the docs.

## A no-downtime migration plan

1. Get an API key and top up the balance.
2. Write an adapter that turns your `getNumber`, `getStatus` and `setStatus` calls into Hush SMS methods.
3. Test the full cycle on one service: purchase, code, finish and cancel.
4. Connect webhooks and keep status polling as a fallback.
5. Send a small share of orders to the new flow, compare the results and only then switch everything.

## Frequently asked questions

### Does Hush SMS have an endpoint compatible with the SMS-Activate handler API?

No. Hush SMS has its own REST API. The easiest way to migrate is a small adapter that turns the old calls into the new methods.

### Where do I get an API key?

In the Telegram bot @HushNumBot, in the API section, or in the web account settings. Requests pass the key in the Authorization: Bearer header.

### Can I request another code through the API?

There is no separate API method for that yet. You can request another code in the bot or in the web account, if the service supports resending.

Moving an integration? Get an API key in the bot or in the web account and start with one test order.

[Key in the bot](https://t.me/HushNumBot?start=landing) [Key on the website](https://hush-sms.com/account/settings/api?lang=en)