DEVELOPER PLATFORM · REST v1

API для разработчиков

Интегрируйте SMS-номера в приложение с балансом Get SMS.

USD pricingBearer authentication10 operationsPolling for SMS
01 / GET STARTED

From API key to your first SMS

This reference describes the Get SMS contract. Use the exact endpoints and fields here; credentials and IDs from another provider do not authenticate this API. Technical documentation is maintained in English across all interface languages.

Base URLhttps://get-sms.io/api/v1
  1. Prepare your account. Sign in as a customer, add funds through the website, and create an API key.
  2. Choose a service and country. Use canonical catalog IDs, then fetch a live price.
  3. Approve and save one purchase. Persist a UUIDv4 and the exact four-field body before sending POST /orders.
  4. Read the number and SMS. Poll the recorded order through one shared account queue.
  5. Settle the same order. Finish after using the code, or cancel when permitted. Recover a lost response before retrying.
Examples are illustrative. Sample UUIDs, timestamps, prices, stock and SMS are not live values. Replace them with saved IDs and approved current quotes. POST /orders is a real purchase; there is no sandbox or free test number.

For a durable implementation, use the downloadable Python client and integration algorithm. Short request snippets below illustrate the HTTP contract; they do not replace durable intent storage or production error handling.

Authentication & common response format

Send Authorization: Bearer gs_live_… in every request. Set GETSMS_API_KEY in your backend environment. Cookies cannot authenticate API calls. Keys are shown once, stored as hashes, and share the same customer wallet and history.

Authorization: Bearer YOUR_SERVER_API_KEY
Accept: application/json
Content-Type: application/json  # POST only

Every successful response wraps its result in data and includes request_id. Response headers include X-Request-ID, X-API-Version: 1 and Cache-Control: private, no-store. A request ID identifies one HTTP attempt; an Idempotency-Key identifies one purchase intent. Keep both roles separate.

