Idempotency keys

Buying a phone number charges your wallet, so the purchase endpoint requires an Idempotency-Key to make retries safe.

Purchase a phone number charges the wallet and then orders the number from the carrier. A network failure in the middle of that could leave you unsure whether you were charged, so the endpoint requires an Idempotency-Key header. Other endpoints ignore the header.

How it works

1. Generate a unique value per purchase, for example a UUID, and send it as Idempotency-Key.
2. If the request fails before you get a response, retry with the same key and the same body.
3. If the first attempt finished, the retry returns the stored response (same status and body) with the header Idempotent-Replayed: true and no new charge.
4. If the first attempt failed before anything was charged, the key is released and the retry runs normally.

KEY=$(uuidgen)
curl -X POST "https://api.centerfy.ai/webhooks/inbound/phone-numbers/purchase" \
  -H "x-api-key: $CENTERFY_API_KEY" \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155550123" }'

Rules

Situation	Result
Header missing or malformed (must be 1–255 printable characters, no spaces)	400
Same key, same body, first request finished	Stored response replayed, Idempotent-Replayed: true
Same key, different body	409 “this Idempotency-Key was already used with a different request”
Same key while the first request is still running	409 “a request with this Idempotency-Key is still in progress”
Order failed after the wallet was charged	The charge is refunded automatically; the response says refunded: true

Keys are scoped to your sub-account, so two sub-accounts can use the same value without colliding.

The Node SDK takes the key as { idempotencyKey } in the options argument; the CLI generates one for you.