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

Query codes / my orders

{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 (with latestCode, status, expireAt); {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"

Custom receive URL (recommended for integration)

An order response contains an apiBindingKey. With that key you can fetch the order's latest SMS from one fixed URL in real time — only our URL is exposed, never the upstream provider. This endpoint needs no auth header; the key authorizes it.

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|.

# Default JSON
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 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: