Skip to main content
POST /v1/projects/{id}/platforms/sms/numbers Buys one US local number from the provider and records it as a resource with SMS enabled. Requires countryCode (US) and accepts an optional three-digit geographic areaCode. The server selects an exact matching number. Empty inventory keeps the operation running until a number is available or the caller cancels before ordering begins. Always answers 202 with an operation: the work runs behind the response, and the Location points at the operation to poll. New area-specific requests must appear in current provider coverage; discover it with GET /sms/numbers/area-codes?countryCode=US. Coverage and subscription checks run before operation creation. Billing follows delivery. Replays return the original operation without checking current coverage. The Idempotency-Key is required and permanent: repeating it returns the same operation forever, never a second number. A further number always needs a NEW key, including while others are still running. Requires the platforms:write permission bound to the project resource in the path.
TypeScript

Parameters

string
required
Identifies one logical mutation across retries.
string
required

Body

string
"US"
required

Returns

202 The purchase was accepted and is running. GET the Location after the Retry-After interval until state is terminal; the response there carries the number once it exists. Operation Headers: Location. The raw response carries these headers; see Raw responses.
boolean
required
string (date-time)
required
object
string (date-time)
OperationError
string
required
string
required
OperationReason
string
string
required
string (date-time)
OperationState
required
OperationType
required
string (date-time)
required