{"openapi":"3.1.0","info":{"title":"BringSMS API","description":"\n
\n
One endpoint

Every action lives on the\nsame URL and is chosen by action=. Nothing to discover, no versions\nto follow.

\n
Drop-in protocol

Answer for answer, the\nsame protocol your software already speaks. Change the host, paste the key, keep\nyour code.

\n
Runnable page

Every operation below has\na Try it out button: call it with your own key and read the real answer, no client\nneeded.

\n
\n\n**The endpoint:**\n\n```\nGET https://api.bring-sms.store/stubs/handler_api.php?api_key=KEY&action=ACTION\nPOST https://api.bring-sms.store/stubs/handler_api.php (form-urlencoded or JSON)\n```\n\n* **Two ways to the same code.** This endpoint with `action=`, or the matching\n `/api/` URL — the second form exists so **Try it out** works right here.\n* **Already speaking the SMS-Activate protocol?** Point the host at\n `https://api.bring-sms.store`, paste the key. Nothing else to change.\n* **Every price is in RUB**, with your level discount already applied.\n\n## Quickstart\n\nGet the key in [@bringsmsbot](https://t.me/bringsmsbot) → **API**, then:\n\n```python\nimport time, requests\n\nAPI = \"https://api.bring-sms.store/stubs/handler_api.php\"\nKEY = \"YOUR_API_KEY\"\n\ndef call(action, **params):\n return requests.get(API, params={\"api_key\": KEY, \"action\": action, **params}, timeout=30)\n\nprint(call(\"getBalance\").text) # ACCESS_BALANCE:
:\n\nr = call(\"getNumber\", service=\"tg\", country=187, maxPrice=25) # Telegram, USA, max 25 RUB\nif not r.text.startswith(\"ACCESS_NUMBER\"):\n raise SystemExit(f\"purchase failed: HTTP {r.status_code} {r.text}\")\n_, activation_id, phone = r.text.split(\":\")\n\ncode, deadline = None, time.time() + 20 * 60 # 20 min: the server refunds by itself\nwhile time.time() < deadline:\n status = call(\"getStatus\", id=activation_id).text\n if status.startswith(\"STATUS_OK:\"):\n code = status.split(\":\", 1)[1]\n break\n if status == \"STATUS_CANCEL\":\n raise SystemExit(\"cancelled or expired — money already refunded\")\n time.sleep(5) # STATUS_WAIT_* — keep polling\n\ncall(\"setStatus\", id=activation_id, status=6 if code else 8) # 6 = used it, 8 = refund\n```\n\nThe last line is the one people forget, and it is what frees your\nconcurrent-activation slots.\n\n
\nSame first call in PHP / Node.js / cURL\n\n```php\n\n\n## Authorization & transport\n\n* `api_key` is required by **every** request. There are no public actions.\n* **GET and POST** both work on the main endpoint. POST accepts\n `application/x-www-form-urlencoded`, `multipart/form-data` and `application/json`.\n* Parameter aliases are accepted, so you rarely have to rename anything:\n\n| Canonical | Also accepted |\n|---|---|\n| `api_key` | `apiKey` |\n| `id` | `activationId`, `activation_id` |\n| `max_price` | `maxPrice` |\n| `fixed_price` | `fixedPrice` |\n| `phone_exception` | `phoneException` |\n| `use_bonus` | `useBonus` |\n| `time` | `rent_time`, `duration` |\n\n
A typo cannot cost you money.\nAn unknown path answers 404 with a hint, an unknown action answers\nBAD_ACTION, and neither one executes anything — a misspelled request\nnever buys a number.
\n\n## Rules & limits\n\n| Rule | Value |\n|---|---|\n| Rate limit per API key | **40 requests / second** |\n| Rate limit per IP | **2400 requests / minute** |\n| Cancellation allowed after | **2 minutes** from purchase |\n| Auto-expiry, refund, end of the free-cancel window | **20 minutes** from purchase |\n\n
Over the limit you get 429 with a\nRetry-After header. Wait exactly that long instead of retrying in a\ntight loop: a loop keeps the counter full and the ban alive.
\n\n## Error format\n\nTwo shapes exist on the wire. The array shape is inherited from the SMS-Activate\nprotocol and kept for compatibility with existing software, so **handle both**:\n\n```json\n{\"title\": \"NO_BALANCE\", \"details\": \"Payment Required. Insufficient funds.\"}\n```\n```json\n[{\"title\": \"NO_BALANCE\", \"details\": \"Insufficient funds\"}]\n```\n\nEach operation below states which shape it uses, and its `responses` block shows a\nreal example. Three lines cover every case, including the plain-text ones:\n\n```python\ndef parse_error(resp):\n \"\"\"-> (code, human_text). Works for object, array and plain-text answers.\"\"\"\n try:\n body = resp.json()\n except ValueError:\n return resp.text.strip(), resp.text.strip() # e.g. NO_ACTIVATION\n if isinstance(body, list):\n body = body[0] if body else {}\n return body.get(\"title\", \"UNKNOWN\"), body.get(\"details\", \"\")\n```\n\n
Branch on title, never on\ndetails. details is written for humans and may be\nreworded at any time; info carries machine-readable extras when they\nexist (info.min, info.field,\ninfo.retry_after).
\n\n
getStatus and\nsetStatus answer in plain text with HTTP 200 — including\nNO_ACTIVATION and WRONG_ACTIVATION_ID. That is protocol\nlegacy, not a bug: old software checks the body, not the status code. Everything else\nanswers in JSON.
\n\n
\nFull error reference — all codes, when they happen, what to do\n\n**Key & access**\n\n| Code | HTTP | When it happens | What to do |\n|---|:---:|---|---|\n| `BAD_KEY` | 401 | `api_key` not sent, unknown, or the activation belongs to another account | Take the key in [@bringsmsbot](https://t.me/bringsmsbot) → API and send it in every request |\n| `BANNED` | 403 | Account is suspended | Contact support — retrying will not help |\n| `WRONG_ACTIVATION_ID` | 403 | The `id` exists but belongs to a different account | Check the `id`. `getStatus`/`setStatus` return this as **plain text with HTTP 200** |\n\n**Limits**\n\n| Code | HTTP | When it happens | What to do |\n|---|:---:|---|---|\n| `TOO_MANY_REQUESTS` | 429 | More than 40 req/s per key or 2400 req/min per IP | Sleep for the number of seconds in the `Retry-After` header, then repeat |\n| `CHANNELS_LIMIT` | 403 | `getNumber`: concurrent activation limit for your loyalty level is reached | Close finished activations with `setStatus=6`/`8`, or raise your level |\n| `TOO_MANY_ACTIVE_ACTIVATIONS` | 403 | Same as `CHANNELS_LIMIT`, reported by `getNumberV2` | Close finished activations, then repeat |\n| `LIMIT_ERROR` | 403 | `getNumberV2`: refused because of a per-account limit | Close finished activations, then repeat |\n\n**Money**\n\n| Code | HTTP | When it happens | What to do |\n|---|:---:|---|---|\n| `NO_BALANCE` | 402 | Main balance is lower than the price of the order | Top up in the bot. `getBalance` shows main and bonus balance separately |\n\n**Request parameters**\n\n| Code | HTTP | When it happens | What to do |\n|---|:---:|---|---|\n| `BAD_ACTION` | 404 | `action` is missing or such an action does not exist | Check the spelling against the operation list on this page |\n| `UNPROCESSABLE_ENTITY` | 422 | A required parameter is missing or has the wrong type | Read `info.field` and `info.code` (`REQUIRED`, `NOT_AN_INTEGER`, `NOT_A_TIMESTAMP`) |\n| `WRONG_MAX_PRICE` | 400 / 422 | `maxPrice` is below the cheapest number (400), or is not a number at all (422) | Take the real minimum from `info.min` and raise `maxPrice` |\n| `WRONG_SERVICE` | 400 | Unknown `service` code | Take the code from `getServicesList` |\n| `BAD_STATUS` | 400 | `setStatus` received a `status` other than 1, 3, 6, 8 | See the `setStatus` table below |\n| `BAD_DURATION` | 400 | The requested number of hours is not offered for this number | Take an available value from `reactivateOptions` / `prolongOptions` |\n| `WRONG_COUNTRY_ID` | 400 | `getNumberV2`: this country ID is not recognised | Take the ID from `getCountries` |\n| `BAD_COUNTRY` | 400 | `getNumberV2`: the country exists but is not served | Pick another country from `getCountries` |\n| `WRONG_DOMAIN` | 400 | `buyEmail`: this `domain` is not offered for the requested `site` | Take a `domain` from `getEmailDomains` — the list changes during the day |\n\n**Availability**\n\n| Code | HTTP | When it happens | What to do |\n|---|:---:|---|---|\n| `NO_NUMBERS` | 400 / 404 | Nothing in stock for this service+country, or the country is not on our list | Retry in a few seconds or pick another country. `getPrices` shows the stock |\n| `NOT_AVAILABLE` | 400 | This number can no longer be reactivated — `reactivateOptions` answers this way too, instead of an empty list | Buy a new number with `getNumber` |\n| `NO_EMAILS` | 400 | `buyEmail`: the requested domain has run out of addresses | Pick another domain from `getEmailDomains` — `count` there shows the stock |\n| `SERVICE_UNAVAILABLE` | 400 | This service is temporarily disabled, or an email address / its price could not be issued right now | Retry later — this is not a problem with your request |\n| `SIM_TEMPORARY_OFFLINE` | 400 | `cancelActivation` / `reactivate` / `prolong`: the SIM is out of network | Retry in a minute; the money was not taken |\n| `ACTIVATION_NOT_AVAILABLE` | 400 | This activation cannot be operated on right now | Check the state with `getStatus` before repeating |\n\n**Activation state**\n\n| Code | HTTP | When it happens | What to do |\n|---|:---:|---|---|\n| `NO_ACTIVATION` | 404 | There is no activation with this `id` (the email operations answer the same way for an unknown email order id) | Check the `id`. `getStatus`/`setStatus` return this as **plain text with HTTP 200** |\n| `NOT_FOUND` | 404 | Same as `NO_ACTIVATION`, reported by the rent operations | Check the `id` in `getActiveActivations` |\n| `ALREADY_FINISHED` | 400 | The activation is no longer `ACTIVE` (for an email: no longer `WAIT`, and a canceled address cannot be reactivated) | Nothing to do — the operation already happened. This is not a failure |\n| `ERROR_CANCEL` | 400 | You try to cancel an activation that already received a code — or an email address that already received a letter | Close a number with `setStatus=6`; for an email there is nothing to do — a delivered code or letter is not refundable |\n| `EARLY_CANCEL_DENIED` | 425 / 400 | Cancellation attempted less than 2 minutes after purchase — the same hold applies to numbers and to email addresses. For an email you also get it while the address is still being processed and cannot be released yet: nothing is refunded and the address stays live | Wait until 2 minutes have passed, then repeat. An email address that gets no letter refunds by itself when it expires |\n| `EARLY_REACTIVATION_DENIED` | 425 | `reactivateEmail` was called on a just-bought address that is still being processed | Wait until 2 minutes have passed. Nothing was charged — extend later, when the address is about to expire or the first letter has arrived |\n| `FREE_CANCELLATION_EXPIRED` | 400 | More than 20 minutes have passed since the purchase | Nothing to do. Activations expire and refund on their own after 20 min |\n| `CANCEL_FAILED` | 400 | The cancellation was not confirmed and the number (or email address) is still live | Repeat the request; the money was not taken |\n| `IN_PROGRESS` | 400 / 429 | A previous purchase for the same account has not finished yet | Wait ~1 second and repeat. Do **not** send purchases in parallel per key |\n\n**Service & server**\n\n| Code | HTTP | When it happens | What to do |\n|---|:---:|---|---|\n| `SERVER_ERROR` | 500 / 503 / 429 | Temporary outage, timeout, or an internal failure | **Before retrying a purchase** call `getActiveActivations` — the number may already be yours |\n| `API_TIMEOUT` | 400 / 500 | The request did not complete in time | Check `getActiveActivations`, then retry |\n| `TIMEOUT` | 500 | The purchase did not fit into the timeout but may still complete | Do not retry immediately — check `getActiveActivations` first |\n| `FINISH_FAILED` | 400 | `finishActivation` on a regular number failed | Repeat, or close it with `setStatus=6` |\n| `RENT_FINISH_FAILED` | 400 | `finishActivation` on a rent failed; `details` carries the exact reason | Read `details` — it explains what exactly went wrong |\n| `REACTIVATION_FAILED` | 400 | `reactivate` / `reactivateEmail` was refused for an unclassified reason | The money is already back. Buy a fresh number or address instead |\n| `PROLONG_FAILED` | 400 | `prolong` was refused for an unclassified reason | The money is already back. Read `details` and retry if it looks transient |\n\n
\n\n## Activation statuses\n\nReturned by `getStatus` as plain text:\n\n| Response | Meaning | Your move |\n|---|---|---|\n| `STATUS_WAIT_CODE` | No SMS yet | Keep polling every 5–10 s |\n| `STATUS_OK:12345` | Code received — it is `12345` | `setStatus=6` |\n| `STATUS_WAIT_RETRY:12345` | New code requested after `setStatus=3` | Keep polling |\n| `STATUS_WAIT_RESEND` | Waiting for the SMS to be resent | Keep polling |\n| `STATUS_CANCEL` | Cancelled or expired — **money already refunded** | Stop polling |\n| `NO_ACTIVATION` | No such `id` | Fix the `id` |\n| `WRONG_ACTIVATION_ID` | The `id` belongs to another account | Fix the `id` |\n\n## setStatus codes\n\n| `status` | Meaning | When to send it |\n|:---:|---|---|\n| `1` | SMS requested | Optional. After you pressed «send code» on the site |\n| `3` | Send me another code | When the first code did not arrive or you need a second one |\n| `6` | **Done** | You used the code. Frees the slot, the charge stays |\n| `8` | **Cancel** | No code came. Frees the slot and refunds the money |\n\nAnswers: `ACCESS_READY` · `ACCESS_RETRY_GET` · `ACCESS_ACTIVATION` · `ACCESS_CANCEL`,\nor `EARLY_CANCEL_DENIED` / `ERROR_CANCEL` if cancellation is not allowed.\n\n
Closing an activation is not\noptional bookkeeping. Unclosed activations hold your concurrent slots until the\n20-minute expiry and will eventually answer CHANNELS_LIMIT to every new\npurchase.
\n\n
\nEmail addresses instead of a number\n\nSome sites can be registered with a disposable email address — cheaper than an SMS\nactivation. The flow is separate from numbers: **own ids, own statuses, own actions.**\nNever pass an email id to `getStatus` / `setStatus`.\n\n```\ngetEmailServices → getEmailDomains → buyEmail → getEmailStatus (poll)\n ↳ cancelEmail (refund)\n ↳ reactivateEmail (+20 min, paid)\n```\n\n| Step | Call | What matters |\n|---|---|---|\n| 1 | `getEmailServices` | Which `site` belongs to a service code. Static — cache it |\n| 2 | `getEmailDomains` | Live `price` and `count` per domain — read it right before buying |\n| 3 | `buyEmail` | 1…10 addresses at once. Save `data[].id` |\n| 4 | `getEmailStatus` | Poll every 3–5 s until `status` is `SUCCESS`, read `letter` |\n\n`status`: `WAIT` waiting for the letter · `SUCCESS` letter received ·\n`CANCELED` canceled or expired, **money already back**.\n\n* Not every service has addresses — `getEmailDomains` with an empty `data` means\n \"not for this site right now\", not an error.\n* An address lives **20 minutes**, then expires and refunds itself. Nothing to call.\n* `cancelEmail` refunds early, but only while no letter has arrived.\n* `reactivateEmail` is **paid** (`reactivateEmailOptions` shows the price). It also\n works after a letter arrived, when you need a second one to the same address — the\n old letter stays in `letters`.\n* Bought addresses show up in the bot too, in the same account.\n\n
\n\n
\nLoyalty levels, bonus balance and concurrency limits\n\nUp to **35%** of an order can be paid from your **bonus balance**. The level is\nrecalculated automatically from your **last 7 days** of activity:\n\n| Level | Max bonus share | Concurrent activations | Requirement (last 7 days) |\n|:---:|:---:|:---:|---|\n| 0 | **20%** | 20 | default for everyone |\n| 1 | **25%** | 100 | 100 activations **or** ₽1,500 topped up |\n| 2 | **30%** | 500 | 500 activations **or** ₽2,500 topped up |\n| 3 | **35%** | 2,000 | 2,000 activations **or** ₽10,000 topped up |\n\nBonuses are earned from daily tasks and achievements in the bot. Via API they are\nspent automatically — pass `use_bonus=0` on `getNumber` to pay from the main balance\nonly. `getBalance` returns both numbers: `ACCESS_BALANCE:
:`.\n\n
\n","version":"2.0.0"},"servers":[{"url":"https://api.bring-sms.store","description":"Production API"}],"paths":{"/api/getBalance":{"get":{"tags":["💳 Balance"],"summary":"Balance and bonus balance","description":"**Use it** as a cheap health check for your key, and before a batch of purchases.\n\nFormat: `ACCESS_BALANCE::` — both in RUB.\n\nThe second number is the bonus balance. It can cover 20–35% of an order\ndepending on your level, and it is used automatically unless you pass\n`use_bonus=0` to `getNumber`.\n\n*Errors: object form.*","operationId":"get_balance_doc_api_getBalance_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"}],"responses":{"200":{"description":"Main and bonus balance in RUB","content":{"application/json":{"schema":{}},"text/plain":{"example":"ACCESS_BALANCE:253.40:45.00"}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/getPrices":{"get":{"tags":["💰 Prices & stock"],"summary":"Price list for every service and country","description":"**Use it** to decide what to buy and to pick a sane `maxPrice`.\n\nShape: `{country_id: {service: {cost, count}}}`, `\"187\"` = USA.\n\n* `cost` — the **minimum** price available right now, in RUB, with your level\n discount already applied. This is the number `maxPrice` is compared against.\n* `count` — approximate stock. Treat it as a hint, not a guarantee.\n\nPassing `service` makes the answer live (slower, exact); without it you get the\ncached world price list (fast). Cache the result on your side — prices move\nslowly, and this call is heavier than the rest.\n\n
\n

Without country this answer is the whole world — every\ncountry times every service, megabytes of JSON in one response. Fine for a\nscript, too heavy for a browser: Try it out on this page shows only the\nfirst 200 KB of it. While you are exploring, ask for one country\n(country=187).

\n
\n\n*Errors: object form.*","operationId":"get_prices_doc_api_getPrices_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Only this country ID. Omit for the whole world","title":"Country"},"description":"Only this country ID. Omit for the whole world"},{"name":"service","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only this service code. Fetches live prices","title":"Service"},"description":"Only this service code. Fetches live prices"}],"responses":{"200":{"description":"Prices in RUB with your discount applied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FullPrices"},"example":{"187":{"tg":{"cost":13.5,"count":4210},"wa":{"cost":11.8,"count":1805}}}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/getNumbersStatus":{"get":{"tags":["💰 Prices & stock"],"summary":"Stock counts, flat map","description":"**Use it** when you only need availability and not prices — the payload is much\nsmaller than `getPrices`.\n\nShape: `{\"_\": }`, e.g. `{\"tg_187\": 4210}`.\n\n
\n

Smaller than getPrices, but still one key per service per\ncountry: without country it is a long answer, and this page shows\nonly its first 200 KB.

\n
\n\n*Errors: object form.*","operationId":"get_numbers_status_doc_api_getNumbersStatus_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Only this country ID. Omit for all","title":"Country"},"description":"Only this country ID. Omit for all"}],"responses":{"200":{"description":"Counts per service+country","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumbersStatus"},"example":{"tg_187":4210,"wa_187":1805,"tg_2":350}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/getCountries":{"get":{"tags":["📚 Catalog"],"summary":"Countries","description":"**Use it once** and cache: `{country_id: name}`. These IDs go into the `country`\nparameter everywhere. `187` is the USA. Russia (`0`) is not sold here — it is\nabsent from this list and `country=0` is rejected.\n\n*Errors: object form.*","operationId":"get_countries_doc_api_getCountries_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"}],"responses":{"200":{"description":"Country ID → name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleDict"},"example":{"187":"🇺🇸 США","2":"🇰🇿 Казахстан","6":"🇮🇩 Индонезия"}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/getServicesList":{"get":{"tags":["📚 Catalog"],"summary":"Services","description":"**Use it once** and cache. The `code` field is what goes into the `service`\nparameter of `getNumber`, `getPrices`, `getRentNumber`.\n\nUnknown codes come back as `WRONG_SERVICE`, so validate against this list\ninstead of guessing.\n\n*Errors: object form.*","operationId":"get_services_list_doc_api_getServicesList_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"}],"responses":{"200":{"description":"Service codes and names","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ServiceItem"},"title":"Response Get Services List Doc Api Getserviceslist Get"},"example":[{"code":"tg","name":"Telegram"},{"code":"wa","name":"WhatsApp"}]}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/getOperators":{"get":{"tags":["📚 Catalog"],"summary":"Mobile operators","description":"**Use it** only if you need to pin a specific carrier via the `operator`\nparameter. `any` (the default) is almost always the right choice — filtering\nby operator shrinks the pool and makes `NO_NUMBERS` more likely.\n\n*Errors: object form.*","operationId":"get_operators_doc_api_getOperators_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"}],"responses":{"200":{"description":"Operator code → name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleDict"},"example":{"any":"ЛЮБОЙ","beeline":"Beeline","mts":"MTS"}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/getNumber":{"get":{"tags":["📲 Activations"],"summary":"Buy a number","description":"**Step 2 of the flow.** Reserves a number and charges your balance immediately.\n\nAnswer: `ACCESS_NUMBER::` — plain text. Keep the\n`activation_id`, everything afterwards needs it.\n\n**Then:** poll `getStatus` every 5–10 s, and close with `setStatus=6` or `8`.\nNothing else releases the concurrent-activation slot before the 20-minute expiry.\n\n| Parameter | Behaviour |\n|---|---|\n| `maxPrice=25` | Buy only at ≤ 25 RUB. Otherwise `WRONG_MAX_PRICE`, real minimum in `info.min` |\n| `phoneException=1201,1202` | Never hand you a number starting with those digits |\n| `use_bonus=0` | Do not touch the bonus balance for this order |\n| `operator=verizon` | Only that carrier. Raises the chance of `NO_NUMBERS` |\n\n> On `SERVER_ERROR` **503** (`TIMEOUT`) the purchase may still be completing in\n> the background. Call `getActiveActivations` before retrying, or you will pay\n> for two numbers.\n\n*Errors: object form.*","operationId":"get_number_doc_api_getNumber_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"service","in":"query","required":true,"schema":{"type":"string","description":"Service code from `getServicesList`, e.g. `tg`","title":"Service"},"description":"Service code from `getServicesList`, e.g. `tg`","examples":{"ex":{"value":"tg"}}},{"name":"country","in":"query","required":false,"schema":{"type":"integer","description":"Country ID from `getCountries`. `187` = USA","default":187,"title":"Country"},"description":"Country ID from `getCountries`. `187` = USA","examples":{"ex":{"value":187}}},{"name":"operator","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pin a carrier. `any` — no filter, recommended","default":"any","title":"Operator"},"description":"Pin a carrier. `any` — no filter, recommended","examples":{"ex":{"value":"any"}}},{"name":"maxPrice","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Price ceiling in RUB. Above it you get WRONG_MAX_PRICE with the real minimum in `info.min`","title":"Maxprice"},"description":"Price ceiling in RUB. Above it you get WRONG_MAX_PRICE with the real minimum in `info.min`","examples":{"ex":{"value":25.0}}},{"name":"fixedPrice","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`true` — strict price enforcement together with maxPrice","title":"Fixedprice"},"description":"`true` — strict price enforcement together with maxPrice"},{"name":"phoneException","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated prefixes to avoid, up to 20. Example: `1201,1202`","title":"Phoneexception"},"description":"Comma-separated prefixes to avoid, up to 20. Example: `1201,1202`","examples":{"ex":{"value":"1201,1202"}}},{"name":"use_bonus","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"`1` — spend bonus balance (default), `0` — main balance only","default":1,"title":"Use Bonus"},"description":"`1` — spend bonus balance (default), `0` — main balance only"}],"responses":{"200":{"description":"Number reserved","content":{"application/json":{"schema":{}},"text/plain":{"example":"ACCESS_NUMBER:857312441:12015550123"}}},"400":{"description":"NO_NUMBERS · WRONG_MAX_PRICE · WRONG_SERVICE","content":{"application/json":{"examples":{"NO_NUMBERS":{"summary":"Nothing in stock for this service+country, or the country is not on our list","value":{"title":"NO_NUMBERS","details":"No numbers available for this service/country. Try again later."}},"WRONG_MAX_PRICE":{"summary":"`maxPrice` is below the cheapest number (400), or is not a number at all (422)","value":{"title":"WRONG_MAX_PRICE","details":"The maximum price (10.0 RUB) is less than the minimum available price (13.50 RUB).","info":{"min":13.5}}},"WRONG_SERVICE":{"summary":"Unknown `service` code","value":{"title":"WRONG_SERVICE","details":"Service 'xyz' is not supported or unavailable."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"NO_BALANCE","content":{"application/json":{"examples":{"NO_BALANCE":{"summary":"Main balance is lower than the price of the order","value":{"title":"NO_BALANCE","details":"Payment Required. Insufficient funds."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED · CHANNELS_LIMIT","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}},"CHANNELS_LIMIT":{"summary":"`getNumber`: concurrent activation limit for your loyalty level is reached","value":{"title":"CHANNELS_LIMIT","details":"You have reached the maximum number of concurrent purchases allowed for your account."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"UNPROCESSABLE_ENTITY · WRONG_MAX_PRICE","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}},"WRONG_MAX_PRICE":{"summary":"`maxPrice` is below the cheapest number (400), or is not a number at all (422)","value":{"title":"WRONG_MAX_PRICE","details":"The maximum price (10.0 RUB) is less than the minimum available price (13.50 RUB).","info":{"min":13.5}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"TOO_MANY_REQUESTS · SERVER_ERROR","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}},"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/getStatus":{"get":{"tags":["📲 Activations"],"summary":"Poll for the SMS code","description":"**Step 3 of the flow.** Poll every **5–10 seconds** until you see\n`STATUS_OK:` or `STATUS_CANCEL`.\n\n| Response | Meaning |\n|---|---|\n| `STATUS_WAIT_CODE` | No SMS yet — keep polling |\n| `STATUS_OK:12345` | Code received, it is `12345` |\n| `STATUS_WAIT_RETRY:12345` | A repeat code was requested, still waiting |\n| `STATUS_WAIT_RESEND` | Waiting for the SMS to be resent |\n| `STATUS_CANCEL` | Cancelled or expired — the money is already back |\n| `NO_ACTIVATION` | No activation with this `id` |\n| `WRONG_ACTIVATION_ID` | The `id` belongs to another account |\n\nStop after 20 minutes: at that point the activation expires and refunds by\nitself, and this call starts answering `STATUS_CANCEL`.\n\n> This operation answers **plain text with HTTP 200 in every case**, errors\n> included. It is protocol legacy kept for compatibility — check the body.","operationId":"get_status_doc_api_getStatus_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"id","in":"query","required":true,"schema":{"type":"string","description":"Activation ID from `getNumber`","title":"Id"},"description":"Activation ID from `getNumber`","examples":{"ex":{"value":"857312441"}}}],"responses":{"200":{"description":"Current state — always HTTP 200, always plain text","content":{"application/json":{"schema":{}},"text/plain":{"examples":{"waiting":{"summary":"No SMS yet — keep polling","value":"STATUS_WAIT_CODE"},"received":{"summary":"Code received","value":"STATUS_OK:12345"},"retry":{"summary":"Waiting for a repeat code after setStatus=3","value":"STATUS_WAIT_RETRY:12345"},"resend":{"summary":"Waiting for the SMS to be resent","value":"STATUS_WAIT_RESEND"},"cancelled":{"summary":"Cancelled or expired — money refunded","value":"STATUS_CANCEL"},"no_activation":{"summary":"No such id","value":"NO_ACTIVATION"},"foreign":{"summary":"The id belongs to another account","value":"WRONG_ACTIVATION_ID"}}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/setStatus":{"get":{"tags":["📲 Activations"],"summary":"Close the activation or ask for another code","description":"**Step 4 of the flow — do not skip it.** Until an activation is closed it\noccupies one of your concurrent slots, and enough of them will earn you\n`CHANNELS_LIMIT`.\n\n| `status` | Meaning | When to send |\n|:---:|---|---|\n| `1` | SMS requested | Optional, right after you triggered the send |\n| `3` | Send another code | The first code did not arrive, or you need a second one |\n| `6` | **Done** | You used the code. Charge stays, slot freed |\n| `8` | **Cancel** | No code came. Money refunded, slot freed |\n\nCancellation rules: `< 2 min` → `EARLY_CANCEL_DENIED`; a code already\nreceived → `ERROR_CANCEL` (a delivered code is not refundable); after\n20 minutes the server has already cancelled and refunded on its own.\n\n> Plain text with HTTP 200 for everything except an invalid `status`, which is\n> a JSON `BAD_STATUS` (400).","operationId":"set_status_doc_api_setStatus_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"id","in":"query","required":true,"schema":{"type":"string","description":"Activation ID","title":"Id"},"description":"Activation ID","examples":{"ex":{"value":"857312441"}}},{"name":"status","in":"query","required":true,"schema":{"type":"integer","description":"1 — SMS requested · 3 — send another code · 6 — done · 8 — cancel & refund","title":"Status"},"description":"1 — SMS requested · 3 — send another code · 6 — done · 8 — cancel & refund","examples":{"ex":{"value":6}}}],"responses":{"200":{"description":"Accepted — always HTTP 200, always plain text","content":{"application/json":{"schema":{}},"text/plain":{"examples":{"done":{"summary":"status=6 — finished","value":"ACCESS_ACTIVATION"},"cancelled":{"summary":"status=8 — cancelled and refunded","value":"ACCESS_CANCEL"},"sms_sent":{"summary":"status=1 — accepted","value":"ACCESS_READY"},"retry":{"summary":"status=3 — another code requested","value":"ACCESS_RETRY_GET"},"early":{"summary":"status=8 sooner than 2 min after purchase","value":"EARLY_CANCEL_DENIED"},"has_code":{"summary":"status=8 after a code already arrived","value":"ERROR_CANCEL"},"no_activation":{"summary":"No such id","value":"NO_ACTIVATION"},"foreign":{"summary":"The id belongs to another account","value":"WRONG_ACTIVATION_ID"}}}}},"400":{"description":"BAD_STATUS","content":{"application/json":{"examples":{"BAD_STATUS":{"summary":"`setStatus` received a `status` other than 1, 3, 6, 8","value":{"title":"BAD_STATUS","details":"Wrong status code. Valid values: 1, 3, 6, 8."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/getNumberV2":{"get":{"tags":["📲 Activations"],"summary":"Buy a number (JSON answer)","description":"Same purchase as `getNumber`, but the answer is a **JSON object** instead of\n`ACCESS_NUMBER:...`. Pick this one for new integrations; use `getNumber` if your\nsoftware already expects the classic plain-text protocol.\n\nTake `activationId` from the response and continue with `getStatusV2`.\n\n> Note the different status codes: no stock is **404** here (`getNumber` uses\n> 400), and errors arrive in the **array** form.\n\n*Errors: array form.*","operationId":"get_number_v2_doc_api_getNumberV2_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"service","in":"query","required":true,"schema":{"type":"string","description":"Service code","title":"Service"},"description":"Service code","examples":{"ex":{"value":"tg"}}},{"name":"country","in":"query","required":false,"schema":{"type":"integer","description":"Country ID. `187` = USA","default":187,"title":"Country"},"description":"Country ID. `187` = USA","examples":{"ex":{"value":187}}},{"name":"operator","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pin a carrier. `any` — no filter","default":"any","title":"Operator"},"description":"Pin a carrier. `any` — no filter","examples":{"ex":{"value":"any"}}},{"name":"maxPrice","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Price ceiling in RUB","title":"Maxprice"},"description":"Price ceiling in RUB"},{"name":"fixedPrice","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`true` — strict price enforcement","title":"Fixedprice"},"description":"`true` — strict price enforcement"},{"name":"phoneException","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated prefixes to avoid","title":"Phoneexception"},"description":"Comma-separated prefixes to avoid"},{"name":"use_bonus","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"`1` — spend bonus balance (default), `0` — no","default":1,"title":"Use Bonus"},"description":"`1` — spend bonus balance (default), `0` — no"}],"responses":{"200":{"description":"Number reserved","content":{"application/json":{"schema":{},"example":{"activationId":"857312441","phoneNumber":"12015550123","activationCost":18.5,"currency":643,"countryCode":187,"countryPhoneCode":187,"canGetAnotherSms":true,"activationTime":"2026-06-18T10:00:00+00:00","activationOperator":"any"}}}},"400":{"description":"SERVICE_UNAVAILABLE · WRONG_COUNTRY_ID · BAD_COUNTRY · IN_PROGRESS · WRONG_MAX_PRICE","content":{"application/json":{"examples":{"SERVICE_UNAVAILABLE":{"summary":"This service is temporarily disabled, or an email address / its price could not be issued right now","value":[{"title":"SERVICE_UNAVAILABLE","details":"Service is currently unavailable"}]},"WRONG_COUNTRY_ID":{"summary":"`getNumberV2`: this country ID is not recognised","value":[{"title":"WRONG_COUNTRY_ID","details":"Country not found"}]},"BAD_COUNTRY":{"summary":"`getNumberV2`: the country exists but is not served","value":[{"title":"BAD_COUNTRY","details":"Country not found or not supported"}]},"IN_PROGRESS":{"summary":"A previous purchase for the same account has not finished yet","value":[{"title":"IN_PROGRESS","details":"Another request is already in progress, retry in a moment"}]},"WRONG_MAX_PRICE":{"summary":"`maxPrice` is below the cheapest number (400), or is not a number at all (422)","value":[{"title":"WRONG_MAX_PRICE","details":"The maximum price (10.0 RUB) is less than the minimum available price (13.50 RUB).","info":{"min":13.5}}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 400 Get Number V2 Doc Api Getnumberv2 Get"}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"NO_BALANCE","content":{"application/json":{"examples":{"NO_BALANCE":{"summary":"Main balance is lower than the price of the order","value":[{"title":"NO_BALANCE","details":"Payment Required. Insufficient funds."}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 402 Get Number V2 Doc Api Getnumberv2 Get"}}}},"403":{"description":"BANNED · TOO_MANY_ACTIVE_ACTIVATIONS · LIMIT_ERROR","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}},"TOO_MANY_ACTIVE_ACTIVATIONS":{"summary":"Same as `CHANNELS_LIMIT`, reported by `getNumberV2`","value":[{"title":"TOO_MANY_ACTIVE_ACTIVATIONS","details":"Too many active activations"}]},"LIMIT_ERROR":{"summary":"`getNumberV2`: refused because of a per-account limit","value":[{"title":"LIMIT_ERROR","details":"Active activation limit reached for your account"}]}}}}},"404":{"description":"NO_NUMBERS","content":{"application/json":{"examples":{"NO_NUMBERS":{"summary":"Nothing in stock for this service+country, or the country is not on our list","value":[{"title":"NO_NUMBERS","details":"No numbers available for this service/country. Try again later."}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 404 Get Number V2 Doc Api Getnumberv2 Get"}}}},"422":{"description":"UNPROCESSABLE_ENTITY","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":[{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 422 Get Number V2 Doc Api Getnumberv2 Get"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR · API_TIMEOUT · TIMEOUT","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}},"API_TIMEOUT":{"summary":"The request did not complete in time","value":[{"title":"API_TIMEOUT","details":"Request timed out"}]},"TIMEOUT":{"summary":"The purchase did not fit into the timeout but may still complete","value":[{"title":"TIMEOUT","details":"Request timed out, please retry"}]}}}}}}}},"/api/getStatusV2":{"get":{"tags":["📲 Activations"],"summary":"Poll for the SMS code (JSON answer)","description":"Structured version of `getStatus`. Poll every 5–10 s; the code appears in\n`sms.code`.\n\nUnlike `getStatus`, a missing or foreign `id` here is a real HTTP error\n(404 / 403), so you can rely on status codes.\n\n> Cancelled and finished activations answer with plain text `STATUS_CANCEL` —\n> handle a non-JSON body.\n\n*Errors: array form.*","operationId":"get_status_v2_doc_api_getStatusV2_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"id","in":"query","required":true,"schema":{"type":"string","description":"Activation ID","title":"Id"},"description":"Activation ID","examples":{"ex":{"value":"857312441"}}}],"responses":{"200":{"description":"Current state","content":{"application/json":{"schema":{},"examples":{"waiting":{"summary":"No SMS yet","value":{"verificationType":2,"sms":{"dateTime":"0000-00-00 00:00:00"}}},"received":{"summary":"Code received","value":{"verificationType":2,"sms":{"dateTime":"2026-06-18 10:15:30","code":"12345","text":"12345"}}},"cancelled":{"summary":"Cancelled — plain text, not JSON","value":"STATUS_CANCEL"}}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED · WRONG_ACTIVATION_ID","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}},"WRONG_ACTIVATION_ID":{"summary":"The `id` exists but belongs to a different account","value":[{"title":"WRONG_ACTIVATION_ID","details":"Activation belongs to another user"}]}}}}},"404":{"description":"NO_ACTIVATION","content":{"application/json":{"examples":{"NO_ACTIVATION":{"summary":"There is no activation with this `id` (the email operations answer the same way for an unknown email order id)","value":[{"title":"NO_ACTIVATION","details":"Activation Not Found"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 404 Get Status V2 Doc Api Getstatusv2 Get"}}}},"422":{"description":"UNPROCESSABLE_ENTITY","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":[{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 422 Get Status V2 Doc Api Getstatusv2 Get"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/getActiveActivations":{"get":{"tags":["📲 Activations"],"summary":"Your unfinished activations","description":"**Use it to recover after a network failure.** If a purchase timed out or you\nlost the `activation_id`, call this **before** buying again — the number may\nalready be reserved and paid for.\n\nAlso the honest answer to «how many slots am I using» when you keep hitting\n`CHANNELS_LIMIT`.\n\n`activationStatus`: `3` waiting for SMS · `4` SMS received · `6` finished ·\n`8` cancelled.\n\n*Errors: object form.*","operationId":"get_active_activations_doc_api_getActiveActivations_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"start","in":"query","required":false,"schema":{"type":"integer","description":"Offset","default":0,"title":"Start"},"description":"Offset"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","description":"Page size, max 100","default":100,"title":"Limit"},"description":"Page size, max 100"}],"responses":{"200":{"description":"Activations still open","content":{"application/json":{"schema":{},"example":{"status":"OK","data":[{"activationId":"857312441","serviceCode":"tg","phoneNumber":"12015550123","activationCost":18.5,"activationStatus":"3","activationTime":"2026-06-18T10:00:00+00:00","discount":"0.00","repeated":"0","countryCode":187,"countryName":"🇺🇸 США","canGetAnotherSms":"1","currency":643}]}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/getHistory":{"get":{"tags":["📲 Activations"],"summary":"Activation history","description":"**Use it** for reconciliation and reporting: what was bought, what it cost,\nwhich code arrived.\n\n`status`: `3` was waiting · `6` finished · `8` cancelled and refunded.\n\n`start` and `end` are unix timestamps (seconds). Anything that is not an\ninteger comes back as `UNPROCESSABLE_ENTITY` with `info.code = NOT_A_TIMESTAMP`.\n\n*Errors: object form.*","operationId":"get_history_doc_api_getHistory_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"start","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"From this unix timestamp","title":"Start"},"description":"From this unix timestamp"},{"name":"end","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"To this unix timestamp","title":"End"},"description":"To this unix timestamp"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","description":"Offset","default":0,"title":"Offset"},"description":"Offset"},{"name":"size","in":"query","required":false,"schema":{"type":"integer","description":"Page size, 1…100","default":20,"title":"Size"},"description":"Page size, 1…100"}],"responses":{"200":{"description":"Past activations, newest first","content":{"application/json":{"schema":{},"example":[{"id":"857312441","date":"2026-06-18 10:00:00","phone":"12015550123","sms":"12345","cost":18.5,"status":"6","currency":643}]}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"UNPROCESSABLE_ENTITY","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/getRentNumber":{"get":{"tags":["📅 Rent"],"summary":"Rent a number for N hours","description":"**Use it** when one code is not enough: a rented number keeps receiving SMS for\nthe whole period, and you read them with `getAllSms`.\n\nCheck the offered durations first — `serviceCountRent` (by service) or\n`getRentServicesAndCountries` (by country). An hour count that is not offered\ncomes back as `NO_NUMBERS`, not as a price error.\n\n`activationEndTime` in the answer is when the rent expires. Before that you can\n`prolong` it; afterwards only `reactivate` may help.\n\n> Watch the error shape here: parameter and country problems arrive as an\n> **object**, service problems as an **array**. Use the snippet from the\n> overview and you do not have to care.","operationId":"get_rent_number_doc_api_getRentNumber_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"service","in":"query","required":true,"schema":{"type":"string","description":"Service code","title":"Service"},"description":"Service code","examples":{"ex":{"value":"tg"}}},{"name":"country","in":"query","required":false,"schema":{"type":"integer","description":"Country ID. `187` = USA","default":187,"title":"Country"},"description":"Country ID. `187` = USA","examples":{"ex":{"value":187}}},{"name":"time","in":"query","required":false,"schema":{"type":"integer","description":"Rent duration in hours. Must match an offered option","default":4,"title":"Time"},"description":"Rent duration in hours. Must match an offered option","examples":{"ex":{"value":4}}},{"name":"operator","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Carrier filter. `any` — no filter","default":"any","title":"Operator"},"description":"Carrier filter. `any` — no filter","examples":{"ex":{"value":"any"}}}],"responses":{"200":{"description":"Number rented","content":{"application/json":{"schema":{},"example":{"activationId":"12345","phoneNumber":"79991234567","activationCost":15.5,"currency":643,"countryCode":0,"countryPhoneCode":0,"canGetAnotherSms":true,"activationTime":"2026-06-16T10:00:00+00:00","activationEndTime":"2026-06-16T14:00:00+00:00","activationOperator":"any"}}}},"400":{"description":"NO_NUMBERS · NO_BALANCE · SERVICE_UNAVAILABLE · API_TIMEOUT","content":{"application/json":{"examples":{"NO_NUMBERS":{"summary":"Nothing in stock for this service+country, or the country is not on our list","value":{"title":"NO_NUMBERS","details":"No numbers available for this service/country. Try again later."}},"NO_NUMBERS (array form)":{"summary":"Nothing in stock for this service+country, or the country is not on our list","value":[{"title":"NO_NUMBERS","details":"No numbers available for this service/country. Try again later."}]},"NO_BALANCE":{"summary":"Main balance is lower than the price of the order","value":[{"title":"NO_BALANCE","details":"Payment Required. Insufficient funds."}]},"SERVICE_UNAVAILABLE":{"summary":"This service is temporarily disabled, or an email address / its price could not be issued right now","value":[{"title":"SERVICE_UNAVAILABLE","details":"Service is currently unavailable"}]},"API_TIMEOUT":{"summary":"The request did not complete in time","value":[{"title":"API_TIMEOUT","details":"Request timed out"}]}}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"UNPROCESSABLE_ENTITY","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/getAllSms":{"get":{"tags":["🔁 Manage a number"],"summary":"Every SMS received by a number","description":"Returns every message delivered to the number, as-is.\n\n**Use it** for rent — that is where several messages arrive — but it also\naccepts a regular activation id, and then it is the way to see the full text\nof the SMS instead of just the code from `getStatus`.\n\nPoll it on the same 5–10 s rhythm as `getStatus`. New messages are appended,\nso remember the last one you processed.\n\n*Errors: array form.*","operationId":"get_all_sms_doc_api_getAllSms_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"id","in":"query","required":true,"schema":{"type":"string","description":"Activation or rent ID","title":"Id"},"description":"Activation or rent ID","examples":{"ex":{"value":"12345"}}}],"responses":{"200":{"description":"Messages received so far","content":{"application/json":{"schema":{},"example":[{"date":"2026-06-16 10:05:00","sender":"Telegram","text":"Code 12345"}]}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}},"BAD_KEY (array form)":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":[{"title":"BAD_KEY","details":"Unauthorized"}]}}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"examples":{"NOT_FOUND":{"summary":"Same as `NO_ACTIVATION`, reported by the rent operations","value":[{"title":"NOT_FOUND","details":"Activation not found"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 404 Get All Sms Doc Api Getallsms Get"}}}},"422":{"description":"UNPROCESSABLE_ENTITY","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":[{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 422 Get All Sms Doc Api Getallsms Get"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}},"SERVER_ERROR (array form)":{"summary":"Temporary outage, timeout, or an internal failure","value":[{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}]}}}}}}}},"/api/serviceCountRent":{"get":{"tags":["📅 Rent"],"summary":"Rent options for a service","description":"**Call this before `getRentNumber`.** It tells you which hour counts exist and\nwhat they cost, so you never guess a `time` value that is not on offer.\n\nShape: `countryId → hours → {price, count}`. The keys of the inner object are\nexactly the values allowed in `time`.\n\n*Errors: array form.*","operationId":"service_count_rent_doc_api_serviceCountRent_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"service","in":"query","required":true,"schema":{"type":"string","description":"Service code","title":"Service"},"description":"Service code","examples":{"ex":{"value":"tg"}}},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Only this country ID","title":"Country"},"description":"Only this country ID"},{"name":"operator","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Carrier filter. `any` — no filter","default":"any","title":"Operator"},"description":"Carrier filter. `any` — no filter","examples":{"ex":{"value":"any"}}}],"responses":{"200":{"description":"countryId → hours → {price, count}","content":{"application/json":{"schema":{},"example":{"187":{"4":{"price":15.5,"count":12},"8":{"price":28.0,"count":5}}}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"UNPROCESSABLE_ENTITY","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":[{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 422 Service Count Rent Doc Api Servicecountrent Get"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}},"SERVER_ERROR (array form)":{"summary":"Temporary outage, timeout, or an internal failure","value":[{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}]}}}}}}}},"/api/getRentServicesAndCountries":{"get":{"tags":["📅 Rent"],"summary":"Rent options for a country","description":"The mirror image of `serviceCountRent`: you fix the country and the duration,\nand get back everything rentable there.\n\n**Use it** to build a «what can I rent in this country» picker. A zero or\nnegative `time` is `BAD_DURATION`.\n\n*Errors: array form.*","operationId":"get_rent_services_and_countries_doc_api_getRentServicesAndCountries_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"country","in":"query","required":true,"schema":{"type":"integer","description":"Country ID","title":"Country"},"description":"Country ID","examples":{"ex":{"value":0}}},{"name":"time","in":"query","required":false,"schema":{"type":"integer","description":"Rent duration in hours, positive integer","default":4,"title":"Time"},"description":"Rent duration in hours, positive integer","examples":{"ex":{"value":4}}}],"responses":{"200":{"description":"Services, operators and prices available for rent","content":{"application/json":{"schema":{},"example":{"services":{"tg":{"cost":15.5,"count":12}},"operators":["any","mts"]}}}},"400":{"description":"BAD_DURATION","content":{"application/json":{"examples":{"BAD_DURATION":{"summary":"The requested number of hours is not offered for this number","value":[{"title":"BAD_DURATION","details":"Duration not available"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 400 Get Rent Services And Countries Doc Api Getrentservicesandcountries Get"}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"UNPROCESSABLE_ENTITY","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":[{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 422 Get Rent Services And Countries Doc Api Getrentservicesandcountries Get"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}},"SERVER_ERROR (array form)":{"summary":"Temporary outage, timeout, or an internal failure","value":[{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}]}}}}}}}},"/api/prolongOptions":{"get":{"tags":["📅 Rent"],"summary":"Prolong prices for an active rent","description":"**Call this before `prolong`.** The `hours` values it returns are the only ones\n`prolong` accepts — anything else is `BAD_DURATION`.\n\n`price` is the final amount in RUB with your discount already applied: exactly\nwhat `prolong` will charge for that option.\n\nRent only. For a regular activation the answer is an empty list — an ordinary\nnumber cannot be extended, only brought back with `reactivate`.\n\n*Errors: array form.*","operationId":"prolong_options_doc_api_prolongOptions_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"id","in":"query","required":true,"schema":{"type":"string","description":"Active rent ID","title":"Id"},"description":"Active rent ID","examples":{"ex":{"value":"12345"}}}],"responses":{"200":{"description":"Durations and prices you may prolong by","content":{"application/json":{"schema":{},"example":[{"hours":4,"price":15.5},{"hours":8,"price":28.0}]}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}},"BAD_KEY (array form)":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":[{"title":"BAD_KEY","details":"Unauthorized"}]}}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"examples":{"NOT_FOUND":{"summary":"Same as `NO_ACTIVATION`, reported by the rent operations","value":[{"title":"NOT_FOUND","details":"Activation not found"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 404 Prolong Options Doc Api Prolongoptions Get"}}}},"422":{"description":"UNPROCESSABLE_ENTITY","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":[{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 422 Prolong Options Doc Api Prolongoptions Get"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}},"SERVER_ERROR (array form)":{"summary":"Temporary outage, timeout, or an internal failure","value":[{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}]}}}}}}}},"/api/prolong":{"get":{"tags":["📅 Rent"],"summary":"Prolong an active rent","description":"Extends a rent that is **still active**, keeping the same phone number. Take\n`duration` from `prolongOptions`.\n\nThe answer carries a new `activationId` and the new `activationEndTime` — use\nthe new id afterwards.\n\n> The charge happens before the operation is executed. If it then fails,\n> the money is refunded automatically and you get `SERVER_ERROR` (503) or\n> `PROLONG_FAILED` — you never pay for a failed prolong.\n\n*Errors: array form.*","operationId":"prolong_doc_api_prolong_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"id","in":"query","required":true,"schema":{"type":"string","description":"Active rent ID","title":"Id"},"description":"Active rent ID","examples":{"ex":{"value":"12345"}}},{"name":"duration","in":"query","required":false,"schema":{"type":"integer","description":"Extra hours. Must be one of `prolongOptions`","default":4,"title":"Duration"},"description":"Extra hours. Must be one of `prolongOptions`","examples":{"ex":{"value":4}}}],"responses":{"200":{"description":"Rent prolonged","content":{"application/json":{"schema":{},"example":{"activationId":"12345","phoneNumber":"79991234567","activationCost":15.5,"currency":643,"countryCode":0,"countryPhoneCode":0,"canGetAnotherSms":true,"activationTime":"2026-06-16T14:00:00+00:00","activationEndTime":"2026-06-16T18:00:00+00:00","activationOperator":"any"}}}},"400":{"description":"BAD_DURATION · SIM_TEMPORARY_OFFLINE · ACTIVATION_NOT_AVAILABLE · PROLONG_FAILED","content":{"application/json":{"examples":{"BAD_DURATION":{"summary":"The requested number of hours is not offered for this number","value":[{"title":"BAD_DURATION","details":"Duration not available"}]},"SIM_TEMPORARY_OFFLINE":{"summary":"`cancelActivation` / `reactivate` / `prolong`: the SIM is out of network","value":[{"title":"SIM_TEMPORARY_OFFLINE","details":"SIM is temporarily offline. Try again later."}]},"ACTIVATION_NOT_AVAILABLE":{"summary":"This activation cannot be operated on right now","value":[{"title":"ACTIVATION_NOT_AVAILABLE","details":"Activation is not available for cancellation."}]},"PROLONG_FAILED":{"summary":"`prolong` was refused for an unclassified reason","value":[{"title":"PROLONG_FAILED","details":"The request was refused. Your balance has been refunded."}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 400 Prolong Doc Api Prolong Get"}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}},"BAD_KEY (array form)":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":[{"title":"BAD_KEY","details":"Unauthorized"}]}}}}},"402":{"description":"NO_BALANCE","content":{"application/json":{"examples":{"NO_BALANCE":{"summary":"Main balance is lower than the price of the order","value":[{"title":"NO_BALANCE","details":"Payment Required. Insufficient funds."}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 402 Prolong Doc Api Prolong Get"}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"examples":{"NOT_FOUND":{"summary":"Same as `NO_ACTIVATION`, reported by the rent operations","value":[{"title":"NOT_FOUND","details":"Activation not found"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 404 Prolong Doc Api Prolong Get"}}}},"422":{"description":"UNPROCESSABLE_ENTITY","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":[{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 422 Prolong Doc Api Prolong Get"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":[{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 503 Prolong Doc Api Prolong Get"}}}}}}},"/api/reactivateOptions":{"get":{"tags":["🔁 Manage a number"],"summary":"Reactivation prices for a number you already used","description":"**Call this before `reactivate`.**\n\n`price` is the final amount in RUB with your discount already applied: exactly\nwhat `reactivate` will charge for that option.\n\n| The id belongs to | You get |\n|---|---|\n| a rent | every duration on offer; use one of them as `duration` |\n| a regular activation | one option with `hours: 0` — `duration` is ignored there |\n\nNothing on offer is reported as an error, not as an empty list, so you can tell\nthe two cases apart: `NOT_AVAILABLE` (400) means this number cannot be brought\nback — buy a new one with `getNumber`; `SERVER_ERROR` (503) means we could not\nget an answer in time — repeat the same call in a few seconds.\n\n*Errors: array form.*","operationId":"reactivate_options_doc_api_reactivateOptions_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"id","in":"query","required":true,"schema":{"type":"string","description":"Old activation or rent ID","title":"Id"},"description":"Old activation or rent ID","examples":{"ex":{"value":"12345"}}}],"responses":{"200":{"description":"Durations and prices you may reactivate for","content":{"application/json":{"schema":{},"example":[{"hours":4,"price":17.0},{"hours":12,"price":41.0}]}}},"400":{"description":"NOT_AVAILABLE","content":{"application/json":{"examples":{"NOT_AVAILABLE":{"summary":"This number can no longer be reactivated — `reactivateOptions` answers this way too, instead of an empty list","value":[{"title":"NOT_AVAILABLE","details":"Reactivation unavailable"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 400 Reactivate Options Doc Api Reactivateoptions Get"}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}},"BAD_KEY (array form)":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":[{"title":"BAD_KEY","details":"Unauthorized"}]}}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"examples":{"NOT_FOUND":{"summary":"Same as `NO_ACTIVATION`, reported by the rent operations","value":[{"title":"NOT_FOUND","details":"Activation not found"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 404 Reactivate Options Doc Api Reactivateoptions Get"}}}},"422":{"description":"UNPROCESSABLE_ENTITY","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":[{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 422 Reactivate Options Doc Api Reactivateoptions Get"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":[{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 503 Reactivate Options Doc Api Reactivateoptions Get"}}}}}}},"/api/reactivate":{"get":{"tags":["🔁 Manage a number"],"summary":"Take back a number you used before","description":"**Use it** when you need *the same* phone number again — re-login, a second\ncode, an account recovery. Works both for finished rents and for ordinary\nactivations.\n\nDifference from `prolong`: `prolong` extends a rent that has not expired yet,\n`reactivate` brings back one that already ended. If the number is gone for good\nyou get `NOT_AVAILABLE` — buy a new one with `getNumber`.\n\n> Same money guarantee as `prolong`: if the operation fails the charge is\n> refunded automatically.\n\n*Errors: array form.*","operationId":"reactivate_doc_api_reactivate_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"id","in":"query","required":true,"schema":{"type":"string","description":"Old activation ID — a rent or a regular activation","title":"Id"},"description":"Old activation ID — a rent or a regular activation","examples":{"ex":{"value":"12345"}}},{"name":"duration","in":"query","required":false,"schema":{"type":"integer","description":"Hours. Must be one of `reactivateOptions` (rent only)","default":4,"title":"Duration"},"description":"Hours. Must be one of `reactivateOptions` (rent only)","examples":{"ex":{"value":4}}}],"responses":{"200":{"description":"Number reactivated","content":{"application/json":{"schema":{},"example":{"activationId":"12346","phoneNumber":"79991234567","activationCost":17.0,"currency":643,"countryCode":0,"countryPhoneCode":0,"canGetAnotherSms":true,"activationTime":"2026-06-17T09:00:00+00:00","activationEndTime":"2026-06-17T13:00:00+00:00","activationOperator":"any"}}}},"400":{"description":"BAD_DURATION · NOT_AVAILABLE · SIM_TEMPORARY_OFFLINE · ACTIVATION_NOT_AVAILABLE · REACTIVATION_FAILED","content":{"application/json":{"examples":{"BAD_DURATION":{"summary":"The requested number of hours is not offered for this number","value":[{"title":"BAD_DURATION","details":"Duration not available"}]},"NOT_AVAILABLE":{"summary":"This number can no longer be reactivated — `reactivateOptions` answers this way too, instead of an empty list","value":[{"title":"NOT_AVAILABLE","details":"Reactivation unavailable"}]},"SIM_TEMPORARY_OFFLINE":{"summary":"`cancelActivation` / `reactivate` / `prolong`: the SIM is out of network","value":[{"title":"SIM_TEMPORARY_OFFLINE","details":"SIM is temporarily offline. Try again later."}]},"ACTIVATION_NOT_AVAILABLE":{"summary":"This activation cannot be operated on right now","value":[{"title":"ACTIVATION_NOT_AVAILABLE","details":"Activation is not available for cancellation."}]},"REACTIVATION_FAILED":{"summary":"`reactivate` / `reactivateEmail` was refused for an unclassified reason","value":[{"title":"REACTIVATION_FAILED","details":"The request was refused. Your balance has been refunded."}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 400 Reactivate Doc Api Reactivate Get"}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}},"BAD_KEY (array form)":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":[{"title":"BAD_KEY","details":"Unauthorized"}]}}}}},"402":{"description":"NO_BALANCE","content":{"application/json":{"examples":{"NO_BALANCE":{"summary":"Main balance is lower than the price of the order","value":[{"title":"NO_BALANCE","details":"Payment Required. Insufficient funds."}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 402 Reactivate Doc Api Reactivate Get"}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"examples":{"NOT_FOUND":{"summary":"Same as `NO_ACTIVATION`, reported by the rent operations","value":[{"title":"NOT_FOUND","details":"Activation not found"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 404 Reactivate Doc Api Reactivate Get"}}}},"422":{"description":"UNPROCESSABLE_ENTITY","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":[{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 422 Reactivate Doc Api Reactivate Get"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":[{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 503 Reactivate Doc Api Reactivate Get"}}}}}}},"/api/cancelActivation":{"get":{"tags":["🔁 Manage a number"],"summary":"Cancel a number and get the money back","description":"Cancels a number you own and **refunds it automatically**. The `refund` field\nshows exactly how much came back, in RUB. Accepts both a regular activation and\na rent id.\n\nFor a **regular activation**:\n\n| Time since purchase | Result |\n|---|---|\n| 0 – 2 min | `EARLY_CANCEL_DENIED` (425) — too early |\n| 2 – 20 min | free cancellation, money back |\n| after 20 min | `FREE_CANCELLATION_EXPIRED` (400) — the server already refunded it |\n\nA code that already arrived cannot be refunded: that is `ERROR_CANCEL`.\n`ALREADY_FINISHED` means someone got there first — it is not a failure.\n\nFor a **rent** the same errors apply, but the window is decided when you ask:\nif it can no longer be cancelled you get `FREE_CANCELLATION_EXPIRED`,\n`ACTIVATION_NOT_AVAILABLE` or `SIM_TEMPORARY_OFFLINE`, and nothing is charged.\n\n
The refund is written only\nafter the cancellation is confirmed. If it does not confirm you get\nCANCEL_FAILED and the number stays live — retry.
\n\n*Errors: array form.*","operationId":"cancel_activation_doc_api_cancelActivation_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"id","in":"query","required":true,"schema":{"type":"string","description":"Rent or activation ID","title":"Id"},"description":"Rent or activation ID","examples":{"ex":{"value":"12345"}}}],"responses":{"200":{"description":"Cancelled, balance refunded","content":{"application/json":{"schema":{},"example":{"status":"success","message":"Activation canceled","refund":15.5}}}},"400":{"description":"ALREADY_FINISHED · ERROR_CANCEL · FREE_CANCELLATION_EXPIRED · ACTIVATION_NOT_AVAILABLE · SIM_TEMPORARY_OFFLINE · CANCEL_FAILED","content":{"application/json":{"examples":{"ALREADY_FINISHED":{"summary":"The activation is no longer `ACTIVE` (for an email: no longer `WAIT`, and a canceled address cannot be reactivated)","value":[{"title":"ALREADY_FINISHED","details":"Activation is already finished or canceled"}]},"ERROR_CANCEL":{"summary":"You try to cancel an activation that already received a code — or an email address that already received a letter","value":[{"title":"ERROR_CANCEL","details":"Cannot cancel after SMS code received."}]},"FREE_CANCELLATION_EXPIRED":{"summary":"More than 20 minutes have passed since the purchase","value":[{"title":"FREE_CANCELLATION_EXPIRED","details":"Free cancellation window has expired (20 minutes). Cancellation is no longer possible."}]},"ACTIVATION_NOT_AVAILABLE":{"summary":"This activation cannot be operated on right now","value":[{"title":"ACTIVATION_NOT_AVAILABLE","details":"Activation is not available for cancellation."}]},"SIM_TEMPORARY_OFFLINE":{"summary":"`cancelActivation` / `reactivate` / `prolong`: the SIM is out of network","value":[{"title":"SIM_TEMPORARY_OFFLINE","details":"SIM is temporarily offline. Try again later."}]},"CANCEL_FAILED":{"summary":"The cancellation was not confirmed and the number (or email address) is still live","value":[{"title":"CANCEL_FAILED","details":"Cancellation was not confirmed. Number is still active."}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 400 Cancel Activation Doc Api Cancelactivation Get"}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}},"BAD_KEY (array form)":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":[{"title":"BAD_KEY","details":"Unauthorized"}]}}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"examples":{"NOT_FOUND":{"summary":"Same as `NO_ACTIVATION`, reported by the rent operations","value":[{"title":"NOT_FOUND","details":"Activation not found"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 404 Cancel Activation Doc Api Cancelactivation Get"}}}},"422":{"description":"UNPROCESSABLE_ENTITY","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":[{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 422 Cancel Activation Doc Api Cancelactivation Get"}}}},"425":{"description":"EARLY_CANCEL_DENIED","content":{"application/json":{"examples":{"EARLY_CANCEL_DENIED":{"summary":"Cancellation attempted less than 2 minutes after purchase — the same hold applies to numbers and to email addresses. For an email you also get it while the address is still being processed and cannot be released yet: nothing is refunded and the address stays live","value":[{"title":"EARLY_CANCEL_DENIED","details":"Too early to cancel. Please wait 2 minutes after purchase."}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 425 Cancel Activation Doc Api Cancelactivation Get"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}},"SERVER_ERROR (array form)":{"summary":"Temporary outage, timeout, or an internal failure","value":[{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}]}}}}}}}},"/api/finishActivation":{"get":{"tags":["🔁 Manage a number"],"summary":"Close a number without a refund","description":"Closes a number you are done with, **without a refund**. Accepts both a regular\nactivation and a rent id — for a regular activation it does exactly the same as\n`setStatus` with `status=6`, for a rent it ends the rent early.\n\nUse `cancelActivation` if you want the money back instead. `ALREADY_FINISHED`\njust means it was closed earlier.\n\n*Errors: array form.*","operationId":"finish_activation_doc_api_finishActivation_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"id","in":"query","required":true,"schema":{"type":"string","description":"Rent or activation ID","title":"Id"},"description":"Rent or activation ID","examples":{"ex":{"value":"12345"}}}],"responses":{"200":{"description":"Finished","content":{"application/json":{"schema":{},"example":{"status":"success","message":"Activation finished"}}}},"400":{"description":"ALREADY_FINISHED · FINISH_FAILED · RENT_FINISH_FAILED","content":{"application/json":{"examples":{"ALREADY_FINISHED":{"summary":"The activation is no longer `ACTIVE` (for an email: no longer `WAIT`, and a canceled address cannot be reactivated)","value":[{"title":"ALREADY_FINISHED","details":"Activation is already finished or canceled"}]},"FINISH_FAILED":{"summary":"`finishActivation` on a regular number failed","value":[{"title":"FINISH_FAILED","details":"Failed to finish activation"}]},"RENT_FINISH_FAILED":{"summary":"`finishActivation` on a rent failed; `details` carries the exact reason","value":[{"title":"RENT_FINISH_FAILED","details":"Rent is not active"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 400 Finish Activation Doc Api Finishactivation Get"}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}},"BAD_KEY (array form)":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":[{"title":"BAD_KEY","details":"Unauthorized"}]}}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"examples":{"NOT_FOUND":{"summary":"Same as `NO_ACTIVATION`, reported by the rent operations","value":[{"title":"NOT_FOUND","details":"Activation not found"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 404 Finish Activation Doc Api Finishactivation Get"}}}},"422":{"description":"UNPROCESSABLE_ENTITY","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":[{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 422 Finish Activation Doc Api Finishactivation Get"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}},"SERVER_ERROR (array form)":{"summary":"Temporary outage, timeout, or an internal failure","value":[{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}]}}}}}}}},"/api/prolongHistory":{"get":{"tags":["📅 Rent"],"summary":"Prolong history of a rent","description":"Every extension of a rented number: what was paid and how many hours were added.\n**Use it** for reconciliation when a rent has been prolonged several times.\n\n`payerType` is always `client` for user-initiated extensions. If there is\nnothing to report, the answer is an empty `{\"data\": []}` rather than an error.\n\n*Errors: array form.*","operationId":"prolong_history_doc_api_prolongHistory_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"id","in":"query","required":true,"schema":{"type":"string","description":"Rent activation ID","title":"Id"},"description":"Rent activation ID","examples":{"ex":{"value":"12345"}}}],"responses":{"200":{"description":"Extensions of this number","content":{"application/json":{"schema":{},"example":{"data":[{"userPrice":15.5,"hours":4,"createDate":"2026-06-18T10:00:00+00:00","payerType":"client"}]}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED · WRONG_ACTIVATION_ID","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}},"WRONG_ACTIVATION_ID":{"summary":"The `id` exists but belongs to a different account","value":[{"title":"WRONG_ACTIVATION_ID","details":"Activation belongs to another user"}]}}}}},"404":{"description":"NO_ACTIVATION","content":{"application/json":{"examples":{"NO_ACTIVATION":{"summary":"There is no activation with this `id` (the email operations answer the same way for an unknown email order id)","value":[{"title":"NO_ACTIVATION","details":"Activation Not Found"}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 404 Prolong History Doc Api Prolonghistory Get"}}}},"422":{"description":"UNPROCESSABLE_ENTITY","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":[{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 422 Prolong History Doc Api Prolonghistory Get"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/getEmailServices":{"get":{"tags":["📧 Email addresses"],"summary":"Service codes and their sites","description":"**Start here.** A reference list: which `site` to use for each service code.\n\n* `service` — the same code you use for numbers.\n* `site` — pass it to `getEmailDomains` / `buyEmail`.\n\nTwo things worth knowing:\n\n1. **Not every service has email addresses.** This list maps codes to sites; whether\n addresses exist for a site is answered by `getEmailDomains` — an empty `data`\n there means \"not right now\".\n2. **Prices and stock are per domain**, not per site, so they live in\n `getEmailDomains` and move during the day.\n\nThe answer is static — cache it and don't call it before every purchase.\n\n*Errors: object form.*","operationId":"get_email_services_doc_api_getEmailServices_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"service","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Return just this one service code","title":"Service"},"description":"Return just this one service code","examples":{"ex":{"value":"tg"}}}],"responses":{"200":{"description":"Service code → site","content":{"application/json":{"schema":{},"example":[{"service":"tg","name":"Telegram","site":"telegram.com"},{"service":"lf","name":"TikTok/Douyin","site":"tiktok.com"}]}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/getEmailDomains":{"get":{"tags":["📧 Email addresses"],"summary":"Domains and prices for a site","description":"**Use it right before buying** — this is where `price` and `count` come from, and\nboth move during the day.\n\nPass either `site` (exactly as in `getEmailServices`) or `service`; at least one is\nrequired, otherwise `UNPROCESSABLE_ENTITY` with `info.field = site`.\n\n* `price` — final price of **one** address in RUB, your discount applied. This is\n the number `max_price` in `buyEmail` is compared against.\n* `count` — approximate stock on that domain.\n\nDomains whose price is unknown at the moment are omitted rather than shown with a\nzero price, so everything in `data` is buyable.\n\n**Empty `data` is a valid answer**, not a failure: this site has no addresses right\nnow, or it isn't supported at all. In that case a `message` field explains it. If we\ncannot price the addresses at that moment you get `SERVICE_UNAVAILABLE` instead — that\none is worth retrying.\n\n*Errors: object form.*","operationId":"get_email_domains_doc_api_getEmailDomains_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"site","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Site to register on","title":"Site"},"description":"Site to register on","examples":{"ex":{"value":"telegram.com"}}},{"name":"service","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Service code — used to guess the `site` when you don't pass one","title":"Service"},"description":"Service code — used to guess the `site` when you don't pass one"}],"responses":{"200":{"description":"Domains available right now","content":{"application/json":{"schema":{},"example":{"site":"telegram.com","data":[{"domain":"mail.ru","price":4.2,"count":640,"currency":643},{"domain":"outlook.com","price":6.8,"count":172,"currency":643}]}}}},"400":{"description":"SERVICE_UNAVAILABLE","content":{"application/json":{"examples":{"SERVICE_UNAVAILABLE":{"summary":"This service is temporarily disabled, or an email address / its price could not be issued right now","value":{"title":"SERVICE_UNAVAILABLE","details":"Service is currently unavailable"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"UNPROCESSABLE_ENTITY","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/buyEmail":{"get":{"tags":["📧 Email addresses"],"summary":"Buy one or more email addresses","description":"Buys disposable addresses on one domain. **Each address lives 20 minutes** — start\nthe registration right away.\n\n* `quantity` — 1…10. Anything outside the range is refused, never silently\n trimmed: you are charged only for what you asked for.\n* The price is taken **on our side** from the current domain list — you cannot\n send a price. `max_price` only sets your upper limit per address; if the real\n price is higher you get `WRONG_MAX_PRICE` with the real one in `info.min`.\n* `charged` is the total actually taken. If only part of the batch could be\n issued, `bought` is smaller than `requested`, a `warning` is added, and you are\n charged for the issued addresses only.\n\nSave `data[].id` — every other email operation needs it. Then poll\n`getEmailStatus` roughly once every 3–5 seconds.\n\n> If the address never receives a letter, it expires on its own after 20 minutes\n> and the money comes back automatically — no call needed.\n\n*Errors: object form.*","operationId":"buy_email_doc_api_buyEmail_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"domain","in":"query","required":true,"schema":{"type":"string","description":"Domain from `getEmailDomains`","title":"Domain"},"description":"Domain from `getEmailDomains`","examples":{"ex":{"value":"mail.ru"}}},{"name":"site","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Site to register on","title":"Site"},"description":"Site to register on","examples":{"ex":{"value":"telegram.com"}}},{"name":"service","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Service code — used to guess the `site` when you don't pass one","title":"Service"},"description":"Service code — used to guess the `site` when you don't pass one"},{"name":"quantity","in":"query","required":false,"schema":{"type":"integer","description":"How many addresses at once, 1…10","default":1,"title":"Quantity"},"description":"How many addresses at once, 1…10","examples":{"ex":{"value":1}}},{"name":"max_price","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Refuse if one address costs more than this, RUB","title":"Max Price"},"description":"Refuse if one address costs more than this, RUB"}],"responses":{"200":{"description":"Addresses issued and charged","content":{"application/json":{"schema":{},"example":{"status":"OK","requested":2,"bought":2,"charged":8.4,"currency":643,"data":[{"id":5417,"email":"kate.morrow91@mail.ru","site":"telegram.com","domain":"mail.ru","status":"WAIT","cost":4.2,"letters":[],"createdAt":"2026-08-26T10:00:00+00:00","expiresAt":"2026-08-26T10:20:00+00:00","expiresIn":1200,"currency":643}]}}}},"400":{"description":"WRONG_DOMAIN · NO_EMAILS · WRONG_MAX_PRICE · SERVICE_UNAVAILABLE","content":{"application/json":{"examples":{"WRONG_DOMAIN":{"summary":"`buyEmail`: this `domain` is not offered for the requested `site`","value":{"title":"WRONG_DOMAIN","details":"Domain 'example.com' is not available for site 'tiktok.com'","info":{"site":"tiktok.com","hint":"Get the current list via action=getEmailDomains"}}},"NO_EMAILS":{"summary":"`buyEmail`: the requested domain has run out of addresses","value":{"title":"NO_EMAILS","details":"No addresses left on this domain. Try another domain.","info":{"site":"tiktok.com","domain":"mail.ru"}}},"WRONG_MAX_PRICE":{"summary":"`maxPrice` is below the cheapest number (400), or is not a number at all (422)","value":{"title":"WRONG_MAX_PRICE","details":"The maximum price (10.0 RUB) is less than the minimum available price (13.50 RUB).","info":{"min":13.5}}},"SERVICE_UNAVAILABLE":{"summary":"This service is temporarily disabled, or an email address / its price could not be issued right now","value":{"title":"SERVICE_UNAVAILABLE","details":"Service is currently unavailable"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"NO_BALANCE","content":{"application/json":{"examples":{"NO_BALANCE":{"summary":"Main balance is lower than the price of the order","value":{"title":"NO_BALANCE","details":"Payment Required. Insufficient funds."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"UNPROCESSABLE_ENTITY","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/getEmailStatus":{"get":{"tags":["📧 Email addresses"],"summary":"Poll one address for its letter","description":"**The polling call.** Once every 3–5 seconds is plenty; the address lives 20\nminutes, and `expiresIn` counts the seconds left.\n\n`status`:\n\n| Value | Meaning |\n|---|---|\n| `WAIT` | waiting for the letter |\n| `SUCCESS` | letter received — read `letter` |\n| `CANCELED` | canceled or expired, money already back on your balance |\n\n* `letter` — the last letter (usually just the code).\n* `letters` — every letter this address received, oldest first. A second one\n appears only after `reactivateEmail`.\n\n*Errors: object form.*","operationId":"get_email_status_doc_api_getEmailStatus_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"id","in":"query","required":true,"schema":{"type":"integer","description":"Email order id from `buyEmail`","title":"Id"},"description":"Email order id from `buyEmail`","examples":{"ex":{"value":5417}}}],"responses":{"200":{"description":"Current state of the address","content":{"application/json":{"schema":{},"examples":{"waiting":{"summary":"Letter has not arrived yet","value":{"id":5417,"email":"kate.morrow91@mail.ru","site":"tiktok.com","domain":"mail.ru","status":"WAIT","cost":4.2,"letters":[],"createdAt":"2026-08-26T10:00:00+00:00","expiresAt":"2026-08-26T10:20:00+00:00","expiresIn":742,"currency":643}},"received":{"summary":"Letter received","value":{"id":5417,"email":"kate.morrow91@mail.ru","site":"tiktok.com","domain":"mail.ru","status":"SUCCESS","cost":4.2,"letters":["482913"],"letter":"482913","createdAt":"2026-08-26T10:00:00+00:00","expiresAt":"2026-08-26T10:20:00+00:00","expiresIn":0,"currency":643}}}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED · WRONG_ACTIVATION_ID","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}},"WRONG_ACTIVATION_ID":{"summary":"The `id` exists but belongs to a different account","value":{"title":"WRONG_ACTIVATION_ID","details":"Activation belongs to another user"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NO_ACTIVATION","content":{"application/json":{"examples":{"NO_ACTIVATION":{"summary":"There is no activation with this `id` (the email operations answer the same way for an unknown email order id)","value":{"title":"NO_ACTIVATION","details":"Activation Not Found"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"UNPROCESSABLE_ENTITY","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/cancelEmail":{"get":{"tags":["📧 Email addresses"],"summary":"Cancel an address and get the money back","description":"Releases an address that you no longer need and returns the money — the full sum\npaid for it, extensions included.\n\nPossible only while `status` is `WAIT` **and** no letter has arrived. Once a letter\nis delivered the service is done and the answer is `ERROR_CANCEL`.\n\n**The first 2 minutes are a hold** — same rule as for numbers. Until then the\nanswer is `EARLY_CANCEL_DENIED` (425) with `info.waitSeconds` telling you how long\nis left. A fresh address stays in *processing* for that window and cannot be\nreleased, so a \"cancel\" during it would take your money back while the address\nstayed live.\n\nCancellation is confirmed before anything is refunded. If it cannot be confirmed,\nnothing changes: you keep the address, keep waiting for the letter, and the money\ncomes back on its own when it expires.\n\nThere is no rush and no penalty for not calling it: an unused address expires by\nitself after 20 minutes and refunds automatically.\n\n*Errors: array form for `EARLY_CANCEL_DENIED`, object form for the rest.*","operationId":"cancel_email_doc_api_cancelEmail_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"id","in":"query","required":true,"schema":{"type":"integer","description":"Email order id from `buyEmail`","title":"Id"},"description":"Email order id from `buyEmail`","examples":{"ex":{"value":5417}}}],"responses":{"200":{"description":"Canceled and refunded","content":{"application/json":{"schema":{},"example":{"status":"OK","id":5417,"refund":4.2,"currency":643}}}},"400":{"description":"ALREADY_FINISHED · ERROR_CANCEL · SERVICE_UNAVAILABLE · CANCEL_FAILED","content":{"application/json":{"examples":{"ALREADY_FINISHED":{"summary":"The activation is no longer `ACTIVE` (for an email: no longer `WAIT`, and a canceled address cannot be reactivated)","value":{"title":"ALREADY_FINISHED","details":"Activation is already finished or canceled"}},"ERROR_CANCEL":{"summary":"You try to cancel an activation that already received a code — or an email address that already received a letter","value":{"title":"ERROR_CANCEL","details":"Cannot cancel after SMS code received."}},"SERVICE_UNAVAILABLE":{"summary":"This service is temporarily disabled, or an email address / its price could not be issued right now","value":{"title":"SERVICE_UNAVAILABLE","details":"Service is currently unavailable"}},"CANCEL_FAILED":{"summary":"The cancellation was not confirmed and the number (or email address) is still live","value":{"title":"CANCEL_FAILED","details":"Cancellation was not confirmed. Number is still active."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED · WRONG_ACTIVATION_ID","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}},"WRONG_ACTIVATION_ID":{"summary":"The `id` exists but belongs to a different account","value":{"title":"WRONG_ACTIVATION_ID","details":"Activation belongs to another user"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NO_ACTIVATION","content":{"application/json":{"examples":{"NO_ACTIVATION":{"summary":"There is no activation with this `id` (the email operations answer the same way for an unknown email order id)","value":{"title":"NO_ACTIVATION","details":"Activation Not Found"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"UNPROCESSABLE_ENTITY","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"425":{"description":"EARLY_CANCEL_DENIED","content":{"application/json":{"examples":{"EARLY_CANCEL_DENIED":{"summary":"Cancellation attempted less than 2 minutes after purchase — the same hold applies to numbers and to email addresses. For an email you also get it while the address is still being processed and cannot be released yet: nothing is refunded and the address stays live","value":[{"title":"EARLY_CANCEL_DENIED","details":"Too early to cancel. Please wait 2 minutes after purchase."}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 425 Cancel Email Doc Api Cancelemail Get"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/reactivateEmailOptions":{"get":{"tags":["📧 Email addresses"],"summary":"Price of extending an address","description":"**Call it before `reactivateEmail`** — extending is a paid action, and this is the\nprice you will be charged.\n\n`data` holds one option: `minutes` added and its `price` in RUB with your discount.\nAn empty `data` means the address cannot be extended right now (already canceled,\nor the price is temporarily unknown) — buy a new address instead.\n\nA `waitSeconds` field next to an empty `data` means the address is still on the\n2-minute hold after purchase: extending is refused until it passes.\n\n*Errors: object form.*","operationId":"reactivate_email_options_doc_api_reactivateEmailOptions_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"id","in":"query","required":true,"schema":{"type":"integer","description":"Email order id from `buyEmail`","title":"Id"},"description":"Email order id from `buyEmail`","examples":{"ex":{"value":5417}}}],"responses":{"200":{"description":"What an extension costs","content":{"application/json":{"schema":{},"examples":{"available":{"summary":"Can be extended","value":{"id":5417,"data":[{"minutes":20,"price":4.2,"currency":643}]}},"unavailable":{"summary":"Cannot be extended","value":{"id":5417,"data":[]}},"hold":{"summary":"Still on the 2-minute hold","value":{"id":5417,"data":[],"waitSeconds":83}}}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED · WRONG_ACTIVATION_ID","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}},"WRONG_ACTIVATION_ID":{"summary":"The `id` exists but belongs to a different account","value":{"title":"WRONG_ACTIVATION_ID","details":"Activation belongs to another user"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NO_ACTIVATION","content":{"application/json":{"examples":{"NO_ACTIVATION":{"summary":"There is no activation with this `id` (the email operations answer the same way for an unknown email order id)","value":{"title":"NO_ACTIVATION","details":"Activation Not Found"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"UNPROCESSABLE_ENTITY","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/reactivateEmail":{"get":{"tags":["📧 Email addresses"],"summary":"Extend an address by 20 minutes (paid)","description":"Gives the same address another 20 minutes. **Paid** — take the price from\n`reactivateEmailOptions` first, or cap it with `max_price`.\n\nTwo reasons to use it:\n\n* the letter is late and the 20 minutes are running out;\n* the letter arrived, but you need one more to the **same** address (a login code\n after the registration code). Then `status` goes back to `WAIT`, and the new\n letter is appended to `letters` — the previous one is kept.\n\nA just-bought address cannot be extended: for the first 2 minutes it stays in\n*processing* and the answer is `EARLY_REACTIVATION_DENIED` (425) with\n`info.waitSeconds`. Nothing is charged. There is no reason to extend that early\nanyway — the address still has its full 20 minutes.\n\nIf the extension fails, nothing is charged: the money is returned before you get\nthe error. `cost` in the answer is the total spent on this address so far.\n\n*Errors: array form for `EARLY_REACTIVATION_DENIED`, object form for the rest.*","operationId":"reactivate_email_doc_api_reactivateEmail_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"id","in":"query","required":true,"schema":{"type":"integer","description":"Email order id from `buyEmail`","title":"Id"},"description":"Email order id from `buyEmail`","examples":{"ex":{"value":5417}}},{"name":"max_price","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Refuse if the extension costs more than this, RUB","title":"Max Price"},"description":"Refuse if the extension costs more than this, RUB"}],"responses":{"200":{"description":"Extended and charged","content":{"application/json":{"schema":{},"example":{"status":"OK","charged":4.2,"currency":643,"data":{"id":5417,"email":"kate.morrow91@mail.ru","site":"tiktok.com","domain":"mail.ru","status":"WAIT","cost":8.4,"letters":["482913"],"letter":"482913","createdAt":"2026-08-26T10:00:00+00:00","expiresAt":"2026-08-26T10:40:00+00:00","expiresIn":1200,"currency":643}}}}},"400":{"description":"ALREADY_FINISHED · WRONG_MAX_PRICE · SERVICE_UNAVAILABLE · REACTIVATION_FAILED","content":{"application/json":{"examples":{"ALREADY_FINISHED":{"summary":"The activation is no longer `ACTIVE` (for an email: no longer `WAIT`, and a canceled address cannot be reactivated)","value":{"title":"ALREADY_FINISHED","details":"Activation is already finished or canceled"}},"WRONG_MAX_PRICE":{"summary":"`maxPrice` is below the cheapest number (400), or is not a number at all (422)","value":{"title":"WRONG_MAX_PRICE","details":"The maximum price (10.0 RUB) is less than the minimum available price (13.50 RUB).","info":{"min":13.5}}},"SERVICE_UNAVAILABLE":{"summary":"This service is temporarily disabled, or an email address / its price could not be issued right now","value":{"title":"SERVICE_UNAVAILABLE","details":"Service is currently unavailable"}},"REACTIVATION_FAILED":{"summary":"`reactivate` / `reactivateEmail` was refused for an unclassified reason","value":{"title":"REACTIVATION_FAILED","details":"The request was refused. Your balance has been refunded."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"NO_BALANCE","content":{"application/json":{"examples":{"NO_BALANCE":{"summary":"Main balance is lower than the price of the order","value":{"title":"NO_BALANCE","details":"Payment Required. Insufficient funds."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED · WRONG_ACTIVATION_ID","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}},"WRONG_ACTIVATION_ID":{"summary":"The `id` exists but belongs to a different account","value":{"title":"WRONG_ACTIVATION_ID","details":"Activation belongs to another user"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NO_ACTIVATION","content":{"application/json":{"examples":{"NO_ACTIVATION":{"summary":"There is no activation with this `id` (the email operations answer the same way for an unknown email order id)","value":{"title":"NO_ACTIVATION","details":"Activation Not Found"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"UNPROCESSABLE_ENTITY","content":{"application/json":{"examples":{"UNPROCESSABLE_ENTITY":{"summary":"A required parameter is missing or has the wrong type","value":{"title":"UNPROCESSABLE_ENTITY","details":"Validation failed","info":{"field":"country","code":"NOT_AN_INTEGER","message":"Param 'country' must be a country ID (integer). Get the list via action=getCountries."}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"425":{"description":"EARLY_REACTIVATION_DENIED","content":{"application/json":{"examples":{"EARLY_REACTIVATION_DENIED":{"summary":"`reactivateEmail` was called on a just-bought address that is still being processed","value":[{"title":"EARLY_REACTIVATION_DENIED","details":"Too early to extend. Please wait 2 minutes after purchase."}]}},"schema":{"type":"array","items":{"$ref":"#/components/schemas/ErrorResponse"},"title":"Response 425 Reactivate Email Doc Api Reactivateemail Get"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/getActiveEmails":{"get":{"tags":["📧 Email addresses"],"summary":"Your addresses still waiting for a letter","description":"**Use it to recover after a network failure.** If `buyEmail` timed out and you\nlost the id, look here before buying again — the address may already be yours and\npaid for.\n\nOnly addresses in `WAIT` are listed. For everything else use `getEmailHistory`.\n\n*Errors: object form.*","operationId":"get_active_emails_doc_api_getActiveEmails_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"start","in":"query","required":false,"schema":{"type":"integer","description":"Offset","default":0,"title":"Start"},"description":"Offset"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","description":"Page size, max 100","default":100,"title":"Limit"},"description":"Page size, max 100"}],"responses":{"200":{"description":"Addresses in `WAIT`","content":{"application/json":{"schema":{},"example":{"status":"OK","count":1,"data":[{"id":5417,"email":"kate.morrow91@mail.ru","site":"tiktok.com","domain":"mail.ru","status":"WAIT","cost":4.2,"letters":[],"createdAt":"2026-08-26T10:00:00+00:00","expiresAt":"2026-08-26T10:20:00+00:00","expiresIn":742,"currency":643}]}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/getEmailHistory":{"get":{"tags":["📧 Email addresses"],"summary":"Email purchase history","description":"**Use it** for reconciliation: which addresses were bought, what they cost, which\nletters arrived. Every status is included — `WAIT`, `SUCCESS` and `CANCELED`.\n\n`cost` is the total paid for the address, extensions included, so the sum over a\nperiod matches what left your balance.\n\n*Errors: object form.*","operationId":"get_email_history_doc_api_getEmailHistory_get","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Your API key from @bringsmsbot → API","title":"Api Key"},"description":"Your API key from @bringsmsbot → API"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","description":"Offset","default":0,"title":"Offset"},"description":"Offset"},{"name":"size","in":"query","required":false,"schema":{"type":"integer","description":"Page size, 1…100","default":20,"title":"Size"},"description":"Page size, 1…100"}],"responses":{"200":{"description":"Past addresses, newest first","content":{"application/json":{"schema":{},"example":{"status":"OK","count":1,"offset":0,"size":20,"data":[{"id":5417,"email":"kate.morrow91@mail.ru","site":"tiktok.com","domain":"mail.ru","status":"SUCCESS","cost":4.2,"letters":["482913"],"letter":"482913","createdAt":"2026-08-26T10:00:00+00:00","expiresAt":"2026-08-26T10:20:00+00:00","expiresIn":0,"currency":643}]}}}},"401":{"description":"BAD_KEY","content":{"application/json":{"examples":{"BAD_KEY":{"summary":"`api_key` not sent, unknown, or the activation belongs to another account","value":{"title":"BAD_KEY","details":"Unauthorized"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"BANNED","content":{"application/json":{"examples":{"BANNED":{"summary":"Account is suspended","value":{"title":"BANNED","details":"Your account has been suspended. Contact support."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"TOO_MANY_REQUESTS","content":{"application/json":{"examples":{"TOO_MANY_REQUESTS":{"summary":"More than 40 req/s per key or 2400 req/min per IP","value":{"title":"TOO_MANY_REQUESTS","details":"Rate limit exceeded (key). Retry in 1s.","info":{"limit_per_key":"40 req/s","limit_per_ip":"2400 req/min","retry_after":1}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"SERVER_ERROR","content":{"application/json":{"examples":{"SERVER_ERROR":{"summary":"Temporary outage, timeout, or an internal failure","value":{"title":"SERVER_ERROR","details":"The service is temporarily unavailable. Please try again shortly."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"CountryPrices":{"additionalProperties":{"$ref":"#/components/schemas/PriceInfo"},"type":"object","title":"CountryPrices"},"ErrorResponse":{"properties":{"title":{"type":"string","title":"Title","description":"Machine-readable error code — switch on this"},"details":{"type":"string","title":"Details","description":"Human-readable explanation — show this, never parse it"},"info":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Info","description":"Extra machine-readable context when available: `field`/`code` for validation errors, `min` for WRONG_MAX_PRICE, `retry_after` for TOO_MANY_REQUESTS"}},"type":"object","required":["title","details"],"title":"ErrorResponse"},"FullPrices":{"additionalProperties":{"$ref":"#/components/schemas/CountryPrices"},"type":"object","title":"FullPrices"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"NumbersStatus":{"additionalProperties":{"type":"integer"},"type":"object","title":"NumbersStatus"},"PriceInfo":{"properties":{"cost":{"type":"number","title":"Cost","description":"Final price in RUB (your level discount already applied)"},"count":{"type":"integer","title":"Count","description":"Numbers in stock (estimated)"}},"type":"object","required":["cost","count"],"title":"PriceInfo"},"ServiceItem":{"properties":{"code":{"type":"string","title":"Code","description":"Service code to pass as `service`","example":"tg"},"name":{"type":"string","title":"Name","description":"Human-readable name","example":"Telegram"}},"type":"object","required":["code","name"],"title":"ServiceItem"},"SimpleDict":{"additionalProperties":true,"type":"object","title":"SimpleDict"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"💳 Balance","description":"How much money you have."},{"name":"💰 Prices & stock","description":"What a number costs and how many are left. Prices in RUB, your discount applied."},{"name":"📚 Catalog","description":"Reference lists: countries, services, operators. Cache them — they change rarely."},{"name":"📲 Activations","description":"The main flow: buy a number → poll for the code → close the activation."},{"name":"📅 Rent","description":"Long-term numbers: rent one, look up the durations on offer, prolong it. Rent-only operations."},{"name":"🔁 Manage a number","description":"Works for **both** a regular activation and a rent: read messages, cancel, finish, bring a number back. Pass the id you got when you bought it — which of the two it is, the API figures out itself."},{"name":"📧 Email addresses","description":"Disposable email addresses instead of a phone number: buy an address → poll for the letter → cancel for a refund or extend it. Own ids, own 20-minute lifetime — never mix them with activation ids."}]}