Phone Numbers - Inkbox

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 /numbers

Provision 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), `"auto_accept"`, `"auto_reject"`, `"webhook"`, or `"forward"`
`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"`
`forwarding_target_type`	string	No	`"phone"` or `"sip"`. Required when `incoming_call_action` is `"forward"`
`forwarding_phone_number`	string	No	E.164 forwarding destination. Required for a `"phone"` target
`forwarding_sip_uri`	string	No	Complete `sip:user@public-dns-host[:port]` destination. Required for a `"sip"` target; private/single-label and IP hosts are not accepted

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

JSON

{
  "agent_handle": "sales-agent",
  "type": "local",
  "state": "CA"
}

Response (201)

JSON

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "number": "+14155550100",
  "type": "local",
  "country": "US",
  "state": "CA",
  "status": "active",
  "sms_status": "ready",
  "sms_error_code": null,
  "sms_error_detail": null,
  "sms_ready_at": "2026-03-10T12:00:05Z",
  "incoming_call_action": "hosted_agent",
  "client_websocket_url": null,
  "incoming_call_webhook_url": null,
  "forwarding_target_type": null,
  "forwarding_phone_number": null,
  "forwarding_sip_uri": null,
  "agent_identity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "created_at": "2026-03-10T12:00:00Z",
  "updated_at": "2026-03-10T12:00:00Z"
}

New numbers use incoming_call_action: "hosted_agent" by default, so Inkbox Voice AI answers incoming calls without additional setup. Set auto_reject explicitly if you do not want incoming calls answered. You can update the number to change this setting.

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

curl -X POST "https://inkbox.ai/api/v1/phone/numbers" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_handle": "sales-agent", "type": "local"}'

const response = await fetch(
  "https://inkbox.ai/api/v1/phone/numbers",
  {
      method: "POST",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({ agent_handle: "sales-agent", type: "local" }),
  }
);
const number = await response.json();

import requests

response = requests.post(
    "https://inkbox.ai/api/v1/phone/numbers",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"agent_handle": "sales-agent", "type": "local"},
)
number = response.json()

Release phone number

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

curl -X DELETE "https://inkbox.ai/api/v1/phone/numbers/PHONE_NUMBER_ID" \
  -H "X-API-Key: YOUR_API_KEY"

const phoneNumberId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
await fetch(
  `https://inkbox.ai/api/v1/phone/numbers/${phoneNumberId}`,
  {
      method: "DELETE",
      headers: { "X-API-Key": "YOUR_API_KEY" },
  }
);

import requests

phone_number_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
requests.delete(
    f"https://inkbox.ai/api/v1/phone/numbers/{phone_number_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)

List phone numbers

GET /numbers

List your organization’s current phone numbers, newest first.

Query parameters

Parameter	Type	Description
`limit`	integer	Maximum rows to return (1–200). Omit to return all visible phone numbers.
`offset`	integer	Rows to skip (0–10,000). Defaults to `0`.

Response (200)

JSON

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "number": "+14155550100",
    "type": "local",
    "country": "US",
    "state": "CA",
    "status": "active",
    "sms_status": "ready",
    "sms_error_code": null,
    "sms_error_detail": null,
    "sms_ready_at": "2026-03-10T12:00:05Z",
    "incoming_call_action": "auto_accept",
    "client_websocket_url": "wss://your-agent.example.com/stream",
    "incoming_call_webhook_url": null,
    "forwarding_target_type": null,
    "forwarding_phone_number": null,
    "forwarding_sip_uri": null,
    "agent_identity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "created_at": "2026-03-10T12:00:00Z",
    "updated_at": "2026-03-10T12:00:00Z"
  }
]

Code examples

curl -X GET "https://inkbox.ai/api/v1/phone/numbers" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  "https://inkbox.ai/api/v1/phone/numbers",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const numbers = await response.json();

import requests

