Skip to content

API reference

Orders

An order is one number for one service. Create it, put the number into the app you're verifying, and read the code when it arrives. Unused orders are refunded automatically.

Endpoints

Order lifecyclestatus
  1. Pending
    Paid; assigning a number
  2. Waiting
    Number ready, no SMS yet
  3. Received
    A code arrived
  4. Completed
    Finished, or past expires_at

Refunded in fullRefunded

  • from waitingCancelledYou cancelled it before any SMS arrived.
  • from waitingExpiredNo SMS before expires_at.
  • from pendingFailedNo number could be assigned.
Waiting window
Each order waits 20 minutes for an SMS (expires_at). No SMS by then: expired and refunded.
More than one SMS
Resends land on the same order until it ends. code is always the latest; messages keeps them all.
Refunds
Exactly once, to your balance, the moment an order is cancelled, expires or fails. See refunded_at.

Simulator inventory carries demo: true — fictional numbers, simulated SMS. The web app labels it wherever prices or stock are shown.

Invite-only for now

New accounts open after carrier registration is complete; until then, sign-ups go to a waitlist. Real carrier numbers return not_available for now. Everything else on this page is how the API behaves at launch.

The Order object

A one-time number bought for one service. The order waits for an SMS until expires_at; if none arrives it is refunded automatically.

Attributes

  • idstring

    Unique identifier, prefixed ord_.

  • statusstring

    pending (assigning a number) → waiting (number assigned, no SMS yet) → received (a code arrived) → completed. Refunded end states: cancelled, expired, failed.

  • serviceobject

    The service the number is for.

    Show child attributes
    • slugstring

      The service's stable identifier, e.g. whatsapp.

    • namestring

      Display name.

  • countryCountry object

    The number's country.

  • phone_numberstring· nullable

    The number in E.164 format. null until one is assigned.

  • pricestring

    Amount charged in US dollars, as a decimal string.

  • price_microsinteger

    Amount charged in micro-dollars (1 USD = 1,000,000).

  • codestring· nullable

    The latest verification code received, or null.

  • messagesarray of Message objects

    Every SMS received for this order, newest first.

  • strategystring

    The strategy used to pick the offer.

    One of:bestcheapestfastest

  • sourcestring

    Where the order was placed.

    One of:webapi

  • created_attimestamp

    When the order was created.

  • expires_attimestamp· nullable

    When the order stops waiting. Unused orders are refunded at this time.

  • received_attimestamp· nullable

    When the first SMS arrived.

  • completed_attimestamp· nullable

    When the order was completed.

  • cancelled_attimestamp· nullable

    When the order was cancelled.

  • refunded_attimestamp· nullable

    When the price was returned to your balance.

  • can_cancelboolean

    Whether Cancel an order would succeed now (waiting, no SMS yet).

  • can_finishboolean

    Whether Finish an order would succeed now (an SMS arrived).

  • demoboolean

    true for simulator inventory: fictional numbers and simulated SMS.

Order object · example
{
  "id": "ord_7Hq2LmX9vB3kR8tN4cYp",
  "status": "received",
  "service": {
    "slug": "whatsapp",
    "name": "WhatsApp"
  },
  "country": {
    "iso2": "US",
    "name": "United States",
    "dial_code": "+1"
  },
  "phone_number": "+12025550147",
  "price": "0.895",
  "price_micros": 895000,
  "code": "482913",
  "messages": [
    {
      "id": "msg_4mQ8rXc2LpV7nZ1kT9bW",
      "from": "32665",
      "body": "Your WhatsApp code: 482-913\nDon't share this code with others",
      "code": "482913",
      "received_at": "2026-10-06T14:02:19.000Z"
    }
  ],
  "strategy": "best",
  "source": "api",
  "created_at": "2026-10-06T14:02:03.000Z",
  "expires_at": "2026-10-06T14:22:03.000Z",
  "received_at": "2026-10-06T14:02:19.000Z",
  "completed_at": null,
  "cancelled_at": null,
  "refunded_at": null,
  "can_cancel": false,
  "can_finish": true,
  "demo": true
}

The Message object

An SMS received on an order's or rental's number.

Attributes

  • idstring

    Unique identifier, prefixed msg_.

  • fromstring

    Sender: a short code, phone number or alphanumeric sender ID.

  • bodystring

    Full message text.

  • codestring· nullable

    The verification code we extracted from body, or null when unsure.

  • received_attimestamp

    When the SMS arrived.

Message object · example
{
  "id": "msg_4mQ8rXc2LpV7nZ1kT9bW",
  "from": "32665",
  "body": "Your WhatsApp code: 482-913\nDon't share this code with others",
  "code": "482913",
  "received_at": "2026-10-06T14:02:19.000Z"
}

Create an order

POST/v1/orders

