Provision a phone number
Provisions the exact number a prior available search returned, passed as phoneNumber in E.164, and starts recurring monthly billing for it.
Provisions the exact number a prior available search returned, passed as phoneNumber in E.164, and starts recurring monthly billing for it. In countries that require registration documents before a number can be used, the order settles with status: "pending" and a requirements block describing the paperwork rather than failing — the number is reserved, and the next step is registration, not a retry. A number this account already holds returns 409, and a number held by another account or lost to a concurrent purchase returns 409 reporting it is not available. See phone numbers for the full provisioning flow. Requires the phone:write scope.
Scope: phone:write. Send the API key as a bearer token; Scopes lists what each one reaches.
Request
Body
Required, application/json: PhoneNumberBuyRequest.
| Field | Type | Required | Description |
|---|---|---|---|
phoneNumber | string | yes | E.164, exactly as returned by the availability search. |
Response
201 Created. Body: application/json, PhoneNumber.
| Field | Type | Required | Description |
|---|---|---|---|
object | "phone_number" | yes | |
id | string (uuid) | yes | |
phoneNumber | string | yes | E.164. |
countryCode | string | yes | |
numberType | "local", "toll_free", "national", "mobile" | yes | |
capabilities | array of string | no | |
status | "pending", "active", "releasing", "released", "failed" | yes | pending means the provider reserved the number but regulatory documents are still outstanding (common for German local numbers). It is not an error. |
inboxId | string (uuid) or null | no | When set, every inbound call to this number (summary, the caller's notes and the transcript) lands in that inbox as a channel: "voice" message. |
agentId | string (uuid) or null | no | |
inboundInstructions | string or null | no | Who the inbound agent is and what the line is for. null = the default assistant that takes messages and notes. (max length 8000) |
inboundGreeting | string or null | no | Opening line for inbound calls. null = a short default greeting (by first name for a known contact). (max length 500) |
inboundVoice | "marin", "cedar", "alloy", "ash", "ballad", "coral", "echo", "sage", "shimmer", "verse", "quartz", "ripple", "vesper", "willow", "stone", "gleam", "meridian", "bossa", "tempo", "beacon", "delta", "cinder", null | no | Dairo Live voice id for the inbound agent. |
inboundLanguage | string or null | no | ISO language code the inbound agent speaks. |
monthlyCostUsd | number or null | no | |
setupCostUsd | number or null | no | |
requirements | object | no | Outstanding regulatory requirements, when status is pending. |
metadata | object | no | |
purchasedAt | string (date-time) or null | no | |
releasedAt | string (date-time) or null | no | |
createdAt | string (date-time) | yes |
Errors
Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.
| Status | Meaning |
|---|---|
400 | The request is malformed or a value is invalid (invalid_request, invalid_domain, idempotency_key_mismatch). |
401 | The API key is missing or invalid. |
403 | The key lacks the scope this endpoint needs (scope_missing) or may not do this (not_permitted). |
404 | No such resource in this account (resource_not_found). |
409 | The resource already exists or its state does not allow this (duplicate_resource or a condition-specific code). |
429 | Rate limit, plan limit, budget or spend cap reached (rate_limited, plan_limit_reached, budget_exceeded, spend_cap_reached). |
500 | An unexpected error; retry with backoff, then contact support (internal_error). |