Get started with the SimSmsBox API in 5 minutes

This tutorial walks you through SimSmsBox’s core flow in 5 minutes: order a number → receive the code → cancel (optional).

Prerequisites

Sign up and log in to the dashboard.
Top up a small balance under “Wallet” (used for per-order charging).
Create a key on the “API Key” page, formatted like psk_xxxxxxxx.

All endpoints authenticate via the X-API-Key request header.

Step 1: Look up available apps and prices for a country

curl "https://api.simsmsbox.com/api/sms/shop/market?country=US&cardKind=physical" \
  -H "X-API-Key: psk_xxxxxxxx"

The response lists the real-time price and stock for each app (e.g. telegram) in that country; the service field is the service code you pass when ordering.

Step 2: Order a number (create an order)

curl -X POST https://api.simsmsbox.com/api/sms/orders/purchase \
  -H "X-API-Key: psk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"service":"telegram","country":"US","cardKind":"physical","rentDays":30}'

Response (includes apiBindingKey, the credential for the receive URL):

{ "orderId": 19, "phone": "+1xxxxxxxxxx", "status": "waiting", "apiBindingKey": "psk_orderkey_xxx" }

Step 3: Get the code (use the receive URL, recommended)

After ordering, use the apiBindingKey from the previous step to call the fixed receive URL /api/sms/record and pull the code in real time. This URL stays valid for the whole rental window, can be called repeatedly, and needs no X-API-Key (the key itself authorizes it):

# Minimal text: received -> YES|123456, not yet -> NO|
curl "https://api.simsmsbox.com/api/sms/record?key=psk_orderkey_xxx&format=txt"

# Or default JSON (status=YES/NO; data holds the full SMS and codeValue)
curl "https://api.simsmsbox.com/api/sms/record?key=psk_orderkey_xxx"

Example response once received:

YES|123456

The receive URL stays usable throughout the order’s validity — you also collect repeat codes for the same app here. To just check order status/validity, use GET /api/sms/orders/19 (its latestCode is a convenience field, not the primary way to fetch codes).

Step 4: Cancel the order (optional)

If no code arrives and you want a different number, cancel it — uncoded orders are refunded automatically:

curl -X POST https://api.simsmsbox.com/api/sms/orders/19/cancel \
  -H "X-API-Key: psk_xxxxxxxx"

Next steps

Learn to poll automatically: Automated ordering and polling
Learn templated receiving: Custom receive URL and templated responses

← Back to Tutorials

⚡Get started with the SimSmsBox API in 5 minutes