Buys a number for service and returns the order in waiting, with phone_number set. Enter that number in the app you're verifying, then poll Retrieve an order (or listen for the order.code_received webhook) until code is set.

Without offer_id we buy the top quote for strategy in country (or anywhere). Set max_price to refuse anything pricier. The price is charged when the order is created; if no SMS arrives before expires_at, it is refunded in full automatically.

Send an Idempotency-Key so a retried request can never buy twice. See Idempotency.

Headers

  • Idempotency-Keystring· optional

    A unique string (e.g. a UUID), up to 255 characters. Retrying the same request with the same key returns the original order; a different request with it fails with idempotency_conflict.

Body · application/json

  • servicestringRequired

    Service slug (or svc_ id), e.g. whatsapp.

  • countrystring· optional

    ISO2 country code, or any (the default) to let the strategy pick.

  • strategystring· optional

    How to pick the offer when offer_id is not given.

    One of:bestcheapestfastest

    Defaults to best.

  • max_pricestring | number· optional

    Highest price you accept, in USD ("0.50" or 0.5). Fails with price_above_max otherwise.

  • max_price_microsinteger· optional

    The same limit in micro-dollars. Send max_price or this, not both.

  • offer_idstring· optional

    Buy exactly this offer from Get quotes (ofr_…).

Returns

Returns an Order object.

  • 201The new order. Its URL is in the Location header.Location · Path of the order, e.g. /api/v1/orders/ord_….
  • 200The Idempotency-Key was used before: the original order in its current state, with Idempotent-Replayed: true. Nothing is charged.Idempotent-Replayed · Always true on a replay.Location · Path of the original order.

Errors

Any endpoint can also return unauthorized, account_disabled, rate_limited and internal_error, and method_not_allowed when called with another method.

curl 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",
    "max_price": "1.00"
  }'
Response · 201
{
  "id": "ord_7Hq2LmX9vB3kR8tN4cYp",
  "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": [],
  "strategy": "best",
  "source": "api",
  "created_at": "2026-10-06T14:02:03.000Z",
  "expires_at": "2026-10-06T14:22:03.000Z",
  "received_at": null,
  "completed_at": null,
  "cancelled_at": null,
  "refunded_at": null,
  "can_cancel": true,
  "can_finish": false,
  "demo": true
}

List orders

GET/v1/orders

Returns your orders newest first. Active orders are brought up to date first, so statuses are current. Page with limit and the next_cursor of the previous page (Pagination).

Query parameters

  • statusstring· optional

    Only these statuses. One status, or several separated by commas: waiting,received.

  • limitinteger· optional

    Page size, 1–100.

    Defaults to 25.

    Between 1 and 100.

  • cursorstring· optional

    next_cursor from the previous page.

Returns

  • 200A page of orders.
  • dataarray of Order objects

    Orders on this page.

  • has_moreboolean

    Whether another page follows.

  • next_cursorstring· nullable

    Pass as cursor to fetch the next page; null on the last page.

Errors

Any endpoint can also return unauthorized, account_disabled, rate_limited and internal_error, and method_not_allowed when called with another method.

curl -G https://passcode.sh/api/v1/orders \
  -H "Authorization: Bearer $PASSCODE_API_KEY" \
  -d status=received \
  -d limit=10
Response · 200
{
  "data": [
    {
      "id": "ord_7Hq2LmX9vB3kR8tN4cYp",
      "status": "completed",
      "service": {
        "slug": "whatsapp",
        "name": "WhatsApp"
      },
      "country": {
        "iso2": "US",
        "name": "United States",
        "dial_code": "+1"
      },
      "phone_number": "+12025550147",
      "price": "0.895",
      "price_micros": 895000,
      "code": "482913",
      "messages": [
        {
          "id": "msg_4mQ8rXc2LpV7nZ1kT9bW",
          "from": "32665",
          "body": "Your WhatsApp code: 482-913\nDon't share this code with others",
          "code": "482913",
          "received_at": "2026-10-06T14:02:19.000Z"
        }
      ],
      "strategy": "best",
      "source": "api",
      "created_at": "2026-10-06T14:02:03.000Z",
      "expires_at": "2026-10-06T14:22:03.000Z",
      "received_at": "2026-10-06T14:02:19.000Z",
      "completed_at": "2026-10-06T14:03:40.000Z",
      "cancelled_at": null,
      "refunded_at": null,
      "can_cancel": false,
      "can_finish": false,
      "demo": true
    }
  ],
  "has_more": true,
  "next_cursor": "MjAyNi0xMC0wNlQxNDowMjowMy4wMDBafG9yZF83SHEy"
}

Retrieve an order

GET/v1/orders/{id}

Returns the order, settled first: a due SMS is attached and an overdue order is expired and refunded before we respond. Poll this every 2–5 seconds while status is waiting, or use webhooks.