response = requests.get(
    "https://inkbox.ai/api/v1/phone/numbers",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
numbers = response.json()

Get phone number

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

curl -X GET "https://inkbox.ai/api/v1/phone/numbers/PHONE_NUMBER_ID" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  `https://inkbox.ai/api/v1/phone/numbers/${phoneNumberId}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const number = await response.json();

import requests

response = requests.get(
    f"https://inkbox.ai/api/v1/phone/numbers/{phone_number_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
number = response.json()

Update phone number

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"`, `"hosted_agent"` (Inkbox Voice AI answers; requires neither URL), or `"forward"`
`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.
`forwarding_target_type`	string \| null	No	`"phone"`, `"sip"`, or `null`. Required when selecting `"forward"`; set to `null` to clear both forwarding destinations while switching `incoming_call_action` away from `"forward"`
`forwarding_phone_number`	string \| null	No	E.164 forwarding destination for a `"phone"` target
`forwarding_sip_uri`	string \| null	No	Valid complete SIP forwarding destination for a `"sip"` target

Incoming-call configuration belongs to the number’s agent identity. Updating it through this endpoint changes inbound handling for every phone or iMessage line routed to that identity.

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

JSON

{
  "incoming_call_action": "auto_accept",
  "client_websocket_url": "wss://your-agent.example.com/stream"
}

Response (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

curl -X PATCH "https://inkbox.ai/api/v1/phone/numbers/PHONE_NUMBER_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "incoming_call_action": "auto_accept"
  }'

const response = await fetch(
  `https://inkbox.ai/api/v1/phone/numbers/${phoneNumberId}`,
  {
      method: "PATCH",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({ incoming_call_action: "auto_accept" }),
  }
);
const number = await response.json();

import requests

response = requests.patch(
    f"https://inkbox.ai/api/v1/phone/numbers/{phone_number_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"incoming_call_action": "auto_accept"},
)
number = response.json()

Phone 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"`.
`country`	string	ISO 3166-1 alpha-2 country code (e.g. `"US"` or `"GB"`). Existing US numbers use `"US"`.
`state`	string \| null	2-letter US state abbreviation (e.g. `"CA"`); `null` when unavailable or not applicable, including UK 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"`, `"webhook"`, `"hosted_agent"`, or `"forward"`
`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
`forwarding_target_type`	string \| null	`"phone"` or `"sip"` when a forwarding destination is saved
`forwarding_phone_number`	string \| null	Saved E.164 forwarding destination
`forwarding_sip_uri`	string \| null	Saved complete SIP forwarding destination
`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 response also includes non-null inbound_filter_mode and outbound_filter_mode fields (whitelist or blacklist). Configure these effective modes on the identity. Object responses can include optional top-level response notices. The canonical filter-mode control is the agent identity (see Manage identities). Sending filter_mode on the phone-number PATCH is deprecated but still accepted and forwards to the identity’s shared phone_filter_mode; the number’s filter_mode above mirrors that shared value. This shared write sets both incoming and outgoing modes for SMS/MMS, calls, and iMessage, removing directional customization even when the shared value is unchanged. Reads return the common effective mode when both agree, otherwise the last shared baseline. Use the identity’s phone_inbound_filter_mode and phone_outbound_filter_mode for effective directional settings. See directional filter modes. country and state describe the phone number in responses. Provisioning still requests US local numbers with the existing optional US state filter; it does not accept a country parameter.

Webhook Subscriptions — configure identity-owned text-event delivery
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

​Provision phone number

​Request body

​Request example

​Response (201)

​Error responses

​Code examples

​Release phone number

​Path parameters

​Response (204)

​Error responses

​Code examples

​List phone numbers

​Query parameters

​Response (200)

​Code examples

​Get phone number

​Path parameters

​Response (200)

​Error responses

​Code examples

​Update phone number

​Path parameters

​Request body

​Request example

​Response (200)

​Error responses

​Code examples

​Phone number object

​Related

Provision phone number

Request body

Request example

Response (201)

Error responses

Code examples

Release phone number

Path parameters

Response (204)

Error responses

Code examples

List phone numbers

Query parameters

Response (200)

Code examples

Get phone number

Path parameters

Response (200)

Error responses

Code examples

Update phone number

Path parameters

Request body

Request example

Response (200)

Error responses

Code examples

Phone number object

Related