Numbers in. Codes out.

Your first request

Every request carries your API key as a Bearer token. Asking for your own account is a good way to check the key works — and to see your balance before you buy anything.

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

{
  "id": "usr_8Rk3VbX7nQ2mLw5TzP4c",
  "email": "you@example.com",
  "name": "Ada Lovelace",
  "balance": "24.86",
  "balance_micros": 24860000,
  "discount_bps": 0,
  "default_country": "US",
  "default_strategy": "best",
  "webhook_url": "https://example.com/webhooks/passcode",
  "created_at": "2026-09-14T08:21:37.000Z"
}

How it works

Four calls cover the whole job. Most integrations never need more.

1. 01GET/v1/quoteQuoteRanked prices, stock and success rates for a service, per country.
2. 02POST/v1/ordersOrderWe charge your balance and assign a number. Enter it in the app you're verifying.
3. 03GET/v1/orders/{id}Read the codePoll the order, or get a signed webhook the moment the SMS lands.
4. 04POST/v1/orders/{id}/finishFinishOr do nothing: orders that never get an SMS are refunded automatically.

Conventions

Format

JSON in and out, UTF-8, snake_case fields. Unknown body fields are rejected; ignore unknown response fields.

Money

Decimal US-dollar strings plus integer micro-dollars: "price": "0.14" and "price_micros": 140000. Do arithmetic on the micros.

IDs

Opaque strings with a type prefix: ord_ orders, rnt_ rentals, msg_ messages, ofr_ offers, evt_ events.

Timestamps

ISO 8601 in UTC, e.g. 2026-10-06T14:02:19.000Z.

Phone numbers

E.164, e.g. +12025550147.

Demo inventory

Simulator numbers and SMS carry demo: true. They behave like the real thing — delays, codes, refunds — with fictional numbers.

Versioning

The version is in the path. New fields, endpoints and events can appear in v1; breaking changes get a new version.

Endpoints

Where next