Path parameters

  • idstringRequired

    The order id (ord_…).

Returns

Returns an Order object.

  • 200The order.

Errors

Any endpoint can also return unauthorized, account_disabled, rate_limited and internal_error, and method_not_allowed when called with another method.

curl https://passcode.sh/api/v1/orders/ord_7Hq2LmX9vB3kR8tN4cYp \
  -H "Authorization: Bearer $PASSCODE_API_KEY"
Response · 200
{
  "id": "ord_7Hq2LmX9vB3kR8tN4cYp",
  "status": "received",
  "service": {
    "slug": "whatsapp",
    "name": "WhatsApp"
  },
  "country": {
    "iso2": "US",
    "name": "United States",
    "dial_code": "+1"
  },
  "phone_number": "+12025550147",
  "price": "0.895",
  "price_micros": 895000,
  "code": "482913",
  "messages": [
    {
      "id": "msg_4mQ8rXc2LpV7nZ1kT9bW",
      "from": "32665",
      "body": "Your WhatsApp code: 482-913\nDon't share this code with others",
      "code": "482913",
      "received_at": "2026-10-06T14:02:19.000Z"
    }
  ],
  "strategy": "best",
  "source": "api",
  "created_at": "2026-10-06T14:02:03.000Z",
  "expires_at": "2026-10-06T14:22:03.000Z",
  "received_at": "2026-10-06T14:02:19.000Z",
  "completed_at": null,
  "cancelled_at": null,
  "refunded_at": null,
  "can_cancel": false,
  "can_finish": true,
  "demo": true
}

Cancel an order

POST/v1/orders/{id}/cancel

Cancels a waiting order with no messages and refunds it in full, exactly once. Cancelling an already-cancelled order returns it unchanged.

Once an SMS has arrived the order can't be cancelled (invalid_state); finish it instead.

Path parameters

  • idstringRequired

    The order id (ord_…).

Body

No body. Send an empty POST.

Returns

Returns an Order object.

  • 200The cancelled order.

Errors

Any endpoint can also return unauthorized, account_disabled, rate_limited and internal_error, and method_not_allowed when called with another method.

curl -X POST https://passcode.sh/api/v1/orders/ord_7Hq2LmX9vB3kR8tN4cYp/cancel \
  -H "Authorization: Bearer $PASSCODE_API_KEY"
Response · 200
{
  "id": "ord_7Hq2LmX9vB3kR8tN4cYp",
  "status": "cancelled",
  "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": [],
  "strategy": "best",
  "source": "api",
  "created_at": "2026-10-06T14:02:03.000Z",
  "expires_at": "2026-10-06T14:22:03.000Z",
  "received_at": null,
  "completed_at": null,
  "cancelled_at": "2026-10-06T14:04:12.000Z",
  "refunded_at": "2026-10-06T14:04:12.000Z",
  "can_cancel": false,
  "can_finish": false,
  "demo": true
}

Finish an order

POST/v1/orders/{id}/finish

Completes a received order once you've used the code. Orders with a code also complete on their own at expires_at; finishing early just releases the number sooner. Finishing a completed order returns it unchanged.

Path parameters

  • idstringRequired

    The order id (ord_…).

Body

No body. Send an empty POST.

Returns

Returns an Order object.

  • 200The completed order.

Errors

Any endpoint can also return unauthorized, account_disabled, rate_limited and internal_error, and method_not_allowed when called with another method.

curl -X POST https://passcode.sh/api/v1/orders/ord_7Hq2LmX9vB3kR8tN4cYp/finish \
  -H "Authorization: Bearer $PASSCODE_API_KEY"
Response · 200
{
  "id": "ord_7Hq2LmX9vB3kR8tN4cYp",
  "status": "completed",
  "service": {
    "slug": "whatsapp",
    "name": "WhatsApp"
  },
  "country": {
    "iso2": "US",
    "name": "United States",
    "dial_code": "+1"
  },
  "phone_number": "+12025550147",
  "price": "0.895",
  "price_micros": 895000,
  "code": "482913",
  "messages": [
    {
      "id": "msg_4mQ8rXc2LpV7nZ1kT9bW",
      "from": "32665",
      "body": "Your WhatsApp code: 482-913\nDon't share this code with others",
      "code": "482913",
      "received_at": "2026-10-06T14:02:19.000Z"
    }
  ],
  "strategy": "best",
  "source": "api",
  "created_at": "2026-10-06T14:02:03.000Z",
  "expires_at": "2026-10-06T14:22:03.000Z",
  "received_at": "2026-10-06T14:02:19.000Z",
  "completed_at": "2026-10-06T14:03:40.000Z",
  "cancelled_at": null,
  "refunded_at": null,
  "can_cancel": false,
  "can_finish": false,
  "demo": true
}