Skip to content

Phone API

API-first telephony service for AI agents. Provision phone numbers, place and receive calls with bidirectional audio streaming, receive and manage SMS/MMS text messages, retrieve transcripts, and subscribe to events via webhooks.

API base URL:

https://inkbox.ai/api/v1/phone

Quick start

Create an account and get your API key from the Inkbox console:

Get API key

All API requests require authentication using a API key:

X-API-Key: YOUR_API_KEY

Phone Numbers

Provision phone number

POST

Provision a new local phone number

/api/v1/phone/numbers

Release phone number

DELETE

Release a phone number from your organization

/api/v1/phone/numbers/{phone_number_id}

List phone numbers

GET

List all phone numbers for your organization

/api/v1/phone/numbers

Get phone number

GET

Get a single phone number by ID

/api/v1/phone/numbers/{phone_number_id}

Update phone number

PATCH

Update incoming call action, WebSocket URL, or webhook URL

/api/v1/phone/numbers/{phone_number_id}

Calls

Place call

POST

Initiate an outbound call with bidirectional audio streaming

/api/v1/phone/place-call

List calls

GET

List calls for an agent identity, newest first

/api/v1/phone/calls

Get call

GET

Get a single call by ID

/api/v1/phone/calls/{call_id}

List Voice AI tool activity

GET

List safe, paginated tool activity for a call

/api/v1/phone/calls/{call_id}/tool-invocations

Hang up call

POST

End a live call by ID, from outside the call

/api/v1/phone/calls/{call_id}/hangup

Inkbox Voice AI configuration

Get Voice AI configuration

GET

Read an identity's Voice AI configuration

/api/v1/phone/hosted-agent-config

Update Voice AI configuration

PUT

Replace an identity's voice, model, and instructions

/api/v1/phone/hosted-agent-config

Set Voice AI authority mode

PUT

Set the default authority mode for future Voice AI calls

/api/v1/phone/hosted-agent-config/authority-mode

Incoming calls

Set incoming call action

PUT

Configure inbound call handling for an agent identity

/api/v1/phone/incoming-call-action

Get incoming call action

GET

Read the inbound call configuration for an agent identity

/api/v1/phone/incoming-call-action

Texts

Send text

POST

Send an outbound SMS from one of your phone numbers

/api/v1/phone/numbers/{phone_number_id}/texts

List texts

GET

List SMS and MMS messages for a phone number

/api/v1/phone/numbers/{phone_number_id}/texts

Get text

GET

Get a single text message by ID

/api/v1/phone/numbers/{phone_number_id}/texts/{text_id}

Update text

PATCH

Mark as read or delete a text message

/api/v1/phone/numbers/{phone_number_id}/texts/{text_id}

Search texts

GET

Full-text search across text messages

/api/v1/phone/numbers/{phone_number_id}/texts/search

List conversations

GET

List conversation summaries with unread counts

/api/v1/phone/numbers/{phone_number_id}/texts/conversations

Get conversation

GET

Get all messages with a specific remote number

/api/v1/phone/numbers/{phone_number_id}/texts/conversations/{remote_number}

Update conversation

PATCH

Bulk-update read state for all messages in a conversation

/api/v1/phone/numbers/{phone_number_id}/texts/conversations/{remote_number}

Transcripts

List transcripts

GET

List transcript segments for a call, ordered by sequence

/api/v1/phone/calls/{call_id}/transcripts

Search transcripts

GET

Full-text search across transcripts for a phone number

/api/v1/phone/numbers/{phone_number_id}/search

Contact rules

Per-identity allow and block rules interpreted against the identity's phone_filter_mode (blacklist by default, whitelist on demand), covering inbound calls and texts. See the Contact rules reference and the Phone guide for semantics. The legacy per-number routes under /numbers/{phone_number_id}/contact-rules are deprecated — migrate to the handle-keyed routes below.

List contact rules

GET

List allow/block rules for an agent identity

/api/v1/identities/{agent_handle}/phone-contact-rules