{
  "data": {
    "currency": "USD",
    "available": "8.8000"
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}

Ключи API

…

GET/api/v1/catalog200

Catalog

Read canonical services and countries. Cache identifiers in your application; prices and stock must be read separately. The example is an abbreviated catalog.

No query, path or body parameters. Common Bearer authentication applies.

Request example

# Replace the example order/request UUID with your saved UUID where applicable.
curl --request GET 'https://get-sms.io/api/v1/catalog' \
  --header "Authorization: Bearer $GETSMS_API_KEY" \
  --connect-timeout 10 --max-time 25

200 response example

Illustrative response · fields: Catalog. All timestamps use ISO 8601 UTC.

{
  "data": {
    "currency": "USD",
    "services": [
      {
        "id": "telegram",
        "name": "Telegram"
      }
    ],
    "countries": [
      {
        "id": "usa",
        "name": "USA",
        "dial_code": "+1"
      },
      {
        "id": "england",
        "name": "United Kingdom",
        "dial_code": "+44"
      }
    ]
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}

Error codes and handling → · Shared rate limits →

GET/api/v1/prices200

Live prices

Choose one canonical country and service from the catalog. A supported pair without stock returns prices: []; an invalid identifier returns 400. Only an available any-operator quote can fund a new purchase. Values below are illustrative, never a live offer.

Parameters

NameLocation / requiredRules
countryquery · RequiredCanonical catalog country ID; USA is usa, United Kingdom is england. Türkiye is unavailable.
servicequery · RequiredCanonical catalog service ID, for example telegram.

Request example

# Replace the example order/request UUID with your saved UUID where applicable.
curl --request GET 'https://get-sms.io/api/v1/prices?country=usa&service=telegram' \
  --header "Authorization: Bearer $GETSMS_API_KEY" \
  --connect-timeout 10 --max-time 25

200 response example

Illustrative response · fields: Prices. All timestamps use ISO 8601 UTC.

{
  "data": {
    "currency": "USD",
    "checked_at": "2026-10-20T12:00:00.000Z",
    "prices": [
      {
        "country": "usa",
        "service": "telegram",
        "operator": "any",
        "price": "1.2000",
        "stock": 100,
        "success_rate": 80
      }
    ]
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}

Error codes and handling → · Shared rate limits →

GET/api/v1/balance200

Account balance

Read the shared customer wallet. available is spendable; balance includes reserved funds. Website and API purchases use this same wallet.

No query, path or body parameters. Common Bearer authentication applies.

Request example

# Replace the example order/request UUID with your saved UUID where applicable.
curl --request GET 'https://get-sms.io/api/v1/balance' \
  --header "Authorization: Bearer $GETSMS_API_KEY" \
  --connect-timeout 10 --max-time 25

200 response example

Illustrative response · fields: Balance. All timestamps use ISO 8601 UTC.

{
  "data": {
    "currency": "USD",
    "balance": "10.0000",
    "reserved": "1.2000",
    "available": "8.8000"
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}

Error codes and handling → · Shared rate limits →

POST/api/v1/orders202

Buy a number

This starts a real, chargeable purchase. Persist one intent UUID and the exact body before sending. HTTP 202 means an order was recorded; inspect its status. A number and SMS are not guaranteed. No live requests run from this documentation.

Parameters

NameLocation / requiredRules
Idempotency-Keyheader · RequiredUUID versions 1–5; uppercase/lowercase accepted. Prefer UUIDv4.

JSON request body

FieldType / requirementDescription
countrystring
Required
Canonical catalog country ID; USA is usa, United Kingdom is england. Türkiye is unavailable.
servicestring
Required
Canonical catalog service ID, for example telegram.
operatorstring
Required
Use any from a current quote for a new order. A physical operator is not guaranteed.
max_pricestring
Required
Required positive USD string, up to four decimals. Example: "1.2000". Zero, numeric JSON and unknown fields are rejected.
Validation pattern^(?!0+(?:\.0+)?$)\d{1,8}(\.\d{1,4})?$

Request example

# Replace the example UUID with your persisted intent UUID and max_price with an approved live quote.
curl --request POST 'https://get-sms.io/api/v1/orders' \
  --header "Authorization: Bearer $GETSMS_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 11111111-1111-4111-8111-111111111111' \
  --data '{"country":"usa","service":"telegram","operator":"any","max_price":"1.2000"}' \
  --connect-timeout 10 --max-time 120

202 response example

Illustrative response · fields: Order. All timestamps use ISO 8601 UTC.

{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "service": "telegram",
    "country": "usa",
    "operator": "any",
    "phone": null,
    "status": "purchasing",
    "currency": "USD",
    "price": "1.2000",
    "created_at": "2026-10-20T12:00:00.000Z",
    "expires_at": null,
    "cancel_available_at": null,
    "last_checked_at": null,
    "sms": []
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}
A 202 response can still contain purchasing or reconciliation. Preserve the same key/body after a timeout, 429 or 5xx. Follow the recovery decision table.

Error codes and handling → · Shared rate limits →

GET/api/v1/requests/{key}200

Recover a purchase

Use the original Idempotency-Key after a timeout or lost response. This lookup does not buy a number. A 404 can mean the original request is still in preflight; retry its same POST and body, not a new key.

Parameters

NameLocation / requiredRules
keypath · RequiredUUID versions 1–5; uppercase/lowercase accepted. Prefer UUIDv4.

Request example

# Replace the example order/request UUID with your saved UUID where applicable.
curl --request GET 'https://get-sms.io/api/v1/requests/11111111-1111-4111-8111-111111111111' \
  --header "Authorization: Bearer $GETSMS_API_KEY" \
  --connect-timeout 10 --max-time 25

200 response example

Illustrative response · fields: Order. All timestamps use ISO 8601 UTC.

{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "service": "telegram",
    "country": "usa",
    "operator": "any",
    "phone": "+12025550123",
    "status": "pending",
    "currency": "USD",
    "price": "1.2000",
    "created_at": "2026-10-20T12:00:00.000Z",
    "expires_at": "2026-10-20T12:15:00.000Z",
    "cancel_available_at": "2026-10-20T12:01:00.000Z",
    "last_checked_at": "2026-10-20T12:00:10.000Z",
    "sms": []
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}

Error codes and handling → · Shared rate limits →

GET/api/v1/orders/{id}200

Number and SMS

Read your order and all received SMS. Eligible checks refresh saved provider state; calls less than five seconds apart may return the cached state. Poll through one account-level queue.

Parameters

NameLocation / requiredRules
idpath · RequiredUUID versions 1–5; uppercase/lowercase accepted. Prefer UUIDv4.

Request example

# Replace the example order/request UUID with your saved UUID where applicable.
curl --request GET 'https://get-sms.io/api/v1/orders/11111111-1111-4111-8111-111111111111' \
  --header "Authorization: Bearer $GETSMS_API_KEY" \
  --connect-timeout 10 --max-time 25

200 response example

Illustrative response · fields: Order. All timestamps use ISO 8601 UTC.

{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "service": "telegram",
    "country": "usa",
    "operator": "any",
    "phone": "+12025550123",
    "status": "received",
    "currency": "USD",
    "price": "1.2000",
    "created_at": "2026-10-20T12:00:00.000Z",
    "expires_at": "2026-10-20T12:15:00.000Z",
    "cancel_available_at": "2026-10-20T12:01:00.000Z",
    "last_checked_at": "2026-10-20T12:02:05.000Z",
    "sms": [
      {
        "code": "012345",
        "body": "Example verification code: 012345",
        "received_at": "2026-10-20T12:02:00.000Z"
      }
    ]
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}

Error codes and handling → · Shared rate limits →

GET/api/v1/orders200

Order history

Newest first, across all API keys and website orders. Listing returns saved state and does not refresh each order. New arrivals can move offset pages; deduplicate by order id.

Parameters

NameLocation / requiredRules
pagequery · OptionalCurrent one-based page. Minimum 1. Maximum 100000. Default 1.
limitquery · OptionalPage size: 1–50, default 20. Minimum 1. Maximum 50. Default 20.

Request example

# Replace the example order/request UUID with your saved UUID where applicable.
curl --request GET 'https://get-sms.io/api/v1/orders?page=1&limit=20' \
  --header "Authorization: Bearer $GETSMS_API_KEY" \
  --connect-timeout 10 --max-time 25

200 response example

Illustrative response · fields: History. All timestamps use ISO 8601 UTC.

{
  "data": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "orders": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "service": "telegram",
        "country": "usa",
        "operator": "any",
        "phone": "+12025550123",
        "status": "pending",
        "currency": "USD",
        "price": "1.2000",
        "created_at": "2026-10-20T12:00:00.000Z",
        "expires_at": "2026-10-20T12:15:00.000Z",
        "cancel_available_at": "2026-10-20T12:01:00.000Z",
        "last_checked_at": "2026-10-20T12:00:10.000Z",
        "sms": []
      }
    ]
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}

Error codes and handling → · Shared rate limits →

POST/api/v1/orders/{id}/cancel200

Cancel a number

Use after cancel_available_at and before SMS. Send {}. Cancellation is independently verified before unused funds are released. HTTP 200 does not prove a refund: inspect data.status and GET /balance. A recorded order can already be finished. If SMS arrives during cancellation, HTTP 409 ORDER_CONFLICT may follow a saved delivery; GET /orders/{id} using the same order UUID to retrieve received or finished state and its SMS. Do not create a new purchase or promise a refund from the cancellation response alone.

Parameters

NameLocation / requiredRules
idpath · RequiredUUID versions 1–5; uppercase/lowercase accepted. Prefer UUIDv4.

JSON request body

Send exactly {} with Content-Type: application/json. Unknown fields are rejected.

Request example

# Replace the example order/request UUID with your saved UUID where applicable.
curl --request POST 'https://get-sms.io/api/v1/orders/11111111-1111-4111-8111-111111111111/cancel' \
  --header "Authorization: Bearer $GETSMS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --connect-timeout 10 --max-time 25

200 response example

Illustrative response · fields: Order. All timestamps use ISO 8601 UTC.

{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "service": "telegram",
    "country": "usa",
    "operator": "any",
    "phone": "+12025550123",
    "status": "cancelled",
    "currency": "USD",
    "price": "1.2000",
    "created_at": "2026-10-20T12:00:00.000Z",
    "expires_at": "2026-10-20T12:15:00.000Z",
    "cancel_available_at": "2026-10-20T12:01:00.000Z",
    "last_checked_at": "2026-10-20T12:00:10.000Z",
    "sms": []
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}

A 409 WAIT_REQUIRED includes seconds in error.retry_after and Retry-After. Wait before trying the same action. Successful HTTP status does not replace inspection of the returned order status.

Error codes and handling → · Shared rate limits →

POST/api/v1/orders/{id}/finish200

Finish an order

Use after an SMS arrives and you have used the code. Send {}. Finishing settles the charge; it is not cancellation. A repeated terminal action returns the recorded state.

Parameters

NameLocation / requiredRules
idpath · RequiredUUID versions 1–5; uppercase/lowercase accepted. Prefer UUIDv4.

JSON request body

Send exactly {} with Content-Type: application/json. Unknown fields are rejected.

Request example

# Replace the example order/request UUID with your saved UUID where applicable.
curl --request POST 'https://get-sms.io/api/v1/orders/11111111-1111-4111-8111-111111111111/finish' \
  --header "Authorization: Bearer $GETSMS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --connect-timeout 10 --max-time 25

200 response example

Illustrative response · fields: Order. All timestamps use ISO 8601 UTC.

{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "service": "telegram",
    "country": "usa",
    "operator": "any",
    "phone": "+12025550123",
    "status": "finished",
    "currency": "USD",
    "price": "1.2000",
    "created_at": "2026-10-20T12:00:00.000Z",
    "expires_at": "2026-10-20T12:15:00.000Z",
    "cancel_available_at": "2026-10-20T12:01:00.000Z",
    "last_checked_at": "2026-10-20T12:00:10.000Z",
    "sms": [
      {
        "code": "012345",
        "body": "Example verification code: 012345",
        "received_at": "2026-10-20T12:02:00.000Z"
      }
    ]
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}

Error codes and handling → · Shared rate limits →

Response field reference

Money is a decimal string with four places, including trailing zeros. Use decimal/integer arithmetic for billing. Phone numbers and SMS codes are strings; null is different from an empty string. success_rate is optional.

Balance

FieldType / requirementDescription
balanceMoney
Required
Total customer balance including reserved funds.
reservedMoney
Required
Funds held for unresolved orders; not available for a new purchase.
availableMoney
Required
Spendable balance: balance minus reserved.
currency"USD"
Required
USD. All wallet and order money is expressed in USD.

Order

FieldType / requirementDescription
idstring (uuid)
Required
Get SMS order UUID. Store as a string; do not use an upstream numeric ID.
servicestring
Required
Canonical catalog service ID, for example telegram.
countrystring
Required
Canonical catalog country ID; USA is usa, United Kingdom is england. Türkiye is unavailable.
operatorstring
Required
Use any from a current quote for a new order. A physical operator is not guaranteed.
phonestring | null
Required
E.164 phone string with +. Null until a number is assigned. Never convert to a number.
statusstring
Required
Order lifecycle state. finished can be automatic: stored SMS plus provider closure settles a paid order with visible SMS, even after cancellation, expiry or ban. HTTP success alone does not mean cancellation or refund.

created, purchasing, pending, received, reconciliation, finished, cancelled, timeout, banned, failed

currency"USD"
Required
USD. All wallet and order money is expressed in USD.
priceMoney
Required
Your Get SMS cost with the current site margin included. Four decimal places.
created_atstring (date-time)
Required
Order creation time, ISO 8601 UTC.
expires_atstring (date-time) | null
Required
Order expiry if known; null before assignment or when unavailable.
cancel_available_atstring (date-time) | null
Required
Earliest cancellation time under the account policy; null if not known. Read this field instead of hard-coding a timer.
last_checked_atstring (date-time) | null
Required
Most recent saved provider check; null if none.
smsSMS[]
Required
Chronologically ordered SMS records. More than one SMS can arrive.
FieldType / requirementDescription
sms[].codestring | null
Required
Code as a string (leading zeros preserved), or null if no code was extracted.
sms[].bodystring
Required
Original SMS text. May contain sensitive data; do not log or send to analytics.
sms[].received_atstring (date-time)
Required
SMS arrival timestamp in UTC. Use to distinguish multiple messages.

SMS

FieldType / requirementDescription
codestring | null
Required
Code as a string (leading zeros preserved), or null if no code was extracted.
bodystring
Required
Original SMS text. May contain sensitive data; do not log or send to analytics.
received_atstring (date-time)
Required
SMS arrival timestamp in UTC. Use to distinguish multiple messages.

Catalog

FieldType / requirementDescription
currency"USD"
Required
USD. All wallet and order money is expressed in USD.
servicesobject[]
Required
Canonical service identifiers and display names.
FieldType / requirementDescription
services[].idstring
Required
Canonical catalog identifier; use this exact string in requests.
services[].namestring
Required
Display label; use id in API requests.
countriesobject[]
Required
Canonical country identifiers, display names and dialing codes.
FieldType / requirementDescription
countries[].idstring
Required
Canonical catalog identifier; use this exact string in requests.
countries[].namestring
Required
Display label; use id in API requests.
countries[].dial_codestring
Required
International dialing prefix, including +.

Prices

FieldType / requirementDescription
currency"USD"
Required
USD. All wallet and order money is expressed in USD.
checked_atstring (date-time)
Required
Time this price response was produced. Prices can change before purchase.
pricesobject[]
Required
Available price-protected options. May be empty.
FieldType / requirementDescription
prices[].countrystring
Required
Canonical catalog country ID; USA is usa, United Kingdom is england. Türkiye is unavailable.
prices[].servicestring
Required
Canonical catalog service ID, for example telegram.
prices[].operatorstring
Required
Use any from a current quote for a new order. A physical operator is not guaranteed.
prices[].priceMoney
Required
Your Get SMS cost with the current site margin included. Four decimal places.
prices[].stocknumber
Required
Estimated available numbers, not a reservation or guarantee.
prices[].success_ratenumber
Optional
Optional reported estimate; absent when unavailable. Not a service guarantee.

History

FieldType / requirementDescription
pageinteger
Required
Current one-based page.
limitinteger
Required
Page size: 1–50, default 20.
totalinteger
Required
Total account orders at query time.
ordersOrder[]
Required
Page of saved orders belonging to this customer.
FieldType / requirementDescription
orders[].idstring (uuid)
Required
Get SMS order UUID. Store as a string; do not use an upstream numeric ID.
orders[].servicestring
Required
Canonical catalog service ID, for example telegram.
orders[].countrystring
Required
Canonical catalog country ID; USA is usa, United Kingdom is england. Türkiye is unavailable.
orders[].operatorstring
Required
Use any from a current quote for a new order. A physical operator is not guaranteed.
orders[].phonestring | null
Required
E.164 phone string with +. Null until a number is assigned. Never convert to a number.
orders[].statusstring
Required
Order lifecycle state. finished can be automatic: stored SMS plus provider closure settles a paid order with visible SMS, even after cancellation, expiry or ban. HTTP success alone does not mean cancellation or refund.

created, purchasing, pending, received, reconciliation, finished, cancelled, timeout, banned, failed

orders[].currency"USD"
Required
USD. All wallet and order money is expressed in USD.
orders[].priceMoney
Required
Your Get SMS cost with the current site margin included. Four decimal places.
orders[].created_atstring (date-time)
Required
Order creation time, ISO 8601 UTC.
orders[].expires_atstring (date-time) | null
Required
Order expiry if known; null before assignment or when unavailable.
orders[].cancel_available_atstring (date-time) | null
Required
Earliest cancellation time under the account policy; null if not known. Read this field instead of hard-coding a timer.
orders[].last_checked_atstring (date-time) | null
Required
Most recent saved provider check; null if none.
orders[].smsSMS[]
Required
Chronologically ordered SMS records. More than one SMS can arrive.

Dynamic prices & your resale margin

Quotes and new purchases read the current Get SMS markup and currency conversion settings. If the site margin changes from 20% to 30%, subsequent API quotes and new purchases use 30%. Existing reserved orders keep their agreed amount.

The quoted price is your Get SMS cost; add your own margin separately in your application. Provider cost is not exposed. Get SMS does not bill your end-customers.

max_price is mandatory and positive. Fetch a fresh quote for operator=any, approve it, and persist the exact body. The purchase checks the price again. A higher current price is rejected before buying; stock and success estimates do not guarantee acquisition. Fixed operators are unavailable for new intents. Exact replays of previously recorded legacy orders remain supported.

Order lifecycle & wallet settlement

StateFundsWhat to do
created / purchasingReservedAcquisition is in progress. Do not create another purchase.
pendingReservedNumber assigned. Wait for SMS or cancel when allowed.
receivedReserved until settlementSMS arrived. Use its code; cancellation cannot refund delivered SMS.
reconciliationReservedUncertain provider outcome. Keep the same intent; do not rebuy or promise a refund.
finishedChargedOrder completed; may be automatic when stored SMS and provider closure coincide. SMS remains readable.
cancelled / timeout / banned / failedSettled according to the authoritative resultUnused funds are released only after settlement. A delivered SMS may still make a terminal order chargeable. Check /balance.

Website orders and all keys share a maximum of five active/resolving orders. Wallet reservation is locked transactionally to protect concurrent purchases. Cancellation normally becomes available 60 seconds after provider purchase time; account-specific exemptions are reflected in cancel_available_at. An elapsed timer or a local cancellation click is not proof of refund. Inspect the order and balance.

Multiple SMS can arrive. Display each message and its received_at timestamp. Finishing requires an SMS; /stop only requests that an unassigned search stop after 15 seconds.

SMS delivery during cancellation or expiry

finished does not necessarily mean that your application called /finish. When a valid SMS has been saved and the provider then closes the order as cancelled, timed out or banned, Get SMS automatically settles it as finished: the agreed order price is charged and the SMS remains readable. Provider closure cannot refund delivered SMS.

  1. After a cancellation HTTP 200, inspect data.status and read GET /balance; do not assume that the order was cancelled or refunded.
  2. If SMS arrives during cancellation, a HTTP 409 ORDER_CONFLICT can follow saved delivery. Read GET /orders/{id} with the same order UUID and display its SMS in received or finished state. Do not create another purchase.
  3. For pending or reconciliation states, continue checking the same order within the polling limits. A timeout, conflict or local timer is not proof of refund.

This rule applies when unresolved orders are subsequently processed. Historical terminal records were not rewritten by this fix; inspect their saved state and balance, and contact support if they disagree.

Retries without duplicate purchases

Persist the intent UUID, exact request body, and your own end-customer sale reference before POST /orders. Scope this mapping to the sale, not to an HTTP retry or API key.

ResultNext action
202 with an orderStore its Get SMS UUID and poll that order. No new purchase.
Timeout, malformed response, connection loss, 429 or 5xxHonor Retry-After if present, then GET /requests/original-key. Keep the original key/body.
Recovery returns an orderContinue the recorded order.
Recovery returns 404The first call may still be validating. Retry the same POST with the same UUID and exact body, with backoff.
409 PRICE_CHANGEDRead a new quote. Obtain approval for a genuinely new intent; never silently increase max_price.
409 IDEMPOTENCY_CONFLICTRecover the original mapping. Do not change its body or use a new key to escape uncertainty.

Allow at least 120 seconds for purchase requests; stock acquisition may take about 70 seconds plus network/database work. Reverse proxies can time out sooner, so durable recovery is still required. Terminal actions can be repeated safely, but return the recorded terminal state. Revoking a key blocks future admissions; an already authorized in-flight purchase may finish.

Rate limits & polling budget

ScopeCeiling
All requests120/minute per key and per customer
New purchase attempts10/minute per customer
Order polls30/minute per customer
Order actions30/minute per customer
Active/resolving orders5 per customer, shared with website
Active API keys3 per customer
POST JSON body2,048 bytes
History1–50 results/page; pages 1–100,000

Use one account-level polling scheduler. Poll each order every five seconds or slower. Five active orders need at least ten seconds per order to fit 30 polls/minute; the durable Python client uses 12.5 seconds for headroom. Add jitter and exponential backoff, honor Retry-After, and never rotate keys to evade account limits. Fixed windows, IP and infrastructure safeguards can impose lower temporary limits.

Error codes & recovery actions

{
  "error": {
    "code": "WAIT_REQUIRED",
    "message": "Wait until cancellation is available.",
    "retry_after": 30
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}

The example has HTTP 409 and Retry-After: 30. The retry_after field is optional. Use error.code for program logic; retain the request ID for support.

HTTPCodeMeaning / action
400INVALID_REQUESTInvalid identifier, UUID, JSON, amount or unsupported field. Correct the input.
400 / 409REQUEST_REJECTED / ORDER_CONFLICTA domain rule rejected the operation. Inspect message, current order, balance and active orders.
401UNAUTHORIZEDKey missing, invalid, revoked, or customer account unavailable. Check your server configuration.
404NOT_FOUNDWrong endpoint, missing/foreign order, or purchase intent with no order recorded yet. Recovery 404 is not proof of failure.
409IDEMPOTENCY_CONFLICTSame intent UUID with a different body. Recover the original request; do not overwrite its mapping.
409PRICE_PROTECTION_REQUIREDNew purchases require operator=any from a live price-protected quote.
409PRICE_CHANGEDCurrent cost exceeds max_price. Fetch a new quote and obtain approval before starting a genuinely new intent.
409NO_STOCKNo available protected quote. Do not blindly buy repeatedly.
409WAIT_REQUIREDAction is too early. Honor error.retry_after and Retry-After, then inspect the same order.
413REQUEST_REJECTEDJSON body exceeds 2,048 bytes. Reduce it.
415INVALID_REQUESTSend Content-Type: application/json for POST.
429RATE_LIMITEDHonor Retry-After; use backoff with jitter. Purchase retries keep their original intent key.
503SALES_UNAVAILABLESales or currency conversion settings are unavailable. Do not start a new intent automatically.
503PROVIDER_UNAVAILABLE / SERVICE_UNAVAILABLERecover the same purchase intent. A timeout or 5xx does not prove that no number was bought.

Production checklist

  • Keep keys on your backend, in secret storage. Never put them in URLs, frontend bundles, mobile binaries, Git, screenshots or analytics.
  • Revoke compromised keys immediately. Keys grant access to all orders of that customer, including website orders; authorize your own end-users separately.
  • Persist intent storage on durable media, preserve exact request bodies, and deduplicate your own sale reference.
  • Use HTTPS and safe decimal arithmetic; keep E.164 phone numbers and leading-zero SMS codes as strings.
  • Test timeout, 404 recovery, 429, insufficient available balance, price changes, concurrent purchase and cancellation uncertainty using mocks.
  • Do not log phone numbers, SMS bodies or credentials. Send only request ID, error code and approximate UTC time to support.
  • API v1 uses polling. No SMS webhooks, browser CORS, sandbox, free numbers, number rebuy, hosting or ban endpoints are provided.

FAQ & support

Which ID should I use for the United Kingdom?

england, from the catalog. Website URL aliases such as uk are not API identifiers.

Can I use this directly from a browser or mobile app?

Route calls through your backend. A distributed client cannot keep a live API key secret; browser CORS is not enabled.

Does creating an API key buy a number?

No. A number is purchased only through POST /orders. Funding and key management remain on the website; no payment-provider credentials are required by the customer API.

Can I reuse a previous phone number?

No rebuy endpoint exists in v1. A new order does not guarantee a previous number or physical operator.

How do I get help without sharing secrets?

Email support@get-sms.io with the request ID, error code and approximate UTC time. Never include API keys or SMS codes.

Use is subject to our terms and privacy policy.

Поддержка в Telegram