Claim an available inventory DID into the workspace
Server-side proration debits the workspace wallet for the
remainder of the current billing month. Idempotency via the
Idempotency-Key header (preferred) — the body's
idempotency_key field is accepted for backwards compatibility
but deprecated. If both are supplied, the header wins.
Authorization
bearerAuth Long-lived ES256 JWT minted from the dashboard (https://app.sautikit.com/developers/api-keys). Signed by the
platform keyring. Carries workspace_id and scopes claims;
revoked via the platform deny-list.
In: header
Path Parameters
The inventory_id to claim.
uuidHeader Parameters
Client-supplied idempotency key. Reusing the same key against the same workspace returns the original ledger entry instead of a duplicate debit.
length <= 64Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
curl -X POST "https://example.com/v1/numbers/497f6eca-6276-4993-bfeb-53cbbbba6f08/claim" \ -H "Content-Type: application/json" \ -d '{ "idempotency_key": "claim-2026-07-19-a1b2c3" }'{ "number": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9", "e164": "string", "friendly_name": "string", "status": "active", "assigned_at": "2019-08-24T14:15:22Z" }, "prorated_minor": 0, "monthly_minor": 0, "currency": "string", "next_renewal_at": "2019-08-24T14:15:22Z"}{ "error": { "code": "validation.bad_request", "message": "string", "request_id": "string" }}{ "error": { "code": "validation.bad_request", "message": "string", "request_id": "string" }}