API para desarrolladores
Integra números SMS en tu aplicación con tu saldo de Get SMS.
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.
https://get-sms.io/api/v1- Prepare your account. Sign in as a customer, add funds through the website, and create an API key.
- Choose a service and country. Use canonical catalog IDs, then fetch a live price.
- Approve and save one purchase. Persist a UUIDv4 and the exact four-field body before sending POST /orders.
- Read the number and SMS. Poll the recorded order through one shared account queue.
- Settle the same order. Finish after using the code, or cancel when permitted. Recover a lost response before retrying.
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 onlyEvery 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"
}Claves API
…
/api/v1/catalog200Catalog
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 25200 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"
}/api/v1/prices200Live 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
| Name | Location / required | Rules |
|---|---|---|
country | query · Required | Canonical catalog country ID; USA is usa, United Kingdom is england. Türkiye is unavailable. |
service | query · Required | Canonical 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 25200 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"
}/api/v1/balance200Account 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 25200 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"
}/api/v1/orders202Buy 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
| Name | Location / required | Rules |
|---|---|---|
Idempotency-Key | header · Required | UUID versions 1–5; uppercase/lowercase accepted. Prefer UUIDv4. |
JSON request body
| Field | Type / requirement | Description |
|---|---|---|
country | stringRequired | Canonical catalog country ID; USA is usa, United Kingdom is england. Türkiye is unavailable. |
service | stringRequired | Canonical catalog service ID, for example telegram. |
operator | stringRequired | Use any from a current quote for a new order. A physical operator is not guaranteed. |
max_price | stringRequired | 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 120202 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"
}purchasing or reconciliation. Preserve the same key/body after a timeout, 429 or 5xx. Follow the recovery decision table./api/v1/requests/{key}200Recover 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
| Name | Location / required | Rules |
|---|---|---|
key | path · Required | UUID 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 25200 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"
}/api/v1/orders/{id}200Number 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
| Name | Location / required | Rules |
|---|---|---|
id | path · Required | UUID 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 25200 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"
}/api/v1/orders200Order 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
| Name | Location / required | Rules |
|---|---|---|
page | query · Optional | Current one-based page. Minimum 1. Maximum 100000. Default 1. |
limit | query · Optional | Page 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 25200 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"
}/api/v1/orders/{id}/cancel200Cancel 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
| Name | Location / required | Rules |
|---|---|---|
id | path · Required | UUID 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 25200 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.
/api/v1/orders/{id}/finish200Finish 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
| Name | Location / required | Rules |
|---|---|---|
id | path · Required | UUID 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 25200 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"
}/api/v1/orders/{id}/stop200Stop number search
Use only for an unassigned search after 15 seconds. Send {}. An in-flight purchase can still finish; funds stay reserved until its outcome is confirmed. If a number arrives, follow the normal cancellation policy.
Parameters
| Name | Location / required | Rules |
|---|---|---|
id | path · Required | UUID 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/stop' \
--header "Authorization: Bearer $GETSMS_API_KEY" \
--header 'Content-Type: application/json' \
--data '{}' \
--connect-timeout 10 --max-time 25200 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 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.
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
| Field | Type / requirement | Description |
|---|---|---|
balance | MoneyRequired | Total customer balance including reserved funds. |
reserved | MoneyRequired | Funds held for unresolved orders; not available for a new purchase. |
available | MoneyRequired | Spendable balance: balance minus reserved. |
currency | "USD"Required | USD. All wallet and order money is expressed in USD. |
Order
| Field | Type / requirement | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id | string (uuid)Required | Get SMS order UUID. Store as a string; do not use an upstream numeric ID. | ||||||||||||
service | stringRequired | Canonical catalog service ID, for example telegram. | ||||||||||||
country | stringRequired | Canonical catalog country ID; USA is usa, United Kingdom is england. Türkiye is unavailable. | ||||||||||||
operator | stringRequired | Use any from a current quote for a new order. A physical operator is not guaranteed. | ||||||||||||
phone | string | nullRequired | E.164 phone string with +. Null until a number is assigned. Never convert to a number. | ||||||||||||
status | stringRequired | 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. | ||||||||||||
price | MoneyRequired | Your Get SMS cost with the current site margin included. Four decimal places. | ||||||||||||
created_at | string (date-time)Required | Order creation time, ISO 8601 UTC. | ||||||||||||
expires_at | string (date-time) | nullRequired | Order expiry if known; null before assignment or when unavailable. | ||||||||||||
cancel_available_at | string (date-time) | nullRequired | Earliest cancellation time under the account policy; null if not known. Read this field instead of hard-coding a timer. | ||||||||||||
last_checked_at | string (date-time) | nullRequired | Most recent saved provider check; null if none. | ||||||||||||
sms | SMS[]Required | Chronologically ordered SMS records. More than one SMS can arrive.
|
SMS
| Field | Type / requirement | Description |
|---|---|---|
code | string | nullRequired | Code as a string (leading zeros preserved), or null if no code was extracted. |
body | stringRequired | Original SMS text. May contain sensitive data; do not log or send to analytics. |
received_at | string (date-time)Required | SMS arrival timestamp in UTC. Use to distinguish multiple messages. |
Catalog
| Field | Type / requirement | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
currency | "USD"Required | USD. All wallet and order money is expressed in USD. | ||||||||||||
services | object[]Required | Canonical service identifiers and display names.
| ||||||||||||
countries | object[]Required | Canonical country identifiers, display names and dialing codes.
|
Prices
| Field | Type / requirement | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
currency | "USD"Required | USD. All wallet and order money is expressed in USD. | |||||||||||||||||||||
checked_at | string (date-time)Required | Time this price response was produced. Prices can change before purchase. | |||||||||||||||||||||
prices | object[]Required | Available price-protected options. May be empty.
|
History
| Field | Type / requirement | Description | ||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
page | integerRequired | Current one-based page. | ||||||||||||||||||||||||||||||||||||||||||
limit | integerRequired | Page size: 1–50, default 20. | ||||||||||||||||||||||||||||||||||||||||||
total | integerRequired | Total account orders at query time. | ||||||||||||||||||||||||||||||||||||||||||
orders | Order[]Required | Page of saved orders belonging to this customer.
|
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
| State | Funds | What to do |
|---|---|---|
created / purchasing | Reserved | Acquisition is in progress. Do not create another purchase. |
pending | Reserved | Number assigned. Wait for SMS or cancel when allowed. |
received | Reserved until settlement | SMS arrived. Use its code; cancellation cannot refund delivered SMS. |
reconciliation | Reserved | Uncertain provider outcome. Keep the same intent; do not rebuy or promise a refund. |
finished | Charged | Order completed; may be automatic when stored SMS and provider closure coincide. SMS remains readable. |
cancelled / timeout / banned / failed | Settled according to the authoritative result | Unused 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.
- After a cancellation HTTP 200, inspect
data.statusand readGET /balance; do not assume that the order was cancelled or refunded. - If SMS arrives during cancellation, a HTTP 409
ORDER_CONFLICTcan follow saved delivery. ReadGET /orders/{id}with the same order UUID and display its SMS inreceivedorfinishedstate. Do not create another purchase. - 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.
| Result | Next action |
|---|---|
| 202 with an order | Store its Get SMS UUID and poll that order. No new purchase. |
| Timeout, malformed response, connection loss, 429 or 5xx | Honor Retry-After if present, then GET /requests/original-key. Keep the original key/body. |
| Recovery returns an order | Continue the recorded order. |
| Recovery returns 404 | The first call may still be validating. Retry the same POST with the same UUID and exact body, with backoff. |
| 409 PRICE_CHANGED | Read a new quote. Obtain approval for a genuinely new intent; never silently increase max_price. |
| 409 IDEMPOTENCY_CONFLICT | Recover 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
| Scope | Ceiling |
|---|---|
| All requests | 120/minute per key and per customer |
| New purchase attempts | 10/minute per customer |
| Order polls | 30/minute per customer |
| Order actions | 30/minute per customer |
| Active/resolving orders | 5 per customer, shared with website |
| Active API keys | 3 per customer |
| POST JSON body | 2,048 bytes |
| History | 1–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.
| HTTP | Code | Meaning / action |
|---|---|---|
| 400 | INVALID_REQUEST | Invalid identifier, UUID, JSON, amount or unsupported field. Correct the input. |
| 400 / 409 | REQUEST_REJECTED / ORDER_CONFLICT | A domain rule rejected the operation. Inspect message, current order, balance and active orders. |
| 401 | UNAUTHORIZED | Key missing, invalid, revoked, or customer account unavailable. Check your server configuration. |
| 404 | NOT_FOUND | Wrong endpoint, missing/foreign order, or purchase intent with no order recorded yet. Recovery 404 is not proof of failure. |
| 409 | IDEMPOTENCY_CONFLICT | Same intent UUID with a different body. Recover the original request; do not overwrite its mapping. |
| 409 | PRICE_PROTECTION_REQUIRED | New purchases require operator=any from a live price-protected quote. |
| 409 | PRICE_CHANGED | Current cost exceeds max_price. Fetch a new quote and obtain approval before starting a genuinely new intent. |
| 409 | NO_STOCK | No available protected quote. Do not blindly buy repeatedly. |
| 409 | WAIT_REQUIRED | Action is too early. Honor error.retry_after and Retry-After, then inspect the same order. |
| 413 | REQUEST_REJECTED | JSON body exceeds 2,048 bytes. Reduce it. |
| 415 | INVALID_REQUEST | Send Content-Type: application/json for POST. |
| 429 | RATE_LIMITED | Honor Retry-After; use backoff with jitter. Purchase retries keep their original intent key. |
| 503 | SALES_UNAVAILABLE | Sales or currency conversion settings are unavailable. Do not start a new intent automatically. |
| 503 | PROVIDER_UNAVAILABLE / SERVICE_UNAVAILABLE | Recover 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.