開発者 API
Get SMS 残高を使用してアプリに 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"
}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.