Getting started

Idempotency

Networks fail. A timeout after you sent a purchase leaves you not knowing whether it went through. An idempotency key makes the retry safe: you get the original order or rental, and you're never charged twice.

How it works

Send an Idempotency-Key header with Create an order or Rent a number — any unique string up to 255 printable characters; a UUID is ideal. Generate it once per purchase you intend to make, and reuse it on every retry of that purchase.

Terminal

KEY=$(uuidgen)   # one key per intended purchase

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

# Timed out? Send the exact same request again with the same $KEY.

Replays and conflicts

First request: 201 Created and the new order or rental.
Same key, same request: 200 OK, the original in its current state, and Idempotent-Replayed: true. Nothing is charged.
Same key, different body: 409 idempotency_conflict, with the original in details.order_id (or details.rental_id). A changed max_price counts: it’s never silently ignored.
Concurrent retries: Exactly one is created; every request gets it back.
Lifetime: Keys are stored with what they created and don't expire. They're scoped to your account, separately for orders and rentals.

The request is compared after normalizing it: "us" and "US", or max_price: "1.00" and max_price_micros: 1000000, are the same request. Requests rejected before anything exists (invalid parameters, insufficient balance) don’t consume the key. One that created an order which then failed — no_inventory with a details.order_id — did: that key now belongs to the failed, refunded order, so use a new key to try again.

Which requests

Create an order and Rent a number — support Idempotency-Key.
Cancel and finish are idempotent by nature: repeating them returns the same order, and a refund happens exactly once.
Update a rental sets auto_renew to the value you send, so repeating it is harmless.
GET requests never change anything.