Create contact rule

POST

Add an allow or block rule (E.164 exact match)

/api/v1/identities/{agent_handle}/phone-contact-rules

Get contact rule

GET

Fetch a single rule by ID

/api/v1/identities/{agent_handle}/phone-contact-rules/{rule_id}

Update contact rule

PATCH

Change a rule's action (admin-only)

/api/v1/identities/{agent_handle}/phone-contact-rules/{rule_id}

Delete contact rule

DELETE

Delete a rule (admin-only)

/api/v1/identities/{agent_handle}/phone-contact-rules/{rule_id}

List org phone contact rules

GET

Org-wide aggregate list across every identity (admin-only)

/api/v1/phone/contact-rules

SMS opt-ins

Per-recipient SMS consent state for your organization. Reads are open to admin-scoped API key holders and callers from the Inkbox Console; writes require your org to be on its own active, customer-managed 10DLC campaign. See the SMS opt-ins reference for the full schema and the customer-campaign gate.

List opt-ins

GET

List the consent rows for your organization

/api/v1/phone/sms-opt-ins

Get opt-in

GET

Look up the consent state for one recipient

/api/v1/phone/sms-opt-ins/{receiver_number}

Opt in recipient

POST

Mark a recipient as opted in (requires active, customer-managed 10DLC campaign)

/api/v1/phone/sms-opt-ins/{receiver_number}/opt-in

Opt out recipient

POST

Mark a recipient as opted out (requires active, customer-managed 10DLC campaign)

/api/v1/phone/sms-opt-ins/{receiver_number}/opt-out

Webhooks

Text events (text.*) are delivered via the Webhook Subscriptions API — attach a subscription to the phone number with the subset you want. The call-lifecycle event (call.ended) is delivered the same way, via a subscription on the agent identity. The incoming-call event stays on the phone number resource: set incoming_call_webhook_url via PATCH /numbers/{phone_number_id} because the response body controls call routing. See the Webhooks guide for event types, payload format, and signature verification.

Filtering by date

Date filtering applies to the comms list endpoints — List calls (GET /calls, and the deprecated GET /numbers/{phone_number_id}/calls alias), List texts (GET /numbers/{phone_number_id}/texts), and List conversations (GET /numbers/{phone_number_id}/texts/conversations). These accept three optional query parameters that filter results by when each record was created (created_at, stored in UTC); other phone list endpoints (such as list phone numbers and list transcripts) do not support them. All three are optional and fully backwards-compatible — omit them and the endpoint behaves exactly as before, with no filtering applied.

ParameterTypeDefaultDescription
start_datetimestring—Inclusive lower bound. A bare date (2026-07-01) starts at 00:00 of that day; a datetime with a Z or offset is used as an exact instant
end_datetimestring—Upper bound, inclusive. A bare date (2026-07-06) covers the whole day; a datetime with a Z or offset is an exact instant, and records created at exactly that instant are included
tzstringUTCIANA time zone (e.g. America/New_York) used to interpret zone-less values. Defaults to UTC
  • A bare date in end_datetime is inclusive of the entire day — end_datetime=2026-07-06 returns records through the last moment of the 6th.
  • A datetime with an explicit Z or offset (2026-07-06T15:30:00Z, 2026-07-06T11:30:00-04:00) is an exact instant; tz is ignored for that value.
  • A naive datetime (2026-07-01T12:00:00) is interpreted in tz (UTC when tz is omitted).
  • Supply only one side for an open-ended range. Ordering, pagination, and all other filters are unchanged.
  • Invalid input returns 422: start_datetime after end_datetime, an unparseable date, or an unknown time zone.

A bare-date range (interpreted in UTC):

?start_datetime=2026-07-01&end_datetime=2026-07-06

Interpret those bare dates in a specific zone:

?start_datetime=2026-07-01&end_datetime=2026-07-06&tz=America/New_York

Filter from an exact instant (tz ignored):

?start_datetime=2026-07-06T15:30:00Z

Additional resources