⚡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

1. Sign up and log in to the dashboard.
2. Top up a small balance under “Wallet” (used for per-order charging).
3. 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:

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

Step 3: Poll for the verification code

Use the orderId from the previous step as {id}:

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

Once received, the code is in the latestCode field:

{ "orderId": 19, "status": "received", "latestCode": "123456" }

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