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/phoneQuick start
Create an account and get your API key from the Inkbox console:
All API requests require authentication using a API key:
X-API-Key: YOUR_API_KEYPhone Numbers
Provision phone number
POSTProvision a new local phone number
/api/v1/phone/numbersRelease phone number
DELETERelease a phone number from your organization
/api/v1/phone/numbers/{phone_number_id}List phone numbers
GETList all phone numbers for your organization
/api/v1/phone/numbersGet phone number
GETGet a single phone number by ID
/api/v1/phone/numbers/{phone_number_id}Update phone number
PATCHUpdate incoming call action, WebSocket URL, or webhook URL
/api/v1/phone/numbers/{phone_number_id}Calls
Place call
POSTInitiate an outbound call with bidirectional audio streaming
/api/v1/phone/place-callList calls
GETList calls for an agent identity, newest first
/api/v1/phone/callsGet call
GETGet a single call by ID
/api/v1/phone/calls/{call_id}Hang up call
POSTEnd a live call by ID, from outside the call
/api/v1/phone/calls/{call_id}/hangupIncoming calls
Set incoming call action
PUTConfigure inbound call handling for an agent identity
/api/v1/phone/incoming-call-actionGet incoming call action
GETRead the inbound call configuration for an agent identity
/api/v1/phone/incoming-call-actionTexts
Send text
POSTSend an outbound SMS from one of your phone numbers
/api/v1/phone/numbers/{phone_number_id}/textsList texts
GETList SMS and MMS messages for a phone number
/api/v1/phone/numbers/{phone_number_id}/textsGet text
GETGet a single text message by ID
/api/v1/phone/numbers/{phone_number_id}/texts/{text_id}Update text
PATCHMark as read or delete a text message
/api/v1/phone/numbers/{phone_number_id}/texts/{text_id}Search texts
GETFull-text search across text messages
/api/v1/phone/numbers/{phone_number_id}/texts/searchList conversations
GETList conversation summaries with unread counts
/api/v1/phone/numbers/{phone_number_id}/texts/conversationsGet conversation
GETGet all messages with a specific remote number
/api/v1/phone/numbers/{phone_number_id}/texts/conversations/{remote_number}Update conversation
PATCHBulk-update read state for all messages in a conversation
/api/v1/phone/numbers/{phone_number_id}/texts/conversations/{remote_number}Transcripts
List transcripts
GETList transcript segments for a call, ordered by sequence
/api/v1/phone/calls/{call_id}/transcriptsSearch transcripts
GETFull-text search across transcripts for a phone number
/api/v1/phone/numbers/{phone_number_id}/searchContact 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
GETList allow/block rules for an agent identity
/api/v1/identities/{agent_handle}/phone-contact-rulesCreate contact rule
POSTAdd an allow or block rule (E.164 exact match)
/api/v1/identities/{agent_handle}/phone-contact-rulesGet contact rule
GETFetch a single rule by ID
/api/v1/identities/{agent_handle}/phone-contact-rules/{rule_id}Update contact rule
PATCHChange a rule's action (admin-only)
/api/v1/identities/{agent_handle}/phone-contact-rules/{rule_id}Delete contact rule
DELETEDelete a rule (admin-only)
/api/v1/identities/{agent_handle}/phone-contact-rules/{rule_id}List org phone contact rules
GETOrg-wide aggregate list across every identity (admin-only)
/api/v1/phone/contact-rulesSMS 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
GETList the consent rows for your organization
/api/v1/phone/sms-opt-insGet opt-in
GETLook up the consent state for one recipient
/api/v1/phone/sms-opt-ins/{receiver_number}Opt in recipient
POSTMark a recipient as opted in (requires active, customer-managed 10DLC campaign)
/api/v1/phone/sms-opt-ins/{receiver_number}/opt-inOpt out recipient
POSTMark a recipient as opted out (requires active, customer-managed 10DLC campaign)
/api/v1/phone/sms-opt-ins/{receiver_number}/opt-outWebhooks
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.
| Parameter | Type | Default | Description |
|---|---|---|---|
start_datetime | string | — | 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_datetime | string | — | 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 |
tz | string | UTC | IANA time zone (e.g. America/New_York) used to interpret zone-less values. Defaults to UTC |
- A bare date in
end_datetimeis inclusive of the entire day —end_datetime=2026-07-06returns records through the last moment of the 6th. - A datetime with an explicit
Zor offset (2026-07-06T15:30:00Z,2026-07-06T11:30:00-04:00) is an exact instant;tzis ignored for that value. - A naive datetime (
2026-07-01T12:00:00) is interpreted intz(UTC whentzis omitted). - Supply only one side for an open-ended range. Ordering, pagination, and all other filters are unchanged.
- Invalid input returns
422:start_datetimeafterend_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-06Interpret those bare dates in a specific zone:
?start_datetime=2026-07-01&end_datetime=2026-07-06&tz=America/New_YorkFilter from an exact instant (tz ignored):
?start_datetime=2026-07-06T15:30:00Z