Phone Numbers
Manage the phone numbers associated with your organization. Provision local numbers, configure how incoming calls are handled, and release numbers when no longer needed.
Provision phone number POST
POST /numbersProvision a new phone number for your organization. Searches available carrier inventory, places an order, and registers the number to your account.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
agent_handle | string | Yes | Agent identity handle to provision this number for (e.g. "sales-agent" or "@sales-agent"). Leading @ is stripped. |
type | string | No | "local" (default). Only "local" is supported. |
state | string | No | US state code (e.g. "NY") to request a number in that state |
incoming_call_action | string | No | How to handle incoming calls: "hosted_agent" (Inkbox Voice AI answers; requires neither URL — the default where Inkbox Voice AI is available), "auto_accept", "auto_reject" (the default otherwise), or "webhook" |
client_websocket_url | string | No | WebSocket URL (wss://) that Inkbox connects to when a call starts. Can carry text or audio, depending on how the connection is configured. Required when incoming_call_action is "auto_accept" |
incoming_call_webhook_url | string | No | HTTPS URL for incoming call webhooks. Required when incoming_call_action is "webhook" |
Filter mode now lives on the agent identity as
phone_filter_mode— see Manage identities.
Text webhook delivery has moved. Configure text events (
text.received,text.sent,text.delivered,text.delivery_failed,text.delivery_unconfirmed) via the Webhook Subscriptions API. Incoming-call webhooks stay on this resource because the response body drives whether Inkbox answers the call.
Request example
JSONResponse (201)
JSONWhere Inkbox Voice AI is available, new numbers are provisioned with incoming_call_action set to hosted_agent — the number answers with zero setup right away. Otherwise the default is auto_reject. Update the number to change how incoming calls are handled.
Error responses
| Status | Description |
|---|---|
| 404 | Identity with the given agent_handle not found, or no available numbers matching the criteria |
| 409 | The identity already has a phone number — each identity can hold at most one number |
| 429 | Organization already has 3 active phone numbers. Release an existing number before provisioning a new one |
| 502 | Carrier provisioning failed |
Code examples
cURLRelease phone number DELETE
DELETE /numbers/{phone_number_id}Release a phone number from your organization. The number is returned to the carrier and stops counting against your organization's active-number cap. Returns 204 No Content on success.
Caution: Releasing a number is irreversible. The number is returned to the carrier and you may not be able to reclaim it.
Path parameters
| Parameter | Type | Description |
|---|---|---|
phone_number_id | UUID | Unique identifier of the phone number to release |
Response (204)
Returns no content.
Error responses
| Status | Description |
|---|---|
| 403 | Number does not belong to your organization |
| 404 | Phone number not found |
| 502 | Carrier release failed — retry shortly |
Code examples
cURLList phone numbers GET
GET /numbersList all phone numbers for your organization.
Response (200)
JSONCode examples
cURLGet phone number GET
GET /numbers/{phone_number_id}Get a single phone number by ID.
Path parameters
| Parameter | Type | Description |
|---|---|---|
phone_number_id | UUID | Unique identifier of the phone number |
Response (200)
Returns a phone number object.
Error responses
| Status | Description |
|---|---|
| 403 | Number does not belong to your organization |
| 404 | Phone number not found |
Code examples
cURLUpdate phone number PATCH
PATCH /numbers/{phone_number_id}Update the configuration for a phone number. All fields are optional — only the fields you provide will be updated.
Path parameters
| Parameter | Type | Description |
|---|---|---|
phone_number_id | UUID | Unique identifier of the phone number |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
incoming_call_action | string | No | How to handle incoming calls: "auto_accept", "auto_reject", "webhook", or "hosted_agent" (Inkbox Voice AI answers; requires neither URL) |
client_websocket_url | string | No | WebSocket URL (wss://) that Inkbox connects to when a call starts. Can carry text or audio, depending on how the connection is configured. Required when incoming_call_action is "auto_accept" |
incoming_call_webhook_url | string | null | No | HTTPS URL for incoming call webhooks. Required when incoming_call_action is "webhook". Set to null to unsubscribe. |
Filter mode now lives on the agent identity as
phone_filter_mode— see Manage identities.
Text webhook delivery has moved. Configure text events via the Webhook Subscriptions API.
Request example
JSONResponse (200)
Returns the updated phone number object.
Error responses
| Status | Description |
|---|---|
| 403 | Number does not belong to your organization |
| 404 | Phone number not found |
Code examples
cURLPhone number object
| Field | Type | Description |
|---|---|---|
id | UUID | Unique phone number identifier |
number | string | Phone number in E.164 format (e.g. "+14155550100") |
type | string | Number type. Always "local". |
state | string | null | 2-letter US state abbreviation (e.g. "CA"); null if not set |
status | string | Lifecycle status: "active" or "paused" |
sms_status | string | Outbound-SMS provisioning readiness: "pending", "ready", or "assignment_failed". Only "ready" numbers can send SMS/MMS. |
sms_error_code | string | null | Vendor-side error code if SMS provisioning failed; null otherwise. |
sms_error_detail | string | null | Human-readable detail if SMS provisioning failed; null otherwise. |
sms_ready_at | string | null | ISO 8601 timestamp at which SMS provisioning reached "ready"; null until then. |
incoming_call_action | string | How incoming calls are handled: "auto_accept", "auto_reject", "webhook", or "hosted_agent" |
client_websocket_url | string | null | WebSocket URL used for auto-accepted calls |
incoming_call_webhook_url | string | null | HTTPS URL for incoming call webhook notifications |
filter_mode | string | Deprecated ("whitelist" or "blacklist"), mirroring the owning identity's phone_filter_mode. Still accepted on the phone-number PATCH as a compatibility bridge that forwards to the identity's mode; the canonical control is the identity's phone_filter_mode, set via PATCH /identities/{agent_handle} — see Manage identities. |
agent_identity_id | UUID | Agent identity that owns this number. Every active or paused phone number is bound to exactly one identity. |
created_at | string | Creation timestamp (ISO 8601) |
updated_at | string | Last updated timestamp (ISO 8601) |
The canonical filter-mode control is the agent identity's phone_filter_mode (see Manage identities). Sending filter_mode on the phone-number PATCH is deprecated but still accepted and forwards to the identity's phone_filter_mode; the number's filter_mode above mirrors that mode.
- Webhook Subscriptions — attach text-event delivery URLs to a phone number
- Phone contact rules — the allow/block list interpreted by the identity's
phone_filter_mode - Manage identities — set
phone_filter_mode - Phone guide — Filtering inbound calls and texts — whitelist/blacklist walkthrough
