Phone Numbers
Manage the phone numbers associated with your organization. Provision toll-free or 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 | "toll_free" (default) or "local" |
state | string | No | US state code (e.g. "NY"). Only applicable when type is "local" |
incoming_call_action | string | No | How to handle incoming calls: "auto_accept", "auto_reject" (default), 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 | string | No | "blacklist" (default) or "whitelist". Controls how contact rules are interpreted for this phone number. Requires an admin-scoped API key, or set it as a user in the Inkbox Console. |
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)
JSONNew numbers are provisioned with incoming_call_action set to auto_reject. Update the number to configure 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", 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 | null | No | HTTPS URL for incoming call webhooks. Required when incoming_call_action is "webhook". Set to null to unsubscribe. |
filter_mode | string | No | "blacklist" or "whitelist". Controls how contact rules are interpreted for this phone number. Requires an admin-scoped API key, or change it as a user in the Inkbox Console. |
Text webhook delivery has moved. Configure text events via the Webhook Subscriptions API.
Request example
JSONResponse (200)
Returns the updated phone number object. When this request changes filter_mode to a new value, the response also includes a filter_mode_change_notice object counting rules that are now redundant under the new mode (see the Phone number object below). The field is null on any other PATCH and on GET, list, and create responses.
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: "toll_free" or "local" |
state | string | null | 2-letter US state abbreviation (e.g. "CA") for local numbers; null for toll_free numbers |
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", or "webhook" |
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 | "blacklist" (default) or "whitelist". Decides how contact rules are interpreted for inbound calls and texts. |
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) |
filter_mode_change_notice | object | null | Populated only on PATCH responses where filter_mode was actually changed. null otherwise. See shape below. |
filter_mode_change_notice
| Field | Type | Description |
|---|---|---|
new_filter_mode | string | The mode the phone number was just flipped to ("whitelist" or "blacklist") |
redundant_rule_action | string | "block" when the new mode is whitelist; "allow" when the new mode is blacklist |
redundant_rule_count | integer | Number of active rules whose action equals redundant_rule_action. 0 is a clean flip; a value greater than 0 suggests the operator review or delete those rules. Paused rules are not counted. |
- Webhook Subscriptions — attach text-event delivery URLs to a phone number
- Phone contact rules — the allow/block list interpreted by
filter_mode - Phone guide — Filtering inbound calls and texts — whitelist/blacklist walkthrough
