REST API Reference

Authentication

Two ways:

• JWT (web / dashboard): POST /api/sms/auth/login returns a token; send it as Authorization: Bearer <token>. There is also POST /api/sms/auth/register and GET /api/sms/auth/me.
• API Key (server integration, recommended): create it in the dashboard and send X-API-Key: psk_xxx (keys start with psk_). An IP allowlist can be set per key.

Base URL

https://api.simsmsbox.com

Catalog lookup (before ordering)

You must look up available countries, services and card kinds first to get the order parameters. The service you pass to an order is the service code returned by market (e.g. instagram) — not the display name "Instagram".

# Available countries (flag / name / service count)
curl "https://api.simsmsbox.com/api/sms/shop/countries" -H "X-API-Key: psk_xxx"

# Number types (card-kind dictionary, e.g. physical / virtual)
curl "https://api.simsmsbox.com/api/sms/shop/number-types" -H "X-API-Key: psk_xxx"

# Services & per-provider offers for a country (sorted by price; includes each service code and stock)
curl "https://api.simsmsbox.com/api/sms/shop/market?country=US&cardKind=physical" -H "X-API-Key: psk_xxx"

Place an order

Orders use price-first smart routing. service accepts either the service code or the display name from market (e.g. instagram or Instagram), and country accepts the code or name (US / us), both case-insensitive; just make sure the item's stock > 0, otherwise you get "no available platform". rentDays is the number's validity in days (1–30); a real SIM number can receive codes repeatedly for the same app within that window, and is released automatically when it expires.

# Single order (service = the market 'service' code, not the display name)
curl -X POST https://api.simsmsbox.com/api/sms/orders/purchase \
  -H "X-API-Key: psk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"service":"instagram","country":"US","cardKind":"physical","rentDays":30}'

# Batch order (one per number, returns per-item result + success/failed counts)
curl -X POST https://api.simsmsbox.com/api/sms/orders/purchase-batch \
  -H "X-API-Key: psk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"service":"instagram","country":"US","cardKind":"physical","rentDays":30,"quantity":5}'

Request body fields:

• service (required) service code or display name from market service/serviceName (e.g. instagram or Instagram), case-insensitive
• country (required) country code or name from market country (e.g. US / us), case-insensitive
• cardKind (optional) physical / virtual; empty = cheapest available
• rentDays (optional) validity 1–30, default 30; reusable within the window
• platformCode (optional) pin a provider; empty = smart routing
• includeSegment / operator (optional) number prefix / carrier filter
• quantity (purchase-batch only) batch size, default 1

The order response returns orderId, displayOrderNo and apiBindingKey; after ordering, fetch the code via the "Receive URL" below using apiBindingKey — do not use the order-query endpoint to poll for codes.

Receive URL (fetch the code after ordering · recommended)

After a successful order, use the apiBindingKey from the order response to call the fixed "Receive URL" /api/sms/record and pull the order's latest code in real time — this is the recommended way to get the code. Only our URL is exposed, never the upstream provider; this endpoint needs no auth header (the key authorizes it). You can also customize the response template under "Receive settings".

Response format (the format param):

• Default (no format): JSON with status (YES=received / NO=not yet) and data (orderNo/phone/content/codeValue…). If you configured a template under "Receive settings", it is rendered instead.
• format=json: force JSON.
• format=txt: minimal text STATUS|content — received is YES|<full SMS content>, not yet is NO|.

# Receive URL: default JSON (key = the apiBindingKey from the order)
curl "https://api.simsmsbox.com/api/sms/record?key={apiBindingKey}"

# Minimal text: YES|123456 or NO|
curl "https://api.simsmsbox.com/api/sms/record?key={apiBindingKey}&format=txt"

# Relay base URL (used to build the public record link; configurable in settings)
curl https://api.simsmsbox.com/api/sms/orders/base-url -H "X-API-Key: psk_xxx"

Order status / my orders (not for fetching codes)

To get the code, use the "Receive URL" above; these endpoints are for order status, validity and SMS history. {id} accepts either the numeric order id (the orderId from purchase, e.g. 19) or the order number (displayOrderNo, e.g. S2606…).

# A single order's details (status, expireAt; latestCode is a convenience field — for real-time fetching use the Receive URL above); {id} = orderId or displayOrderNo
curl https://api.simsmsbox.com/api/sms/orders/{id} -H "X-API-Key: psk_xxx"

# My orders (filterable by status)
curl "https://api.simsmsbox.com/api/sms/orders/mine?page=1&pageSize=20" -H "X-API-Key: psk_xxx"

# All SMS messages I received
curl "https://api.simsmsbox.com/api/sms/orders/messages?page=1&pageSize=20" -H "X-API-Key: psk_xxx"

Order actions

• POST /api/sms/orders/{id}/cancel cancel (refundable if no code received)
• POST /api/sms/orders/{id}/renew renew, body {"days": 7}
• POST /api/sms/orders/{id}/rotate rotate number
• POST /api/sms/orders/{id}/blacklist blacklist the current number

# Renew for 7 days
curl -X POST https://api.simsmsbox.com/api/sms/orders/{id}/renew \
  -H "X-API-Key: psk_xxx" -H "Content-Type: application/json" \
  -d '{"days":7}'

Bulk TOKEN export / query

# Export TOKENs: multi-line "number----relayURL" text (scope: selected/current/renewal/all)
curl -X POST https://api.simsmsbox.com/api/sms/orders/export-tokens \
  -H "X-API-Key: psk_xxx" -H "Content-Type: application/json" \
  -d '{"scope":"all"}'

# Look up order tokens by a batch of keys or numbers (with latest code / status)
curl -X POST https://api.simsmsbox.com/api/sms/orders/query-tokens \
  -H "X-API-Key: psk_xxx" -H "Content-Type: application/json" \
  -d '{"terms":["+1xxxx","psk_orderkey_xxx"]}'

Wallet

# Balance (balance / frozenAmount / totalRecharge / totalConsume)
curl https://api.simsmsbox.com/api/sms/wallet/balance -H "X-API-Key: psk_xxx"
# Transactions
curl "https://api.simsmsbox.com/api/sms/wallet/txs?page=1&pageSize=20" -H "X-API-Key: psk_xxx"

API Key management

Use JWT (Authorization: Bearer) for these. After creation you can view and copy the full key anytime on the API Key page in the dashboard.

# List
curl https://api.simsmsbox.com/api/sms/api-keys -H "Authorization: Bearer <token>"
# Create (returns { id, key }; also viewable later on the API Key page)
curl -X POST https://api.simsmsbox.com/api/sms/api-keys \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"name":"server-1"}'
# Revoke
curl -X DELETE https://api.simsmsbox.com/api/sms/api-keys/{id} -H "Authorization: Bearer <token>"

Note: the example domain https://api.simsmsbox.com is our API domain. If you self-host, replace it with your own domain. For the full field list and all endpoints, see the live Swagger UI at /swagger.

Try it online

Want to fill in your API Key and test in real time? Pick either option: