Retrieve a phone number
Retrieves one owned phone number by id, in the same shape as a row from the list endpoint: status, capabilities, monthlyCostUsd, setupCostUsd, requirements, metadata, its inboxId/agentId bindings, and its inbound agent (inboundInstructions, inboundGreeting, inboundVoice, inboundLanguage; null means the default).
Retrieves one owned phone number by id, in the same shape as a row from the list endpoint: status, capabilities, monthlyCostUsd, setupCostUsd, requirements, metadata, its inboxId/agentId bindings, and its inbound agent (inboundInstructions, inboundGreeting, inboundVoice, inboundLanguage; null means the default). A number that belongs to another account, or one that never existed, returns 404. Requires the phone:read scope.
Scope: phone:read. Send the API key as a bearer token; Scopes lists what each one reaches.
Request
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | The phone number's ID. |
Response
200 Success. 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). |
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). |
Search available phone numbers to buy
Searches carrier inventory for numbers you can buy — this reads live availability, not the numbers you already own.
Update a phone number's inbox, agent, inbound agent, or metadata
Configures an owned number: bind it to an inbox with inboxId — every call it answers then lands in that mailbox alongside your other channels — assign it to an agent with agentId, replace its metadata (a JSON object of at most 8 KiB; null clears it, anything else is a 400), and set up the agent that answers when someone calls it.