Skip to main content
POST
Purchases one available US Voice number. First search available numbers and quote a number. Requires voice_calls.write, the Voice Calls product entitlement, and an API key created by a current account owner. Your account must also pass the existing reseller and billing checks. The 202 response acknowledges a durable acquisition attempt, not completed ownership. Follow its Location header to read the operation. If the response is lost or the outcome is uncertain, retry with the same requestId and identical body; do not use a new request ID for the same intended purchase.

Body Parameters

string
required
Stable purchase identity: 1–128 printable ASCII characters without spaces.
string
required
An unused, unexpired token from your account’s available-number search.
object
required
Exactly quoteId and consentVersion from a priced quote. Obtain the account owner’s consent to that quote before sending this request.

Response Fields

string
The acquisition operation ID.
string
The durable status; complete confirms acquisition, while outcome_unknown requires recovery.
object
The acquisition result when complete.
string | null
A failure code, when present.

Example

Error Codes