Skip to content

API & developers

API quickstart

Create a key, get quotes, order a number and read the code — the whole flow in a handful of curl requests.

Last updated
Updated
Reading time
1 min read
On this page6
  1. 1. Create an API key
  2. 2. Check your balance
  3. 3. Get quotes
  4. 4. Order a number
  5. 5. Get the code
  6. 6. Finish or cancel

The REST API covers buying and using numbers: quotes, orders and their codes, and rentals with their inboxes. Adding funds, API keys and webhook settings live in the dashboard. Requests and responses are JSON, and you authenticate with a bearer API key. This walk-through uses curl; the API docs have the full reference with JavaScript and Python examples.

1. Create an API key

Go to API keys and create one. It's shown once, so copy it somewhere safe, then make it available to your shell:

Shell
export PASSCODE_API_KEY="pc_live_…"

2. Check your balance

Shell
curl https://passcode.sh/api/v1/me \
  -H "Authorization: Bearer $PASSCODE_API_KEY"

3. Get quotes

Shell
curl "https://passcode.sh/api/v1/quote?service=whatsapp&country=US" \
  -H "Authorization: Bearer $PASSCODE_API_KEY"

Quotes come back ranked by strategy — best unless you pass strategy=cheapest or strategy=fastest. Amounts are decimal USD strings like "0.14", with exact integer *_micros fields alongside (1 USD = 1,000,000 micros).

4. Order a number

Shell
curl -X POST https://passcode.sh/api/v1/orders \
  -H "Authorization: Bearer $PASSCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"service": "whatsapp", "country": "US"}'

The response includes the order. phone_number is the number to use, and expires_at is when its 20-minute window closes:

JSON
{
  "id": "ord_…",
  "status": "waiting",
  "service": { "slug": "whatsapp", "name": "WhatsApp" },
  "country": { "iso2": "US", "name": "United States", "dial_code": "+1" },
  "phone_number": "+12025550147",
  "price": "0.895",
  "price_micros": 895000,
  "code": null,
  "messages": [],
  "expires_at": "2026-10-06T14:20:00.000Z",
  "can_cancel": true,
  "can_finish": false,
  "demo": true
}

The Idempotency-Key makes the request safe to retry — see Idempotent orders.

5. Get the code

Either poll the order until status is received and code is set — every few seconds is plenty:

Shell
curl https://passcode.sh/api/v1/orders/ord_… \
  -H "Authorization: Bearer $PASSCODE_API_KEY"

…or set a webhook URL in Settings and we'll POST an order.code_received event to you the moment the SMS arrives. See Webhooks and signature verification.

6. Finish or cancel

  • POST /api/v1/orders/{id}/finish once you've used the code.
  • POST /api/v1/orders/{id}/cancel if no SMS has arrived and you want your money back now. Otherwise the order expires and refunds itself after 20 minutes.

Tip

During the beta, orders use demo inventory. The flow, responses and webhooks are identical, so you can build your integration today. The demo field tells you which is which.