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.
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. inboundInstructions (≤8,000 characters) says who the agent is and what the line is for — null restores the default assistant that takes messages and notes; inboundGreeting (≤500 characters) is its first line — null uses a short default greeting, by first name for a known contact; inboundVoice must be a Dairo Live voice id (any other value is a 400); and inboundLanguage is the ISO code it speaks. After an inbound call, the summary, the caller's structured notes, and the transcript arrive in the bound inbox as a voice message whose channelMetadata carries callId, callerNumber, dialedNumber, durationSeconds, summary, and notes, firing the normal message.received event. Provide at least one field or the request is a 400. Each inboxId/agentId must name a resource this account owns; an id you do not own is rejected with a 400 rather than silently bound. Pass null for inboxId or agentId to unbind. See inbound calls. Requires the phone:write scope.
Scope: phone:write. 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. |
Body
Required, application/json: PhoneNumberUpdateRequest.
At least one property is required. An explicit null unbinds (inboxId, agentId) or resets an inbound* field to its default.
| Field | Type | Required | Description |
|---|---|---|---|
inboxId | string (uuid) or null | no | |
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. |
metadata | object | no |
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). |
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).
Release a phone number back to the pool
Releases an owned number back to the carrier pool and stops its monthly billing.