# How can we help? Set up your business phone, find answers to common questions, or build on our API. Already a customer? [Ask Ping](/help/ping), the assistant in your app. ## Browse by topic ## For developers ## Need a hand? --- # API Build on top of Phone.inc. The REST API gives you read access to the phone numbers, calls, and voicemails on your company account, plus customer context for inbound callers from your connected integrations. [Quickstart](/api/quickstart) [Authentication](/api/authentication) ## Getting started Generate an API key at [app.phone.inc/api_keys](https://app.phone.inc/api_keys), copy the token, and you're authenticated. Walk through the [Quickstart](/api/quickstart) to make your first request. Every endpoint lives under `https://app.phone.inc/api/v1`. [Get an API key](/api/authentication) Building a multi-tenant integration that acts on behalf of *other* Phone.inc customers? Skip API keys and use [OAuth 2.0 for applications](/api/oauth) instead. --- # Authentication The Phone.inc API uses **API keys** for authentication. Generate one in the dashboard, attach it to every request, and you're done. API keys are the right choice when **you** are the customer — your scripts, internal tools, and server-to-server integrations all act on behalf of your own company. If you're building a product that needs to act on behalf of *other* Phone.inc customers, you want OAuth 2.0 instead. See [OAuth 2.0 for applications](/api/oauth). The base URL for everything below is `https://app.phone.inc`. --- ## Create an API key 1. Sign in to your Phone.inc dashboard. 2. Open **Your account → API Keys** in the sidebar, or go directly to [https://app.phone.inc/api_keys](https://app.phone.inc/api_keys). 3. Click **Create API key**, give it a descriptive name (e.g. `Zapier integration`, `Reporting script`), and submit. 4. **Copy the token immediately.** It's shown to you exactly once. We store an HMAC-SHA256 digest, not the raw value, so we cannot show it to you again — losing it means creating a new one. Tokens have the form `phk_` followed by 28 base58 characters, e.g. `phk_a1B2c3D4e5F6g7H8j9K1m2N3p4Q5r6S7`. Treat API keys like passwords. Never commit them to version control, never paste them into a public chat, and never embed them in client-side code (mobile apps, browser bundles). If a key leaks, [revoke it](#revoke-a-key) and create a new one. --- ## Use an API key Send the token on every request to `/api/v1/*`. We accept three methods, in priority order: - **X-Api-Key header** (`recommended`): `X-Api-Key: phk_...` — explicit and unambiguous. Use this for new integrations. - **Authorization: Bearer header** (`supported`): `Authorization: Bearer phk_...` — works if your HTTP client has built-in Bearer support. Phone.inc auto-detects API keys vs OAuth tokens by the `phk_` prefix. - **api_key query parameter** (`discouraged`): `?api_key=phk_...` — supported for compatibility with tools that can't set headers. Avoid when possible: query strings end up in server logs and browser history. ```bash curl https://app.phone.inc/api/v1/business_numbers \ -H "X-Api-Key: phk_a1B2c3D4e5F6g7H8j9K1m2N3p4Q5r6S7" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/business_numbers', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }) ``` ```python import os, requests response = requests.get( "https://app.phone.inc/api/v1/business_numbers", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) ``` ```ruby require 'net/http' uri = URI('https://app.phone.inc/api/v1/business_numbers') response = Net::HTTP.get_response( uri, { 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY') }, ) ``` Every key is scoped to the company that created it. Calls, voicemails, business numbers — everything you fetch comes from that company. --- ## Rotate a key We don't expire keys automatically. Rotate them whenever you change who has access (e.g. when an employee leaves) or after a suspected leak: 1. Create a new key with the same name plus a date suffix. 2. Deploy the new key to your integration. 3. Confirm traffic is flowing under the new key (check **Last used** in the dashboard). 4. [Revoke](#revoke-a-key) the old one. This rotate-then-revoke pattern keeps your integration online during the swap. Phone.inc can also rotate its server-side API-key hashing secret without changing your token. During a configured transition, authenticating a valid existing key upgrades its stored digest automatically, even if the requested action later fails. If the upgrade cannot be written, the key can still authenticate while its stored digest matches the current secret or any configured previous secret. This does not restore revoked keys or change their company access. Keys that have not been used before the transition ends may need replacing. --- ## Revoke a key Revoke a key any time from the dashboard: 1. Open [https://app.phone.inc/api_keys](https://app.phone.inc/api_keys). 2. Find the key in the list — you'll see its name, masked prefix (e.g. `phk_a1B2c3D4…`), creator, and when it was last used. 3. Click **Revoke** and confirm. Revocation takes effect immediately. The next request using that token returns `401 Invalid API key`. --- ## Errors - **401 Unauthorized**: The token is missing, malformed, doesn't exist, or has been revoked. The body is `{"error": "Invalid API key"}`. Don't retry — fix the token. - **429 Too Many Requests**: More than 10 invalid-key attempts from the same IP in 60 seconds. Subsequent requests are blocked for 60 seconds with `{"error": "Too many failed API key attempts. Wait a moment and try again."}` and a `Retry-After: 60` header. This applies only to *failed* lookups — valid keys are never throttled here. See [Errors](/api/errors) for the full status-code reference. --- ## Security checklist - Store keys in environment variables or a secret manager — never in source control. - Use a **separate key per integration**, named after the integration. When something goes wrong, you can revoke just the affected one. - Review the **Last used at** and **Last used IP** columns in the dashboard periodically. If a key shows traffic from somewhere unexpected, rotate it. - Don't ship API keys in mobile apps or single-page apps. Anyone who can read your binary or browser bundle can read the key. Company-owned SaaS OAuth apps also require a server-side client secret; never move that secret into a public client. --- ## Building a multi-tenant integration? If you're building a product that *other* Phone.inc customers will install (a Slack bot, a CRM connector, an analytics service), API keys won't work — every customer would have to paste a key into your UI, and you'd be holding hundreds of credentials. That's what OAuth 2.0 is for. Read the [applications guide](/applications) first. Then create a company-owned app in the [Phone.inc dashboard](https://app.phone.inc/applications), next to your API keys. You do not need a separate partner account or approval. Enable the [25 resource-specific scopes](/api/oauth#scopes) your app needs. Then request a subset through OAuth. No scopes are preselected. Call and voicemail reads include recordings and transcripts. Call reads also include summaries and search. Note reads include text and collected details. Partner apps cannot request broad `api:read` or `api:write` access. Any authenticated employee in the customer company can grant access through OAuth consent. Each token stays bound to that installation and company. API keys and [legacy first-party and public MCP OAuth clients](/api/oauth-public) keep their existing permissions. The dashboard shows the client secret and context signing secret once, when you create or rotate them. Keep both on your server. You manage app credentials in the dashboard. The API and MCP cannot create them. Rotation replaces both secrets and disconnects every installation. Your customers must then reauthorize. API key rotation lets the old and new key overlap, but app rotation does not keep existing authorizations. See the [company-owned application guide](/api/oauth#company-owned-saas-applications) for PKCE, client authentication, and revocation. Enabling additional application scopes does not disconnect installations or revoke existing tokens. Existing tokens and refresh cannot gain scopes: the SaaS must start fresh S256 PKCE authorization for the full desired permission set. Reducing installation or application permissions revokes only credentials containing removed scopes; unaffected narrower tokens and installations continue. Removing every installed permission disconnects that installation. See the [incremental permission lifecycle](/api/oauth#disconnect-rotate-and-reauthorize) for consent, Connection URL links, and webhook restrictions. These dashboard flows add no public REST response fields, endpoints, or MCP tools. [Read the OAuth 2.0 guide](/api/oauth) --- # Business Numbers A business number is a customer-facing phone number on your Phone.inc account — the one you'd publish on a website or business card. Every call and voicemail belongs to exactly one business number. Beyond listing them, you can retrieve the full settings (routing, business hours) and update them through the API. ## The business number model Each business number has a stable public `id`, the human label your team uses to identify it (`name`), the underlying phone number, and its full routing configuration. Both list and detail responses include `porting_status` and `porting_number_human`, matching the business-number list in the dashboard. Both are `null` when no porting request exists. `porting_number_human` is the number being transferred, formatted for display (for example, `+45 33 12 34 56`). `porting_status` is one of: | Status | Meaning | |--------|---------| | `requested` | Your request has been recorded for our team. | | `waiting_for_customer` | Our team is waiting for something from you, such as a signed letter of authorisation, before sending the transfer to the carrier. | | `requested_from_did_worldwide` | The transfer has been requested from the carrier. | | `porting_date_confirmed` | The carrier has confirmed a transfer date. | | `completed` | The transfer is complete. | | `cancelled` | The request was cancelled. | Completed and cancelled requests retain their status; they do not become `null`. Porting status is separate from the business number's service `status`: a temporary number can remain active while its transfer is pending. These fields are read-only. List and detail responses also include read-only `confirmed_porting_date`: the carrier-confirmed transfer date as `YYYY-MM-DD`, for example `2026-11-19`, or `null` when no date is known or no request exists. This is a calendar date, not a timestamp or a promised time of day. A stored date remains available after completion; withdrawing the confirmation clears it. ### Properties - **id** (`string`): Unique identifier for the business number. - **name** (`string`): The label your team set for this number, like `Sales` or `Support`. ASCII letters, numbers, spaces, and `-_~!.+` only, up to 128 characters (no accented characters). - **number** (`string`): The phone number in E.164 format, e.g. `+14155551234`. - **number_formatted** (`string`): The same number formatted for display, e.g. `+1 415-555-1234`. - **status** (`string`): `provisioning`, `active`, `failed`, or `terminated`. Scheduled numbers remain active until `termination_at`. - **termination_at** (`string | null`): ISO 8601 date when service ends permanently. Null when no termination is scheduled. - **released_at** (`string | null`): ISO 8601 date when the provider release completed. Released numbers are omitted from the list but remain retrievable by ID with their history. - **messaging** (`object`): Provider capabilities: `sms` and `mms` each contain boolean `can_send` and `can_receive` flags. Clients can use these directly for messaging availability. `can_send` is also false while the company's plan does not include outbound messages (the same rule as the company's `outbound_calls` entitlement). Sending supports SMS-capable inMobile and DIDWW numbers. DIDWW SMS directions come from stored carrier features: `p2p` for sending and `sms_in` for receiving, with no separate per-number enablement flags. Company messaging, plan, active-number, and destination-country restrictions still apply to sending. Carrier support assumes correct trunk provisioning; operators must manually assign inbound SMS routing in the DIDWW portal. Features are recorded during purchase provisioning and refreshed when port completion or temporary-number restoration replaces the DID. A one-time migration fetches missing feature snapshots for existing active, unreleased DIDWW numbers with a carrier DID ID, without overwriting known snapshots. Missing feature data still means neither SMS direction is available. MMS capabilities are false. - **timezone** (`string`): IANA timezone for the business number, e.g. `Copenhagen` or `London`. - **treat_public_holidays_as_sundays** (`boolean`): Defaults to `false`. When enabled, national public holidays use Sunday's opening hours, including observed substitute days. Dates use the number's timezone and its assigned country, not the company's country or a shared dialling prefix. Regional holidays and bank-only closures are not included. Custom holidays are configured separately. - **custom_holidays** (`array`): Named date ranges that always use Sunday's opening hours, regardless of `treat_public_holidays_as_sundays` or national calendar support. Defaults to `[]`. Each object contains `name`, `start_date`, and `end_date`. Both dates are inclusive local dates in `YYYY-MM-DD` format; use equal endpoints for a single day. - **call_flow_revision_ids** (`object`): Opaque concurrency tokens keyed by `incoming_call_config`, `outside_business_hours_config`, and `no_answer_config`. Includes tokens for empty slots even when the corresponding config is `null`. Send the slot's token as `expected_revision_id` when selecting AI routing. - **language** (`string`): One of the 32 [supported language codes](/api/receptionists#supported-languages), used for number greetings and messages. Private employee introductions use the receptionist's language. Transcription detects the spoken language automatically. - **recording_enabled** (`boolean`): Legacy compatibility field. `true` when either transcription or recording retention is enabled. Setting this field updates both `transcribe_calls` and `keep_call_recording`. - **transcribe_calls** (`boolean`): Whether calls are recorded and transcribed. When `keep_call_recording` is false, the temporary recording is deleted after transcription completes. - **keep_call_recording** (`boolean`): Whether the call recording is stored, including when `transcribe_calls` is false. - **call_data_retention** (`string`): When transcriptions and call recordings are automatically deleted. One of `one_week`, `one_month`, `six_months`, `one_year`, or `never`. New business numbers default to `one_year`; numbers that existed when retention policies were introduced default to `never`. - **incoming_call_config** (`object`): The routing configuration for incoming calls. Contains a `type` field plus type-specific attributes. - **outside_business_hours_config** (`object | null`): The routing configuration used outside business hours, or `null` if not set (falls back to incoming call config). Newly created numbers start with a default `VoicemailConfig` here, greeting callers in the number's language; numbers created before this default may still be `null`. - **no_answer_config** (`object | null`): The routing configuration that runs when a call is transferred to employees but nobody answers within the ring timer, or `null` if no fallback is set. Same shape as the other two configs. - **no_answer_timeout_secs** (`integer | null`): How long a caller waits for an available employee before the `no_answer_config` takes over. `null` (or `0`) means Off: the caller waits until someone answers or they hang up. Allowed values: `15`, `30`, `60`, `300`, `600`, `1200`, `1800`, `2700`, `3600`. Every employee-transfer step queues the same way (in-hours, outside hours, menu branches, and no-answer fallbacks that transfer to employees). Only available employees are rung; callers wait in order. Voicemail and reject after hours never enqueue. - **wait_audio** (`string`): What the caller hears while waiting for an employee. `ringtone` (default, Nordic ringback) or `music`. Number-level, so a menu that transfers uses the same sound. - **registration_status** (`string`): Registration status of the business identity behind the number. One of `not_required`, `pending`, `submitted`, `approved`, `rejected`, or `failed`. Where a country regulates the number, we register it to your company's business identity and address, and it moves from `pending` to `submitted` to `approved`. `not_required` means no registration applies — usually because the number's country does not ask for one, in which case our carrier will not accept a registration even if we offer it. Numbers that did not come from us also report `not_required`. `rejected` means the carrier reviewed the registration and turned it down. `failed` means we could not submit it at all, usually because the company details we hold are incomplete. Both leave the number reachable but unregistered, and both need someone to act — get in touch if a number stays in either state. - **registration_due_at** (`string | null`): ISO 8601 timestamp indicating when the end-user registration must be completed for this number, or `null` if no registration is required. The number remains active during this window. - **business_hours** (`array`): Array of 7 objects (one per weekday) defining the opening schedule. ### Call flow config types All three routing slots — `incoming_call_config`, `outside_business_hours_config`, and `no_answer_config` — share the same set of config types: | Type | Fields | |------|--------| | `WelcomeTransferConfig` | `welcome` (string), `employee_ids` (non-empty array of strings) | | `TransferConfig` | `employee_ids` (non-empty array of strings) | | `RejectConfig` | `message` (string) | | `VoicemailConfig` | `greeting` (string) | | `PhoneMenuConfig` | `welcome` (string), `menu_options` (non-empty array) | | `AiAgentConfig` | `ai_receptionist_id` (string), `expected_revision_id` (string) | `TransferConfig` transfers the call to the chosen employees without playing a welcome message — it's `WelcomeTransferConfig` minus the greeting. Every generated message (`welcome`, `greeting`, `message`, and each menu option's `prompt`) is limited to **150 whitespace-separated words and 1,500 characters**, excluding leading and trailing whitespace. This is roughly one minute of speech, not an exact audio-duration limit: voice and speaking pace vary. Both limits apply to all three routing configurations and voice previews. Overlong text is rejected with `422` before audio generation; it is never silently truncated. Transfer configs must select either non-empty `employee_ids` or a `department_id`, never both. `department_id` is a public UUID from the [Departments API](/api/departments) and works in incoming, outside-hours and no-answer slots. Send `employee_ids: []` when replacing employees with a department; send `department_id: null` when switching back. Without a department, empty employee selection returns `422` and preserves the saved flow. Transfer responses include nullable `department_id` alongside `employee_ids`. Each department has one FIFO queue shared across business numbers, flows and receptionists. Callers inherit waiting and no-answer rules from the number called, and repeated entry into the same department does not reset their queue timestamp or deadline. Receptionist configuration accepts optional `department_ids` (up to 10 unique account department UUIDs). These grant queue transfers, not employee warm transfers. Existing configurations without `department_ids` keep their behavior. #### Phone menu options `PhoneMenuConfig` plays its `welcome` greeting, then waits for the caller to press a single digit. Each entry in `menu_options` maps one digit to an action: | Field | Type | Description | |-------|------|-------------| | `digit` | string | A single key, `"1"` through `"9"` only (`"0"` is rejected). Must be unique within the menu. | | `action_type` | string | What pressing the digit does (see below). | | `prompt` | string | Message played before the action runs. Required when `action_type` is `WelcomeTransferConfig`, `VoicemailConfig`, or `PlayMessageConfig`. | | `prompt_recorded` | boolean | Read only. `true` when the prompt is a recording made in the dashboard, in which case `prompt` is an empty string. | | `employee_ids` | array of strings | Employee transfer targets. For either transfer action, select non-empty `employee_ids` or `department_id`, never both. | | `department_id` | string or null | Department public UUID for `TransferConfig` or `WelcomeTransferConfig`. Callers join its shared queue. Send `employee_ids: []` when selecting a department, or `department_id: null` when switching back to employees. | `action_type` is one of: | `action_type` | What happens when the caller presses the digit | |---------------|------------------------------------------------| | `TransferConfig` | Transfer straight to `employee_ids`. | | `WelcomeTransferConfig` | Play `prompt`, then transfer to `employee_ids`. | | `VoicemailConfig` | Play `prompt`, then record a voicemail. | | `PlayMessageConfig` | Play `prompt`, then hang up. | A menu needs at least one option, and every option's `digit` must be unique — duplicates or an empty `menu_options` array are rejected with a `422`. On read, the response echoes each option's `digit`, `action_type`, `prompt` (when set), `prompt_audio_url` (generated audio), `employee_ids` (resolved to public ids), and nullable `department_id`. Department menu targets work in incoming, outside-hours, and no-answer menus, using the number's waiting and no-answer settings. On read, every config that plays spoken text also returns the URL of its generated audio (or `null` while generation is pending): `welcome_audio_url` on `WelcomeTransferConfig` and `PhoneMenuConfig`, `message_audio_url` on `RejectConfig`, and `greeting_audio_url` on `VoicemailConfig`. Audio regenerates automatically whenever the text changes. A greeting can also be a recording made in the dashboard: the matching `welcome_recorded`, `message_recorded`, `greeting_recorded`, or `prompt_recorded` flag is `true`, the text is an empty string, and the audio URL points at the recording. Recordings are not regenerated when the number's voice changes. Sending new text for that field replaces the recording with generated audio, and the flag turns `false`. Recordings cannot be created through the API. To hear a text before saving it, use [voice previews](#generate-a-voice-preview). Send `{ "type": null }` to clear the `outside_business_hours_config` or `no_answer_config` slot entirely. The `incoming_call_config` slot can't be cleared. ## Route calls to a receptionist The AI receptionist is in beta. Receptionists are standalone, company-owned resources that can serve several numbers. Create and configure one through the [Receptionists API](/api/receptionists), then select its ID using `AiAgentConfig` in any of the three routing slots. Selecting it reuses its published agent version; it does not provision another agent. Pro is required, except for internally marked test companies; see [access and pricing](/api/receptionists#access-and-pricing). ```json { "type": "AiAgentConfig", "ai_receptionist_id": "01a00000-0000-7000-8000-000000000003", "expected_revision_id": "flow:none" } ``` Retrieve the current number first and send the slot's token from `call_flow_revision_ids` as `expected_revision_id` whenever selecting an AI destination, including when replacing a non-AI destination. Config objects also return this token as `expected_revision_id`; empty slots have `flow:none` in `call_flow_revision_ids` while the config remains `null`. Do not construct the token or send `null`. A missing or stale token returns `422`, including if the flow changes while the agent is being prepared. The returned AI slot also includes `ai_receptionist_id` and its immutable `ai_configuration` snapshot. The MCP catalog exposes receptionist CRUD and the same routing selection fields. For compatibility, routing endpoints still accept inline `ai_configuration` instead of `ai_receptionist_id`. This creates a separate named receptionist for that flow rather than modifying a shared receptionist. Do not send both fields. Existing AI flows are migrated to named receptionists without changing their active revision. Knowledge imports, message taking, transfers, opening-hours lookup, call-history lookup and recording behavior are documented on the [Receptionists resource](/api/receptionists). ### Receptionist integration access Receptionist integrations and remote MCP tools are unavailable. See [integration access](/api/receptionists#integration-access) for the current limitations and compatibility behavior. --- ## List all business numbers Returns every business number on the authenticated employee's company. There's no pagination — companies have a small, finite set of business numbers, so the response is a single array. The list endpoint returns a lean response (id, name, number, number_formatted) plus each number's `messaging` capabilities, so a client can tell which numbers can send a text without retrieving each one. Use the retrieve endpoint for full settings including routing config and business hours. ```bash curl https://app.phone.inc/api/v1/business_numbers \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch( 'https://app.phone.inc/api/v1/business_numbers', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }, ) const { business_numbers: businessNumbers } = await response.json() ``` ```python import os, requests response = requests.get( "https://app.phone.inc/api/v1/business_numbers", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) business_numbers = response.json()["business_numbers"] ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/business_numbers') response = Net::HTTP.get_response( uri, { 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY') }, ) business_numbers = JSON.parse(response.body)['business_numbers'] ``` ```json { "business_numbers": [ { "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "name": "Sales", "number": "+14155551234", "number_formatted": "+1 415-555-1234", "messaging": { "sms": { "can_send": true, "can_receive": true }, "mms": { "can_send": false, "can_receive": false } } }, { "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c02", "name": "Support", "number": "+14155555678", "number_formatted": "+1 415-555-5678", "messaging": { "sms": { "can_send": false, "can_receive": false }, "mms": { "can_send": false, "can_receive": false } } } ] } ``` --- ## Retrieve a business number Returns the full settings for a single business number, including its incoming call config, outside-hours config, and weekly business hours schedule. ```bash curl https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01 \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch( 'https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }, ) const businessNumber = await response.json() ``` ```python import os, requests response = requests.get( "https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) business_number = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01') response = Net::HTTP.get_response( uri, { 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY') }, ) business_number = JSON.parse(response.body) ``` ```json { "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "name": "Sales", "number": "+14155551234", "number_formatted": "+1 415-555-1234", "timezone": "Copenhagen", "language": "da", "recording_enabled": false, "transcribe_calls": false, "keep_call_recording": false, "call_data_retention": "never", "incoming_call_config": { "type": "PhoneMenuConfig", "welcome": "Press 1 for sales, 2 to leave a message", "welcome_recorded": false, "welcome_audio_url": "https://app.phone.inc/rails/active_storage/blobs/redirect/...", "menu_options": [ { "id": 42, "digit": "1", "action_type": "TransferConfig", "prompt": null, "prompt_recorded": false, "prompt_audio_url": null, "employee_ids": ["019daef1-085e-7000-aaaa-000000000001"] }, { "id": 43, "digit": "2", "action_type": "VoicemailConfig", "prompt": "Leave a message after the tone", "prompt_recorded": false, "prompt_audio_url": "https://app.phone.inc/rails/active_storage/blobs/redirect/...", "employee_ids": [] } ] }, "outside_business_hours_config": { "type": "RejectConfig", "message": "We are closed, please call back tomorrow." }, "no_answer_config": { "type": "VoicemailConfig", "greeting": "Sorry we missed you — leave a message after the tone." }, "no_answer_timeout_secs": 30, "wait_audio": "ringtone", "registration_status": "approved", "registration_due_at": null, "business_hours": [ { "day_of_week": 0, "day_name": "Monday", "open": true, "opening_at": "09:00", "closing_at": "17:00" }, { "day_of_week": 1, "day_name": "Tuesday", "open": true, "opening_at": "09:00", "closing_at": "17:00" }, { "day_of_week": 2, "day_name": "Wednesday", "open": true, "opening_at": "09:00", "closing_at": "17:00" }, { "day_of_week": 3, "day_name": "Thursday", "open": true, "opening_at": "09:00", "closing_at": "17:00" }, { "day_of_week": 4, "day_name": "Friday", "open": true, "opening_at": "09:00", "closing_at": "17:00" }, { "day_of_week": 5, "day_name": "Saturday", "open": false, "opening_at": "09:00", "closing_at": "17:00" }, { "day_of_week": 6, "day_name": "Sunday", "open": false, "opening_at": "09:00", "closing_at": "17:00" } ] } ``` --- ## Update a business number Updates the scalar fields on a business number. Use the dedicated config endpoints below to change call routing or business hours. ### Accepted fields - **name** (`string`): The display label for this number. ASCII letters, numbers, spaces, and `-_~!.+` only, up to 128 characters. - **timezone** (`string`): IANA timezone identifier, e.g. `Copenhagen`, `London`, `New_York`. - **language** (`string`): One of the 32 [supported language codes](/api/receptionists#supported-languages) for number greetings and messages. Private employee introductions use the receptionist's language. Existing greeting text is not translated when this changes. - **recording_enabled** (`boolean`): Legacy alias that sets both `transcribe_calls` and `keep_call_recording` to the supplied value. - **transcribe_calls** (`boolean`): Whether to create call transcriptions. - **keep_call_recording** (`boolean`): Whether to retain the audio after transcription completes. - **call_data_retention** (`string`): Automatic deletion policy for transcriptions and recordings: `one_week`, `one_month`, `six_months`, `one_year`, or `never`. New business numbers default to `one_year`. ```bash curl -X PATCH https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01 \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Sales Hotline", "timezone": "London"}' ``` ```js const response = await fetch( 'https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01', { method: 'PATCH', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Sales Hotline', timezone: 'London' }), }, ) const businessNumber = await response.json() ``` ```python import os, requests response = requests.patch( "https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, json={"name": "Sales Hotline", "timezone": "London"}, ) business_number = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01') http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true request = Net::HTTP::Patch.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = { name: 'Sales Hotline', timezone: 'London' }.to_json response = http.request(request) business_number = JSON.parse(response.body) ``` ```json { "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "name": "Sales Hotline", "number": "+14155551234", "number_formatted": "+1 415-555-1234", "timezone": "London", "language": "da", "recording_enabled": false, "transcribe_calls": false, "keep_call_recording": false, "call_data_retention": "never", "incoming_call_config": { "..." }, "outside_business_hours_config": null, "no_answer_config": null, "no_answer_timeout_secs": null, "business_hours": [ "..." ] } ``` --- ## Replace incoming call config Replaces the routing configuration used when a call comes in during business hours. Send the desired `type` and its required fields. The full business number (with updated config) is returned. ### Required fields by type | Type | Fields | |------|--------| | `WelcomeTransferConfig` | `welcome`, `employee_ids` (at least one id); optional `welcome_audio_preview_id` | | `TransferConfig` | `employee_ids` (at least one id) | | `RejectConfig` | `message`; optional `message_audio_preview_id` | | `VoicemailConfig` | `greeting`; optional `greeting_audio_preview_id` | | `PhoneMenuConfig` | `welcome`, `menu_options` (at least one option); optional `welcome_audio_preview_id` | ```bash curl -X PUT https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/incoming_call_config \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "WelcomeTransferConfig", "welcome": "Thanks for calling", "employee_ids": ["019daef1-085e-7000-aaaa-000000000001", "019daef1-085e-7000-aaaa-000000000002"] }' ``` ```js const response = await fetch( 'https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/incoming_call_config', { method: 'PUT', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'WelcomeTransferConfig', welcome: 'Thanks for calling', employee_ids: ['019daef1-085e-7000-aaaa-000000000001', '019daef1-085e-7000-aaaa-000000000002'], }), }, ) const businessNumber = await response.json() ``` ```python import os, requests response = requests.put( "https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/incoming_call_config", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, json={ "type": "WelcomeTransferConfig", "welcome": "Thanks for calling", "employee_ids": ["019daef1-085e-7000-aaaa-000000000001", "019daef1-085e-7000-aaaa-000000000002"], }, ) business_number = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/incoming_call_config') http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true request = Net::HTTP::Put.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = { type: 'WelcomeTransferConfig', welcome: 'Thanks for calling', employee_ids: ['019daef1-085e-7000-aaaa-000000000001', '019daef1-085e-7000-aaaa-000000000002'] }.to_json response = http.request(request) business_number = JSON.parse(response.body) ``` ```json { "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "name": "Sales", "number": "+14155551234", "number_formatted": "+1 415-555-1234", "timezone": "Copenhagen", "language": "da", "recording_enabled": false, "transcribe_calls": false, "keep_call_recording": false, "call_data_retention": "never", "incoming_call_config": { "type": "WelcomeTransferConfig", "welcome": "Thanks for calling", "employee_ids": ["019daef1-085e-7000-aaaa-000000000001", "019daef1-085e-7000-aaaa-000000000002"] }, "outside_business_hours_config": null, "no_answer_config": null, "no_answer_timeout_secs": null, "business_hours": [ "..." ] } ``` To set a phone menu instead, send `type: "PhoneMenuConfig"` with a `menu_options` array: ```bash curl -X PUT https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/incoming_call_config \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "PhoneMenuConfig", "welcome": "Press 1 for sales, 2 to leave a message", "menu_options": [ { "digit": "1", "action_type": "TransferConfig", "employee_ids": ["019daef1-085e-7000-aaaa-000000000001"] }, { "digit": "2", "action_type": "VoicemailConfig", "prompt": "Leave a message after the tone" } ] }' ``` ```js const response = await fetch( 'https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/incoming_call_config', { method: 'PUT', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'PhoneMenuConfig', welcome: 'Press 1 for sales, 2 to leave a message', menu_options: [ { digit: '1', action_type: 'TransferConfig', employee_ids: ['019daef1-085e-7000-aaaa-000000000001'] }, { digit: '2', action_type: 'VoicemailConfig', prompt: 'Leave a message after the tone' }, ], }), }, ) const businessNumber = await response.json() ``` ```python import os, requests response = requests.put( "https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/incoming_call_config", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, json={ "type": "PhoneMenuConfig", "welcome": "Press 1 for sales, 2 to leave a message", "menu_options": [ {"digit": "1", "action_type": "TransferConfig", "employee_ids": ["019daef1-085e-7000-aaaa-000000000001"]}, {"digit": "2", "action_type": "VoicemailConfig", "prompt": "Leave a message after the tone"}, ], }, ) business_number = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/incoming_call_config') http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true request = Net::HTTP::Put.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = { type: 'PhoneMenuConfig', welcome: 'Press 1 for sales, 2 to leave a message', menu_options: [ { digit: '1', action_type: 'TransferConfig', employee_ids: ['019daef1-085e-7000-aaaa-000000000001'] }, { digit: '2', action_type: 'VoicemailConfig', prompt: 'Leave a message after the tone' } ] }.to_json response = http.request(request) business_number = JSON.parse(response.body) ``` ```json { "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "name": "Sales", "number": "+14155551234", "number_formatted": "+1 415-555-1234", "timezone": "Copenhagen", "language": "da", "recording_enabled": false, "transcribe_calls": false, "keep_call_recording": false, "call_data_retention": "never", "incoming_call_config": { "type": "PhoneMenuConfig", "welcome": "Press 1 for sales, 2 to leave a message", "welcome_recorded": false, "welcome_audio_url": "https://app.phone.inc/rails/active_storage/blobs/redirect/...", "menu_options": [ { "id": 42, "digit": "1", "action_type": "TransferConfig", "prompt": null, "prompt_recorded": false, "prompt_audio_url": null, "employee_ids": ["019daef1-085e-7000-aaaa-000000000001"] }, { "id": 43, "digit": "2", "action_type": "VoicemailConfig", "prompt": "Leave a message after the tone", "prompt_recorded": false, "prompt_audio_url": "https://app.phone.inc/rails/active_storage/blobs/redirect/...", "employee_ids": [] } ] }, "outside_business_hours_config": null, "no_answer_config": null, "no_answer_timeout_secs": null, "business_hours": [ "..." ] } ``` --- ## Replace outside-hours config Replaces the routing configuration used when a call comes in outside business hours. You can also update the business hours schedule in the same request by including the `business_hours` array. Only `business_hours` is accepted for the schedule; the retired `opening_hours` request key and response aliases are no longer supported. Send `{ "treat_public_holidays_as_sundays": true }` to use Sunday's schedule on national public holidays, or `false` to return to the regular weekly schedule. Omission preserves the setting. Omit `type` when changing only hours or holiday handling to preserve the existing routing. Enabling holiday handling for a country without data returns `422`. Holiday rules come from the open-source [Ruby Holidays library](https://github.com/holidays/holidays); they are not a government-operated calendar and require dependency updates when rules change. Singapore is not supported because the library's calendar omits several national holidays. Enabling holiday handling for Singapore returns `422`. Send `custom_holidays` to replace all custom holidays, for example `{ "custom_holidays": [{ "name": "Winter break", "start_date": "2026-12-24", "end_date": "2027-01-04" }] }`. Omission preserves the list; `[]` clears it. Custom holidays always use Sunday's hours, even when national holiday handling is disabled or unsupported. They do not necessarily close the number: an open Sunday schedule remains open during these ranges. The list accepts at most 100 objects with exactly `name`, `start_date`, and `end_date`. Names must be nonblank strings of at most 100 characters. Dates must be valid `YYYY-MM-DD` dates with years from `0001` to `9999`, and `end_date` must be on or after `start_date`. Ranges may overlap or span years. Invalid input, including `null`, returns `422`. Custom holidays, national holiday handling, weekly hours, and routing changes in the same request are saved together or not at all. Send `{ "type": null }` to clear the outside-hours config entirely — calls will fall through to the regular incoming call config. ### Required fields by type | Type | Fields | |------|--------| | `RejectConfig` | `message`; optional `message_audio_preview_id` | | `WelcomeTransferConfig` | `welcome`, `employee_ids` (at least one id); optional `welcome_audio_preview_id` | | `TransferConfig` | `employee_ids` (at least one id) | | `VoicemailConfig` | `greeting`; optional `greeting_audio_preview_id` | | `PhoneMenuConfig` | `welcome`, `menu_options` (at least one option); optional `welcome_audio_preview_id` | ### Business hours object - **day_of_week** (`integer`): Day index: 0 = Monday, 6 = Sunday. - **open** (`boolean`): Whether the line is open on this day. - **opening_at** (`string`): Opening time in `HH:MM` format (24-hour). - **closing_at** (`string`): Closing time in `HH:MM` format. Use `24:00` for end of day. ```bash curl -X PUT https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/outside_business_hours_config \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "RejectConfig", "message": "We are closed, please call back tomorrow.", "business_hours": [ { "day_of_week": 0, "open": true, "opening_at": "09:00", "closing_at": "17:00" }, { "day_of_week": 1, "open": true, "opening_at": "09:00", "closing_at": "17:00" }, { "day_of_week": 2, "open": true, "opening_at": "09:00", "closing_at": "17:00" }, { "day_of_week": 3, "open": true, "opening_at": "09:00", "closing_at": "17:00" }, { "day_of_week": 4, "open": true, "opening_at": "09:00", "closing_at": "17:00" }, { "day_of_week": 5, "open": false, "opening_at": "09:00", "closing_at": "17:00" }, { "day_of_week": 6, "open": false, "opening_at": "09:00", "closing_at": "17:00" } ] }' ``` ```js const response = await fetch( 'https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/outside_business_hours_config', { method: 'PUT', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'RejectConfig', message: 'We are closed, please call back tomorrow.', business_hours: [ { day_of_week: 0, open: true, opening_at: '09:00', closing_at: '17:00' }, { day_of_week: 1, open: true, opening_at: '09:00', closing_at: '17:00' }, { day_of_week: 2, open: true, opening_at: '09:00', closing_at: '17:00' }, { day_of_week: 3, open: true, opening_at: '09:00', closing_at: '17:00' }, { day_of_week: 4, open: true, opening_at: '09:00', closing_at: '17:00' }, { day_of_week: 5, open: false, opening_at: '09:00', closing_at: '17:00' }, { day_of_week: 6, open: false, opening_at: '09:00', closing_at: '17:00' }, ], }), }, ) const businessNumber = await response.json() ``` ```python import os, requests response = requests.put( "https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/outside_business_hours_config", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, json={ "type": "RejectConfig", "message": "We are closed, please call back tomorrow.", "business_hours": [ {"day_of_week": 0, "open": True, "opening_at": "09:00", "closing_at": "17:00"}, {"day_of_week": 1, "open": True, "opening_at": "09:00", "closing_at": "17:00"}, {"day_of_week": 2, "open": True, "opening_at": "09:00", "closing_at": "17:00"}, {"day_of_week": 3, "open": True, "opening_at": "09:00", "closing_at": "17:00"}, {"day_of_week": 4, "open": True, "opening_at": "09:00", "closing_at": "17:00"}, {"day_of_week": 5, "open": False, "opening_at": "09:00", "closing_at": "17:00"}, {"day_of_week": 6, "open": False, "opening_at": "09:00", "closing_at": "17:00"}, ], }, ) business_number = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/outside_business_hours_config') http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true request = Net::HTTP::Put.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = { type: 'RejectConfig', message: 'We are closed, please call back tomorrow.', business_hours: [ { day_of_week: 0, open: true, opening_at: '09:00', closing_at: '17:00' }, { day_of_week: 1, open: true, opening_at: '09:00', closing_at: '17:00' }, { day_of_week: 2, open: true, opening_at: '09:00', closing_at: '17:00' }, { day_of_week: 3, open: true, opening_at: '09:00', closing_at: '17:00' }, { day_of_week: 4, open: true, opening_at: '09:00', closing_at: '17:00' }, { day_of_week: 5, open: false, opening_at: '09:00', closing_at: '17:00' }, { day_of_week: 6, open: false, opening_at: '09:00', closing_at: '17:00' } ] }.to_json response = http.request(request) business_number = JSON.parse(response.body) ``` ```json { "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "name": "Sales", "number": "+14155551234", "number_formatted": "+1 415-555-1234", "timezone": "Copenhagen", "language": "da", "recording_enabled": false, "transcribe_calls": false, "keep_call_recording": false, "call_data_retention": "never", "incoming_call_config": { "..." }, "outside_business_hours_config": { "type": "RejectConfig", "message": "We are closed, please call back tomorrow." }, "no_answer_config": null, "no_answer_timeout_secs": null, "business_hours": [ { "day_of_week": 0, "day_name": "Monday", "open": true, "opening_at": "09:00", "closing_at": "17:00" }, { "day_of_week": 1, "day_name": "Tuesday", "open": true, "opening_at": "09:00", "closing_at": "17:00" }, { "day_of_week": 2, "day_name": "Wednesday", "open": true, "opening_at": "09:00", "closing_at": "17:00" }, { "day_of_week": 3, "day_name": "Thursday", "open": true, "opening_at": "09:00", "closing_at": "17:00" }, { "day_of_week": 4, "day_name": "Friday", "open": true, "opening_at": "09:00", "closing_at": "17:00" }, { "day_of_week": 5, "day_name": "Saturday", "open": false, "opening_at": "09:00", "closing_at": "17:00" }, { "day_of_week": 6, "day_name": "Sunday", "open": false, "opening_at": "09:00", "closing_at": "17:00" } ] } ``` --- ## Replace no-answer config Sets the flow that runs when a call is transferred to employees but nobody answers within the ring timer. Send the desired `type`, its required fields, and `timeout_secs` to arm the timer. `timeout_secs` controls both the ring duration and whether the feature is on. Pass `15`, `30`, `60`, `300`, `600`, `1200`, `1800`, `2700`, or `3600`. Send `""`, `0`, or `null` to turn it off — calls then ring until they end naturally, exactly as before. Any other value is rejected with a `422`. Send `{ "type": null }` to clear the no-answer flow. Don't put employees in this flow's `WelcomeTransferConfig` or `TransferConfig` and expect another timeout — the no-answer transfer rings without a timer, so it never loops back into itself. ### Required fields by type | Type | Fields | |------|--------| | `WelcomeTransferConfig` | `welcome`, `employee_ids` (at least one id); optional `welcome_audio_preview_id` | | `TransferConfig` | `employee_ids` (at least one id) | | `RejectConfig` | `message`; optional `message_audio_preview_id` | | `VoicemailConfig` | `greeting`; optional `greeting_audio_preview_id` | | `PhoneMenuConfig` | `welcome`, `menu_options` (at least one option); optional `welcome_audio_preview_id` | ### Accepted fields - **type** (`string | null`): One of the call flow config types, or `null` to clear the slot. - **timeout_secs** (`integer | null`): Ring timer in seconds: `15`, `30`, `60`, `300`, `600`, `1200`, `1800`, `2700`, or `3600`. `0`, `null`, or a blank string (`""`, coerced to null server-side) turns the no-answer flow off. ```bash curl -X PUT https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/no_answer_config \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "VoicemailConfig", "greeting": "Sorry we missed you — leave a message after the tone.", "timeout_secs": 30 }' ``` ```js const response = await fetch( 'https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/no_answer_config', { method: 'PUT', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'VoicemailConfig', greeting: 'Sorry we missed you — leave a message after the tone.', timeout_secs: 30, }), }, ) const businessNumber = await response.json() ``` ```python import os, requests response = requests.put( "https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/no_answer_config", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, json={ "type": "VoicemailConfig", "greeting": "Sorry we missed you — leave a message after the tone.", "timeout_secs": 30, }, ) business_number = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/no_answer_config') http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true request = Net::HTTP::Put.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = { type: 'VoicemailConfig', greeting: 'Sorry we missed you — leave a message after the tone.', timeout_secs: 30 }.to_json response = http.request(request) business_number = JSON.parse(response.body) ``` ```json { "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "name": "Sales", "number": "+14155551234", "number_formatted": "+1 415-555-1234", "timezone": "Copenhagen", "language": "da", "recording_enabled": false, "transcribe_calls": false, "keep_call_recording": false, "call_data_retention": "never", "incoming_call_config": { "..." }, "outside_business_hours_config": null, "no_answer_config": { "type": "VoicemailConfig", "greeting": "Sorry we missed you — leave a message after the tone." }, "no_answer_timeout_secs": 30, "business_hours": [ "..." ] } ``` --- ## Generate a voice preview Generates a text-to-speech preview of `text` in the number's voice and language, so you can play a greeting before saving it. Returns a playable `audio_url` and the preview's signed `id`. To reuse the exact preview when saving incoming, outside-business-hours, or no-answer routing, send its signed `id` as `welcome_audio_preview_id` for a welcome/menu, `message_audio_preview_id` for a rejection, or `greeting_audio_preview_id` for voicemail. The preview must be unused and match the number, audio kind, and text. Generate a separate preview for each routing slot. An omitted or nonmatching preview uses normal speech generation. Unused previews are cleaned up automatically. Rate limited to 30 previews per minute per company. Exceeding it returns a `429`. ### Required fields - **kind** (`string`): Which field the text belongs to: `welcome`, `greeting`, `message`, or `prompt`. Anything else is rejected with a `422` and code `invalid_kind`. - **text** (`string`): The text to speak, up to 150 whitespace-separated words and 1,500 characters. Blank text is rejected with a `422` and code `blank_text`. Exceeding either limit returns `422` with code `text_too_long`, without calling the synthesis service. ### Errors Voice generation depends on an upstream synthesis service. Failures there (timeouts, rate limits, rejected text, missing configuration) raise and return `500`, which Sentry captures. Retrying after a moment is the right response. Validation errors stay `422` (`invalid_kind`, `blank_text`, `text_too_long`). Shorten overlong text before retrying. ```bash curl -X POST https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/voice_previews \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "kind": "welcome", "text": "Hi, you have reached Harbour & Co." }' ``` ```js const response = await fetch( 'https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/voice_previews', { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ kind: 'welcome', text: 'Hi, you have reached Harbour & Co.', }), }, ) const preview = await response.json() ``` ```python import os, requests response = requests.post( "https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/voice_previews", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, json={ "kind": "welcome", "text": "Hi, you have reached Harbour & Co.", }, ) preview = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/voice_previews') http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true request = Net::HTTP::Post.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = { kind: 'welcome', text: 'Hi, you have reached Harbour & Co.' }.to_json response = http.request(request) preview = JSON.parse(response.body) ``` ```json { "id": "eyJfcmFpbHMiOnsiZGF0YSI6...", "kind": "welcome", "text": "Hi, you have reached Harbour & Co.", "audio_url": "https://app.phone.inc/rails/active_storage/blobs/..." } ``` --- ## Request number porting Replace an existing business number with your old number. The existing number stays active as a temporary number while our team arranges the carrier transfer. When porting completes, your old number takes over the same business-number ID, routing, and settings. The temporary number is released. Keep your current provider subscription until the transfer completes. Available on Free without purchasing a second business number. The temporary number must be active, unreleased, and use DIDWW or InMobile, without scheduled termination, an open porting request, or a completed port. A number whose latest request was cancelled can start a new request; the cancelled request stays in its history, and the porting endpoints and fields return the newest request. DIDWW numbers must have a provisioned DID; any inventory assignment must be assigned to the number and match its provider. Our team selects DIDWW or InMobile as the destination independently of the temporary-number provider. The business number keeps its current provider until cutover, then switches to the selected destination. A released InMobile temporary number enters inventory quarantine rather than being terminated through a carrier API. Provider selection and carrier submission are internal operations, not customer API parameters. Returns `201` with the [porting request](#retrieve-a-porting-request): its public `id`, `business_number_id`, normalized `number_to_port`, initial `status` of `requested`, `number_type`, and the `documents` still needed. This records a request for our team; it does not immediately submit a transfer to the carrier. Our team sends the port once every required document is in (`documents.complete`). Invalid or ineligible requests return `422` with an `errors` object. Numbers outside your company and released numbers return `404`. ### Attributes - **number_to_port** (`string`): Required. Your old phone number, including its country code. Must match the temporary number's country dial code, differ from the temporary number, and have no open porting request. - **tax_id** (`string`): Required for Danish numbers. A valid eight-digit CVR number, optionally prefixed with `DK`. ```bash curl -X POST https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/porting_request \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"number_to_port":"+4533123487","tax_id":"46213564"}' ``` ```js const response = await fetch('https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/porting_request', { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ number_to_port: '+4533123487', tax_id: '46213564' }), }) const request = await response.json() ``` ```python import os import requests response = requests.post( 'https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/porting_request', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, json={'number_to_port': '+4533123487', 'tax_id': '46213564'}, ) porting_request = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/porting_request') request = Net::HTTP::Post.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = { number_to_port: '+4533123487', tax_id: '46213564' }.to_json response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) } porting_request = JSON.parse(response.body) ``` ```json { "id": "019daef1-085f-7000-8000-a71e2d8dd2cc", "business_number_id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc", "number_to_port": "+4533123487", "status": "requested", "number_type": "National", "documents": { "complete": false, "authorization": { "required": true, "icc_allowed": false, "method": null, "loa_status": "not_sent", "loa_signer_email": null, "icc_provided": false, "current_carrier": null }, "invoice": { "required": true, "uploaded": false } } } ``` --- ## Retrieve a porting request Returns the business number's porting request and the documents still needed before our team can send the port to the carrier. Returns `404` when the number has no porting request. `number_type` is `Local`, `National`, or `Mobile`. Danish numbers are classified by the Danish numbering plan; other countries by their number prefix. The country and number type decide which documents are required. ### Documents - **documents.complete** (`boolean`): `true` when every required document is in, or when the number needs none. Our team starts the transfer only after this. - **documents.authorization.required** (`boolean`): Whether a signed letter of authorisation (LOA) is required. - **documents.authorization.icc_allowed** (`boolean`): `true` for Danish mobile numbers, where the SIM card number (ICC) can replace the LOA. - **documents.authorization.method** (`string | null`): `loa`, `icc`, or `null` when nothing is required. - **documents.authorization.loa_status** (`string | null`): `not_sent`, `sending`, `sent`, `signed`, or `declined`. `null` when no LOA is required. - **documents.authorization.loa_signer_email** (`string | null`): Where the LOA was emailed. - **documents.authorization.icc_provided** (`boolean`): Whether an ICC was given. The ICC itself is never returned. - **documents.authorization.current_carrier** (`string | null`): The provider the number is moving away from. - **documents.invoice.required** (`boolean`): Whether the latest invoice from the current provider is required. - **documents.invoice.uploaded** (`boolean`): Whether an invoice has been uploaded. ```bash curl https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/porting_request \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/porting_request', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }) const portingRequest = await response.json() ``` ```python import os import requests response = requests.get( 'https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/porting_request', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, ) porting_request = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/porting_request') request = Net::HTTP::Get.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) } porting_request = JSON.parse(response.body) ``` ```json { "id": "019daef1-085f-7000-8000-a71e2d8dd2cc", "business_number_id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc", "number_to_port": "+4533123487", "status": "requested", "number_type": "National", "documents": { "complete": false, "authorization": { "required": true, "icc_allowed": false, "method": "loa", "loa_status": "sent", "loa_signer_email": "mette@example.com", "icc_provided": false, "current_carrier": "TDC Erhverv" }, "invoice": { "required": true, "uploaded": false } } } ``` --- ## Cancel a porting request Cancel a port before our team sends it to the carrier. The request must have status `requested` or `waiting_for_customer` and still use its temporary number. The temporary number stays active with its routing and settings unchanged. This does not close the business number or delete the request history. Returns `200` with the updated porting request and status `cancelled`. Returns `422` if the request has already been sent to the carrier, completed, cancelled, or the number has already been replaced. Contact support to discuss cancellation after submission to the carrier. Returns `404` for missing requests, released numbers, and numbers outside your company. ```bash curl -X DELETE https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/porting_request \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/porting_request', { method: 'DELETE', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }) const portingRequest = await response.json() ``` ```python import os import requests response = requests.delete( 'https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/porting_request', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, ) porting_request = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/porting_request') request = Net::HTTP::Delete.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) } porting_request = JSON.parse(response.body) ``` ```json { "id": "019daef1-085e-73f0-85f6-a71e2d8dd2de", "business_number_id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc", "number_to_port": "+4520123456", "status": "cancelled", "number_type": "Mobile", "documents": { "complete": false, "authorization": { "required": true, "icc_allowed": true, "method": "loa", "loa_status": "not_sent", "loa_signer_email": null, "icc_provided": false, "current_carrier": null }, "invoice": { "required": false, "uploaded": false } } } ``` --- ## Authorise a porting request Authorise an open porting request. With `method` `loa`, Phone.inc emails a letter of authorisation, prefilled with your company details, the number, and the current provider, to the signer through DocuSeal. Sending again withdraws the earlier letter, so use it to change the signer. With `method` `icc`, available only when `documents.authorization.icc_allowed` is `true`, the SIM card number replaces the signature. Returns `200` with the updated porting request. Returns `422` when the port was already sent to the supplier, the LOA is already signed, a required field is missing, or the ICC is invalid. Returns `404` when the number has no porting request. ### Attributes - **method** (`string`): Required. `loa` or `icc`. - **current_carrier** (`string`): Required. The provider the number is moving away from. - **signer_name** (`string`): Required for `loa`. The person who signs for your company. - **signer_email** (`string`): Required for `loa`. Where the letter is emailed. - **signer_phone** (`string`): Optional. Printed as the contact number on letters that ask for one. - **icc** (`string`): Required for `icc`. The 18 to 22 digit number printed on the SIM card, starting with `89`. Spaces are ignored. ```bash curl -X POST https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/porting_request/authorization \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"loa","current_carrier":"TDC Erhverv","signer_name":"Mette Hansen","signer_email":"mette@example.com"}' ``` ```js const response = await fetch('https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/porting_request/authorization', { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ method: 'loa', current_carrier: 'TDC Erhverv', signer_name: 'Mette Hansen', signer_email: 'mette@example.com', }), }) const portingRequest = await response.json() ``` ```python import os import requests response = requests.post( 'https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/porting_request/authorization', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, json={ 'method': 'loa', 'current_carrier': 'TDC Erhverv', 'signer_name': 'Mette Hansen', 'signer_email': 'mette@example.com', }, ) porting_request = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/porting_request/authorization') request = Net::HTTP::Post.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = { method: 'loa', current_carrier: 'TDC Erhverv', signer_name: 'Mette Hansen', signer_email: 'mette@example.com' }.to_json response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) } porting_request = JSON.parse(response.body) ``` ```json { "id": "019daef1-085f-7000-8000-a71e2d8dd2cc", "business_number_id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc", "number_to_port": "+4533123487", "status": "requested", "number_type": "National", "documents": { "complete": false, "authorization": { "required": true, "icc_allowed": false, "method": "loa", "loa_status": "sending", "loa_signer_email": "mette@example.com", "icc_provided": false, "current_carrier": "TDC Erhverv" }, "invoice": { "required": true, "uploaded": false } } } ``` --- ## Upload a porting invoice Upload the latest invoice from your current provider as a PDF of at most 10 MB, sent as `multipart/form-data` in the `invoice` field. A new upload replaces the previous one. Only accepted when `documents.invoice.required` is `true` and the port has not been sent to the supplier yet. Returns `200` with the updated porting request, `422` for a missing or invalid file, and `404` when the number has no porting request. ```bash curl -X POST https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/porting_request/invoice \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -F "invoice=@invoice.pdf;type=application/pdf" ``` ```js import { readFile } from 'node:fs/promises' const form = new FormData() form.append('invoice', new Blob([await readFile('invoice.pdf')], { type: 'application/pdf' }), 'invoice.pdf') const response = await fetch('https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/porting_request/invoice', { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, body: form, }) const portingRequest = await response.json() ``` ```python import os import requests with open('invoice.pdf', 'rb') as invoice: response = requests.post( 'https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/porting_request/invoice', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, files={'invoice': ('invoice.pdf', invoice, 'application/pdf')}, ) porting_request = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/porting_request/invoice') request = Net::HTTP::Post.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request.set_form([['invoice', File.open('invoice.pdf'), { filename: 'invoice.pdf', content_type: 'application/pdf' }]], 'multipart/form-data') response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) } porting_request = JSON.parse(response.body) ``` ```json { "id": "019daef1-085f-7000-8000-a71e2d8dd2cc", "business_number_id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc", "number_to_port": "+4533123487", "status": "requested", "number_type": "National", "documents": { "complete": false, "authorization": { "required": true, "icc_allowed": false, "method": "loa", "loa_status": "sent", "loa_signer_email": "mette@example.com", "icc_provided": false, "current_carrier": "TDC Erhverv" }, "invoice": { "required": true, "uploaded": true } } } ``` --- ## Terminate a business number Permanently close a number. On Pro, it closes at the end of its current billing period and stays active until `termination_at`; you can cancel termination before that deadline. On Free, `termination_at` is the time of the request and the number is released in the background. The response can still show `status: "active"` and `released_at: null`; `released_at` is set once the release completes. The number cannot be recovered after closure; call history is retained. Obtain explicit confirmation before sending this request. On Pro, the number charge is removed from future bills immediately, without prorating or refunding the current period. The free-number credit moves to the oldest remaining, non-terminating active number. Employee charges and the company subscription are unchanged. Requires an active number without an ongoing port, and at least one other active number that is not terminating. The company's last number cannot be terminated. Returns `422` if these conditions or, on Pro, a future billing period end are unavailable, and `503` if Stripe cannot be updated. Repeated requests return the same termination date until the number is released; after that, they return `404`. ### Required attributes - **confirm** (`boolean`): Must be `true` to acknowledge permanent termination. ```bash curl -X POST https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/termination \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"confirm":true}' ``` ```js const response = await fetch('https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/termination', { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ confirm: true }), }) const number = await response.json() ``` ```python import os import requests response = requests.post( 'https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/termination', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, json={'confirm': True}, ) number = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/termination') request = Net::HTTP::Post.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = { confirm: true }.to_json response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) } number = JSON.parse(response.body) ``` Returns the full business-number object, including: ```json { "id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc", "status": "active", "termination_at": "2026-11-01T00:00:00Z", "released_at": null } ``` --- ## Cancel a termination Cancel a scheduled termination before `termination_at`. The number stays active and resumes normal renewal. No extra charge is prorated for the current period, which was already paid. The free-number credit is recalculated across the remaining active numbers, so the oldest eligible number receives the discount. Returns the full business-number object with `termination_at: null`. Repeating the request on an active number with no scheduled termination succeeds without changing billing. Previously queued closure jobs will not release the number. Returns `422` at or after the closure deadline, or when billing cannot be restored automatically. Released numbers return `404`. Stripe failures return `503` and leave termination scheduled. Requires an active billing subscription. No request body is required. ```bash curl -X DELETE https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/termination \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/termination', { method: 'DELETE', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }) const number = await response.json() ``` ```python import os import requests response = requests.delete( 'https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/termination', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, ) number = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/business_numbers/019daef1-085e-73f0-85f6-a71e2d8dd2cc/termination') request = Net::HTTP::Delete.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) } number = JSON.parse(response.body) ``` Returns the full business-number object, including: ```json { "id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc", "status": "active", "termination_at": null, "released_at": null } ``` --- ## Send an SMS {{ tag: 'POST', label: '/v1/business_numbers/{business_number_id}/messages' }} Send a message from an active outbound-enabled inMobile or DIDWW business number. Recipients must be in the same country as the sender unless Phone.inc enables the company's **International messaging** feature flag (`international_messaging`, off by default). Cross-country sends otherwise return `422` with an error on `to`. The restriction also applies to retries and automatic replies. The optional JSON body field `format` defaults to `sms`; only `sms` is currently supported, and `mms` or unknown formats return `422` before persistence or provider dispatch. Use `/business_numbers/:id/messages`; the old `/business_numbers/:id/sms_messages` sending URL is not exposed. The server derives the sender from the selected number, so clients cannot override it. The authenticated employee must belong to the company that owns the number. Company API keys are supported only while their creator employee still belongs to that company. Keys without a creator employee cannot send SMS. Missing credentials return `401`; missing or mismatched employee membership returns `403`. Unknown numbers and numbers belonging to another company return `404`. ### Required attributes - **business_number_id** (`string`): Business number public ID in the URL. Only active outbound-enabled inMobile or DIDWW numbers with at most 14 digits can send. - **to** (`string`): Recipient in E.164 format, such as `+4523909778`. Include the country code. National-format numbers are not accepted. - **text** (`string`): SMS text, between 1 and 10,000 characters. Whitespace-only text is rejected. Encoding is automatic: GSM-7 when possible, UCS-2 for Unicode. Longer messages can require multiple chargeable SMS parts. ### Response The number's `messaging.sms.can_send` capability must be true. Its existing provider handles both voice and messaging. The company's `messaging` feature flag must be enabled by Phone.inc; it defaults to off. While disabled, message endpoints return `404` and `messaging.sms.can_send` is false. The message is stored before contacting the provider. `202 Accepted` does not mean the recipient received it. The body is a persisted [SMS activity item](/api/texting#the-activity-model), with a stable Phone.inc ID, employee author, timestamps, and delivery state. A replay returns the current state, which may already be `delivered`, `failed`, or `unknown`. - **id** (`string`):Stable Phone.inc message public ID, shared by history and retries. - **business_number_id** (`string`):Sender business number public ID. - **from** (`string`):Server-selected sender in E.164 format. - **to** (`string`):Recipient in E.164 format. - **status** (`string`):Current delivery state, usually `accepted` after a new send. - **sms_count** (`integer | null`):Number of SMS parts reported by the provider. Null for accepted DIDWW sends, whose submission response does not report a part count, or when the provider response was lost. - **encoding** (`string | null`):Provider-selected `gsm7` or `ucs2` encoding. Null for accepted DIDWW sends, whose submission response does not report encoding, or when the provider response was lost. ### Errors and retries Invalid input or an unsupported sender returns `422` with `{ "errors": { ... } }`. Provider validation rejection also returns `422`, under `errors.base`. Unconfigured SMS sending returns `503`. Provider HTTP, transport, or response errors return `502`; these use `{ "error": "...", "id": "..." }` and omit private provider details. Provider errors after persistence include the stable message ID. Changed input with a reused idempotency key returns `409`. New sends and explicit retries share a limit of 30 attempts per business number per rolling minute (`429`, `Retry-After: 60`); safe replays do not consume another attempt. Sending an SMS has a real, chargeable side effect. Supply `Idempotency-Key` or the JSON field `idempotency_key` (1–128 nonblank characters); the header wins when both are supplied. Reuse the same key only to replay identical recipient, text, and employee input on the same business number. Without a key, each call creates a new message. A timeout or `502` may mean acceptance is unknown: inspect the persisted record rather than sending again with another key. Only definitively failed messages support the explicit retry endpoint. Provider blacklist protection remains enabled. Scheduling, bulk recipients, custom sender IDs, and caller-supplied callback URLs are not exposed. ```bash curl -X POST https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/messages \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"to":"+4523909778","text":"Your appointment is confirmed.","idempotency_key":"appointment-1"}' ``` ```js const response = await fetch( 'https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/messages', { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ to: '+4523909778', text: 'Your appointment is confirmed.', idempotency_key: 'appointment-1', }), }, ) const message = await response.json() ``` ```python import os import requests response = requests.post( 'https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/messages', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, json={ 'to': '+4523909778', 'text': 'Your appointment is confirmed.', 'idempotency_key': 'appointment-1', }, ) message = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/messages') http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true http.max_retries = 0 request = Net::HTTP::Post.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = { to: '+4523909778', text: 'Your appointment is confirmed.', idempotency_key: 'appointment-1' }.to_json response = http.request(request) message = JSON.parse(response.body) ``` ```json { "id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc", "type": "message", "format": "sms", "created_at": "2026-10-06T10:41:00.000000Z", "business_number_name": "Sales", "seen_at": "2026-10-06T10:41:00.000000Z", "direction": "outbound", "text": "Your appointment is confirmed.", "author": { "type": "employee", "id": "019daef1-085e-73f0-85f6-a71e2d8dd2cd", "name": "Lea" }, "received_at": null, "delivered_at": null, "failure_code": null, "can_retry": false, "business_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "from": "+4592450113", "to": "+4523909778", "status": "accepted", "sms_count": 1, "encoding": "gsm7" } ``` --- # Caller context When the phone rings, knowing who's calling turns a cold call into a warm one. The Caller context endpoint takes a phone number, queries every integration you've connected to your Phone.inc account, and returns matching data in a generic, structured format. We support **Shopify**, **Dinero**, **Attio**, **Custom Endpoint**, and installed [company-owned SaaS applications](/api/oauth#company-owned-saas-applications) with a context endpoint. The response shape is the same across providers. ## The caller context model The endpoint returns an array of `contexts` — one per provider that found a match. Each context contains `sections` — either key-value fields or tables — with optional format hints so your UI can render money, dates, and badges appropriately. Partner OAuth tokens need `caller_context:read` to call this lookup API. This does not grant outbound delivery of caller numbers to the partner. Embedded `contact` fields require `contacts:read` and are omitted without it. API-key behavior is unchanged. Shopify returns up to three recent orders. The order table separates payment status (`status`) from fulfillment status (`fulfillment`). Shipment field sections include up to three fulfillments per order and two tracking entries per fulfillment, with carrier, tracking number, safe HTTPS links, and estimated delivery when available. Estimates are not guarantees. Cancelled or failed shipments have no actionable tracking links. Render tracking links using the existing field `url` property. The `get_caller_context` MCP tool returns the same sections. Each Shopify order row includes `details`: up to five ordered line items as plain-text quantity, product title, and variant. Quantities include refunded or removed units. A final `More items in Shopify` entry indicates that the list is incomplete; follow the order URL for the full order. Deleted products remain visible through Shopify's saved line-item titles. These are the matched customer's recent orders, not evidence that a particular call concerns one of them. The inbox queries Shopify when a thread is selected or the page is reloaded; it does not poll or subscribe to shipment updates while the thread stays open. Shopify's carrier data may lag. Historical call snapshots can be older than the live order data. ### Top-level properties - **contexts** (`array`): One entry per provider that matched the phone number. Empty if no integration recognized the caller. - **enriched_at** (`timestamp`): ISO 8601 timestamp of when the lookup was performed. `null` if no providers were queried. - **contact** (`object | null`): The matching Phone.inc contact, if one exists for this number. ### Context entry - **provider** (`string`): Machine-readable identifier for the source system, e.g. `shopify`, `custom_endpoint`. - **label** (`string`): Human-readable name shown in the UI, e.g. `Shopify`, `Internal CRM`. - **source** (`string`): The store, workspace, or account identifier, e.g. `acme.myshopify.com`. - **url** (`string | null`): Deep link to the matched record in the provider's admin UI. - **contact** (`object | null`): Identity returned by the provider. When it includes a `name`, Phone.inc creates a contact for the lookup phone number or fills blank fields on the existing contact. If multiple providers match, identities are merged in priority order: custom endpoint, Shopify, then Dinero. - **sections** (`array`): Array of section objects. Each section is either a `fields` section or a `table` section. ### Provider contact - **name** (`string`): Contact name. Required for Phone.inc to cache the identity. Maximum 128 characters. - **email** (`string | null`): Valid email address, truncated to 320 characters before validation. Invalid values are ignored. - **company_name** (`string | null`): Business or employer name. Maximum 128 characters. - **note** (`string | null`): Optional note copied to the contact. Maximum 10,000 characters. ### Fields section - **type** (`string`): Always `"fields"`. - **label** (`string`): Optional heading above the field list. - **fields** (`array`): Array of field objects with `label`, `value`, optional `format`, `url`, and `bold`. ### Table section - **type** (`string`): Always `"table"`. - **label** (`string`): Required heading above the table. - **columns** (`array`): Column definitions with `key`, `label`, and optional `format`. - **rows** (`array`): Row objects with `url` (optional link for the row), `values` (a map of column key to value), and optional `details` (a plain-text sublist). Details contain at most six strings of 500 characters each. The web caller-context sidebar renders them beneath the row; clients that do not support sublists can ignore them. ### Format hints Values can include a `format` hint to control rendering: | Format | Value shape | Rendering | |--------|------------|-----------| | `text` | String (default) | Rendered as-is | | `money` | `{ "amount": "89", "currency": "DKK" }` | Locale-formatted with currency symbol | | `date` | ISO 8601 string | Relative or absolute date | | `email` | String | Clickable mailto link | | `phone` | String (E.164) | Tap-to-call on mobile | | `badge` | String | Colored status pill | To make any value clickable, use the field-level `url` property instead of a format hint. --- ## Look up a caller Query every connected integration for the given phone number and return the matched data. Designed to be called the moment an inbound call rings — the response is fast enough to surface customer context before the employee picks up. Pass the caller's phone number in E.164 format. Other formats are accepted on a best-effort basis, but E.164 produces the most reliable matches. If no integration is connected, or none recognizes the number, you'll get an empty `contexts` array — that's the success path, not an error. ### Required query parameters - **phone** (`string`): The caller's phone number, ideally in E.164 (e.g. `+14155551234`). Required — calling the endpoint without it returns `400`. ```bash curl -G https://app.phone.inc/api/v1/caller_context \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ --data-urlencode phone=+14085550199 ``` ```js const params = new URLSearchParams({ phone: '+14085550199' }) const response = await fetch( `https://app.phone.inc/api/v1/caller_context?${params}`, { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }, ) const { contexts, enriched_at } = await response.json() ``` ```python import os, requests response = requests.get( "https://app.phone.inc/api/v1/caller_context", params={"phone": "+14085550199"}, headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) data = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/caller_context') uri.query = URI.encode_www_form(phone: '+14085550199') response = Net::HTTP.get_response( uri, { 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY') }, ) data = JSON.parse(response.body) ``` ```json { "contexts": [ { "provider": "shopify", "label": "Shopify", "source": "acme-store.myshopify.com", "url": "https://acme-store.myshopify.com/admin/customers/8123456789", "contact": { "name": "Jamie Rivera", "email": "jamie@example.com" }, "sections": [ { "type": "fields", "fields": [ { "label": "Customer", "value": "Jamie Rivera", "url": "https://acme-store.myshopify.com/admin/customers/8123456789" }, { "label": "Email", "value": "jamie@example.com", "format": "email" }, { "label": "Phone", "value": "+14085550199", "format": "phone" } ] }, { "type": "table", "label": "Orders", "columns": [ { "key": "name", "label": "Order" }, { "key": "date", "label": "Date", "format": "date" }, { "key": "total", "label": "Total", "format": "money" }, { "key": "status", "label": "Status", "format": "badge" } ], "rows": [ { "url": "https://acme-store.myshopify.com/admin/orders/4112233445", "values": { "name": "#1042", "date": "2026-05-09T22:14:01Z", "total": { "amount": "129.95", "currency": "USD" }, "status": "Paid" } } ] } ] } ], "enriched_at": "2026-05-11T16:45:09Z", "contact": null } ``` ```json { "error": "phone parameter required" } ``` ## Signed partner lookups A company-owned SaaS app can register a `context_endpoint_url` and enable `caller_context:provide`. Phone.inc sends a signed POST to that endpoint only when the connected installation grants `caller_context:provide`. This scope requires an app context endpoint and can be granted alone for a context-only installation; it does not grant lookup API access. `caller_context:read` alone never enables outbound delivery. This is a synchronous lookup requiring an immediate JSON response, not an asynchronous webhook or a new Phone.inc API route. Apps without an endpoint remain valid API-only integrations. To verify an installed partner endpoint without creating or updating contacts, use the [partner caller-context test](/api/integrations#test-partner-caller-context). It sends the same signed request, strictly validates the response for preview, and keeps the same SSRF protections. The integration reference covers permissions, E.164 input, and diagnostic errors. The request has `Content-Type: application/json` and a JSON object containing exactly these three fields: ```json { "installation_id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc", "company_id": "019daef1-085e-73f0-85f6-a71e2d8dd2cd", "phone": "+4512345678" } ``` Use the `installation_id` mapping saved at [OAuth token exchange](/api/oauth#company-owned-saas-applications) to resolve your SaaS tenant, and check the associated `company_id`. Do not select a tenant from the phone number alone. ### Verify the signature | Header | Value | | --- | --- | | `X-Phone-Inc-Timestamp` | Unix timestamp in seconds | | `X-Phone-Inc-Signature` | `v1=` followed by a hex HMAC-SHA256 digest | The digest uses the separate **context signing secret**, not the OAuth client secret. Its message is the timestamp header, a literal `.`, and the exact raw request body bytes: ```text v1= ``` Capture the raw bytes before JSON parsing. Reject missing or malformed headers, reject stale timestamps (a five-minute tolerance is recommended), and compare the expected and received digests in constant time. Re-serializing parsed JSON changes the signed bytes and can invalidate the signature. Keep the signing secret server-side. Phone.inc does not send its OAuth bearer tokens to your endpoint; do not require or forward one for these lookups. ### Return caller context Return a JSON context object using the existing context-entry schema above: `provider`, `label`, `source`, `url`, `contact`, and `sections`. Do not wrap it in a new delivery envelope. Phone.inc sanitizes the response and overrides `provider` and `label` with the registered app identity. The integration provider slug is `partner`. Existing display limits apply: at most 5 sections, 15 fields per fields section, 8 columns and 10 rows per table, and 500-character display strings. The provider-contact limits above apply to contact identity. Contact enrichment fills blank fields only; it never overwrites populated customer contact fields. | Response | Lookup behavior | | --- | --- | | `200` with valid context JSON | Sanitize and display matching context | | `204` or `404` | No match | | `429` | Transient failure; contributes to endpoint backoff | | Other failures, timeouts, or invalid responses | Skip context without interrupting call routing; contributes to endpoint backoff | The endpoint must use HTTPS without credentials, query parameters, or a fragment. Phone.inc verifies TLS, checks DNS and destination IPs to prevent SSRF, and does not follow redirects. Requests have 3-second connect and read timeouts within an overall 5-second budget. Responses are bounded to 256 KiB. Keep responses small and fast; do not acknowledge the request and deliver results asynchronously. After three consecutive failures, Phone.inc pauses that application's caller-context endpoint across all installations for 60 seconds. Requests during the cooldown skip the endpoint; previews report the temporary pause. After the delay, one request probes recovery while other requests remain paused. A successful context response or healthy `204`/`404` clears the failures; a failed probe starts another cooldown. Previews use this same backoff and the separate [partner test budget](/api/errors#rate-limits). An application suspension stops lookups independently of this automatic backoff. Adding enabled application scopes does not stop existing caller lookups. Removing `caller_context:provide` from the installation or application stops lookups; removing unrelated permissions does not, while that permission remains granted. Removing every installed permission disconnects the installation. Disconnecting an installation, deleting the app, rotating its secrets, or changing redirects or the endpoint still stops lookups until fresh authorization. Previously stored call context is retained. See the [incremental permission lifecycle](/api/oauth#disconnect-rotate-and-reauthorize). --- # Calls Every voice interaction handled by Phone.inc — inbound or outbound, ringing or ended — shows up as a call. The Calls API lets you list recent activity, filter by phone number, direction, or state, pull a single call by its public ID, and run an attended (warm) transfer between employees. ## The call model A call links a business number, a remote party, and (when applicable) the employees who handled it. The full lifecycle is captured in the `state` field, with timestamps for when the call started and when it was answered. Partner OAuth requires `calls:read` to list or retrieve calls and active calls, including each call's recordings, transcriptions, summaries, and search. Updating or marking calls seen requires `calls:write` plus `calls:read`; transfer creation, cancellation, and completion require `calls:control` plus `calls:read`. Contact-name searches in the [inbox](/api/inbox) additionally require `contacts:read`; phone filters and phone-only queries do not. For partner tokens, reference IDs remain, but embedded employee, contact, department, and business-number details require their matching resource read scopes. Ungranted details are omitted, not returned as `null`. Business-number names and formatted numbers are also gated. The legacy `/api/v1/calls/seen` endpoint checks `calls:write` and `voicemails:write` individually, with their matching reads: call write permission cannot mark voicemails seen. API-key responses are unchanged. See [OAuth scopes](/api/oauth#scopes). ### Properties - **id** (`string`): Unique public identifier for the call. Use this when calling the [retrieve endpoint](#retrieve-a-call). - **from** (`string`): The originating phone number in E.164 format. For experimental internal calls, this is the initiating employee's public ID instead. - **to** (`string`): The destination phone number in E.164 format. For experimental internal calls, this is the recipient employee's public ID instead. - **direction** (`string`): Either `inbound` (someone called you) or `outbound` (an employee called out). Experimental employee-to-employee calls use `outbound` and are available only when your company's Internal calls feature flag is enabled. Start these calls from the web app's employee list or the employee dropdown in the dialer; there is no public API or MCP tool for starting them. These calls ring web browsers and registered iPhone and Android apps through the existing VoIP push and SIP flow. They do not fall back to mobile phone numbers and are not recorded. - **outside_business_hours** (`boolean | null`): Whether an inbound call arrived outside the business number's hours, recorded when routing began. `false` means it arrived during business hours. `null` means the decision is unknown, including older calls and outbound calls. Later schedule changes do not change this value. An after-hours call may still be answered or leave a voicemail. - **state** (`string`): The current lifecycle state. See the [state values](#call-states) section below for the full list. - **started_at** (`timestamp`): ISO 8601 timestamp of when the call was initiated. May be `null` for calls that haven't started yet. - **answered_at** (`timestamp`): ISO 8601 timestamp of when the call was answered. `null` for missed or rejected calls. - **duration** (`integer`): Total length of the call in seconds, measured from `answered_at`. `null` while the call is in progress. - **queue_position** (`integer`): While the caller waits for an employee (`state` is `queued`): their place in the business number's queue, where `1` is next. `null` otherwise. - **enqueued_at** (`timestamp`): While the caller waits for an employee: ISO 8601 timestamp of when they entered the queue, after any greeting or menu. `null` otherwise. - **summary** (`string`): Auto-generated summary of the call once it ends. `null` while the call is in progress or if a summary hasn't been produced. - **transcription** (`string`): Full text transcription of the call recording. `null` until the recording has been transcribed. - **transcription_segments** (`array`): Speaker-diarized transcription segments. Each entry has `speaker`, `text`, and an optional `employee_id` (the employee's public ID). `null` until transcribed. - **business_number_id** (`string`): The ID of the [business number](/api/business-numbers) the call was placed to or from. - **business_number_name** (`string`): The label of the business number (e.g. `Sales`). - **business_number** (`string`): The business number in E.164 format. - **business_number_formatted** (`string`): The business number formatted for display. - **recording_url** (`string`): URL where the call recording can be played or downloaded. New isolated stereo recordings switch to mono MP3s after playback processing; other recordings retain their original channel layout. `null` if recording is disabled or the call hasn't ended yet. The URL is generated per request — don't cache it long-term. - **employees** (`array`): Employees who participated in the call. Each entry has `id`, full `name`, `first_name`, and `last_name`. - **transfers** (`array`): Every warm transfer attempted on the call, oldest first, including finished ones. Each entry has `id`, `state` (see [the transfer model](#the-transfer-model)), `from_employee`, and `to_employee` (each with `id`, full `name`, `first_name`, and `last_name`). Read this after a call ends to see how a transfer actually resolved — `completed` means the target took over, `cancelled` means the caller went back to the controller, `failed` means the caller hung up mid-transfer. `from_employee` is `null` for transfers initiated by an AI agent. - **ai_tools** (`array`): AI tool audit entries, including denied and failed operations. Returned independently of transcription settings, but cleared when transcription/call content is deleted or expires under retention. Empty for calls without tool operations. Each entry includes `id`, `tool_key`, `state`, `created_at`, `duration_ms`, `request`, and `result`. Custom endpoint results contain only catalog-mapped fields, never the raw response. Private introduction text is not retained in these audits. All authenticated employees in the company may read them. The dashboard renders these entries as friendly action cards in the transcript, with expandable technical details. Placement uses the audit time relative to the call's answer time and is approximate, not an exact speech alignment. Entries without usable timing appear separately. A transfer attempt or department queue entry is not evidence that a caller spoke to someone; check the recorded outcome. - **receptionist** (`object`): The AI [receptionist](/api/receptionists) that answered the call, with `id` and `name`. `null` when no receptionist handled the call. Both fields are `null` when the receptionist has since been deleted or the call was answered by an AI agent without a named receptionist. In `transcription_segments`, the receptionist's turns have the speaker `Employee` and no `employee_id`. - **initiated_by** (`object`): For outbound calls only — the employee who placed the call. Has `id`, full `name`, `first_name`, and `last_name`. When recorded at call creation, this remains the original initiator after transfers. If no initiator was recorded, this falls back to a participant; the selection order is not guaranteed. Omitted on inbound calls. ### Call states The `state` field walks through the call's lifecycle. The values are: - **initiated**: The call has been created but not yet answered. Welcome and menu prompts run in this state. - **queued**: The caller is waiting for an available employee. The inbound carrier leg may already be answered so wait audio can play, but `answered_at` stays null until an employee picks up. Callers wait in order on that business number; only available employees are rung. - **answered**: The call was answered. `answered_at` is now set. - **playing_audio**: A pre-recorded greeting or message is being played to the caller. - **transferring**: The call is being transferred to an employee or another destination. - **recording**: The call is being recorded (e.g. taking a voicemail). - **bridged**: Two parties are connected and talking. This is the typical state for an active conversation. - **ended**: The call has hung up. `duration` is now set, and a `summary` may follow shortly. --- ## List recent calls Returns calls for the authenticated employee's company. Without a `query`, calls are ordered newest first. With a `query`, calls are ordered using hybrid keyword and semantic search across their transcription, summary, and saved caller context, so results can match exact words, customer details, or related topics. By default you get 10 calls; raise that with `limit` (capped at 50). All filters can be combined. Without `query`, follow `next_cursor` using the `cursor` parameter and the same filters until it is `null` to retrieve all matching calls. Ordering uses creation time, then an internal ID to break ties. Newer calls added after the first page do not move existing pages. A deleted or foreign-company cursor returns `404`; a non-string cursor returns `422`. Search results remain capped at 50, return `next_cursor: null`, and do not support cursor pagination; combining `query` with `cursor` returns `422`. For reports, filter the call-start period with `start_at` and `end_at`. These use `started_at`, falling back to creation time if absent. When combined with `query`, the date range is applied before search ranking and the result limit, so out-of-range calls do not consume the available results. Boundaries must be ISO 8601 timestamps with a time zone; invalid timestamps or an end not after the start return `422`. Convert local calendar boundaries to UTC or send explicit offsets, including daylight-saving changes. Do not mistake a single page or capped search for complete statistics. ### Optional query parameters - **query** (`string`): Search transcribed calls by exact language and semantic similarity. Summaries and saved caller context are included when available. Calls without a transcription do not match. - **business_number_id** (`string`): Filter to one business number by its public `id`. - **phone_number** (`string`): Filter to calls involving this phone number on the remote side. Accepts E.164 and best-effort matches local formats too. Combine with `direction` to disambiguate inbound vs outbound. - **direction** (`string`): Limit results to `inbound` or `outbound`. Defaults to both. - **state** (`string`): Filter by [call state](#call-states), e.g. `ended` for completed calls only. Unknown values are silently ignored. - **start_at** (`timestamp`): Inclusive call-start boundary, such as `2026-03-29T00:00:00+01:00`. - **end_at** (`timestamp`): Exclusive call-start boundary. Use the next local midnight to include an entire day, such as `2026-03-30T00:00:00+02:00`. - **cursor** (`string`): The previous response's `next_cursor`. Keep all filters unchanged. Not available with `query`. - **limit** (`integer`): Maximum number of calls to return. Defaults to 10, capped at 50. ```bash curl -G https://app.phone.inc/api/v1/calls \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -d query="order status" \ -d business_number_id=0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01 \ -d direction=inbound \ -d state=ended \ -d limit=25 ``` ```js const params = new URLSearchParams({ query: 'order status', business_number_id: '0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01', direction: 'inbound', state: 'ended', limit: '25', }) const response = await fetch( `https://app.phone.inc/api/v1/calls?${params}`, { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }, ) const { calls } = await response.json() ``` ```python import os, requests response = requests.get( "https://app.phone.inc/api/v1/calls", params={ "query": "order status", "business_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "direction": "inbound", "state": "ended", "limit": 25, }, headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) calls = response.json()["calls"] ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/calls') uri.query = URI.encode_www_form( query: 'order status', business_number_id: '0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01', direction: 'inbound', state: 'ended', limit: 25, ) response = Net::HTTP.get_response( uri, { 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY') }, ) calls = JSON.parse(response.body)['calls'] ``` ```json { "calls": [ { "id": "0193f4ba-1234-7c00-9e3d-2b2b8a7f1c11", "from": "+14085550199", "to": "+14155551234", "direction": "inbound", "state": "ended", "started_at": "2026-05-11T14:02:11Z", "answered_at": "2026-05-11T14:02:14Z", "duration": 187, "summary": "Customer asked about the status of order #1042.", "transcription": "Hello, I'm calling about order 1042...", "transcription_segments": [ { "speaker": "Caller", "text": "Hello, I'm calling about order 1042.", "employee_id": null }, { "speaker": "Alex Wong", "text": "Sure, let me look that up for you.", "employee_id": "0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20" } ], "recording_url": "https://app.phone.inc/rails/active_storage/blobs/redirect/.../recording.mp3", "business_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "business_number_name": "Sales", "business_number": "+14155551234", "business_number_formatted": "+1 415-555-1234", "employees": [ { "id": "0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20", "name": "Alex Wong", "first_name": "Alex", "last_name": "Wong" } ] } ], "next_cursor": null } ``` --- ## Retrieve a call Returns a single call by its public `id`. Useful when you receive a webhook or push notification with a call ID and want the latest state. Returns a `404` if the call doesn't exist on this company's account. ```bash curl https://app.phone.inc/api/v1/calls/0193f4ba-1234-7c00-9e3d-2b2b8a7f1c11 \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch( `https://app.phone.inc/api/v1/calls/${callId}`, { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }, ) const call = await response.json() ``` ```python import os, requests response = requests.get( f"https://app.phone.inc/api/v1/calls/{call_id}", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) call = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI("https://app.phone.inc/api/v1/calls/#{call_id}") response = Net::HTTP.get_response( uri, { 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY') }, ) call = JSON.parse(response.body) ``` ```json { "id": "0193f4ba-1234-7c00-9e3d-2b2b8a7f1c11", "from": "+14085550199", "to": "+14155551234", "direction": "inbound", "state": "bridged", "started_at": "2026-05-11T14:02:11Z", "answered_at": "2026-05-11T14:02:14Z", "duration": null, "summary": null, "transcription": null, "transcription_segments": null, "recording_url": null, "business_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "business_number_name": "Sales", "business_number": "+14155551234", "business_number_formatted": "+1 415-555-1234", "transfers": [ { "id": "0193f4c2-bbbb-7c00-9e3d-2b2b8a7f1c33", "state": "completed", "from_employee": { "id": "0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20", "name": "Alex Wong", "first_name": "Alex", "last_name": "Wong" }, "to_employee": { "id": "0193f4b0-cccc-7c00-9e3d-2b2b8a7f1c21", "name": "Bella Núñez", "first_name": "Bella", "last_name": "Núñez" } } ], "employees": [ { "id": "0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20", "name": "Alex Wong", "first_name": "Alex", "last_name": "Wong" } ] } ``` --- ## Delete a call transcription Permanently deletes a call's `transcription`, `transcription_segments` and `summary`. The call itself and its recording are kept. This cannot be undone. Subscribed webhooks receive [`call.data_deleted`](/api/webhooks) with `reason` set to `manual`. Deleting a transcription that is already gone succeeds without sending the event again. Returns an empty response with a `204 No Content` status. Not available to partner OAuth tokens, which receive `403 insufficient_scope`. ```bash curl -X DELETE https://app.phone.inc/api/v1/calls/$CALL_ID/transcription \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js await fetch( `https://app.phone.inc/api/v1/calls/${callId}/transcription`, { method: 'DELETE', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }, ) ``` ```python import os, requests requests.delete( f"https://app.phone.inc/api/v1/calls/{call_id}/transcription", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) ``` ```ruby require 'net/http' uri = URI("https://app.phone.inc/api/v1/calls/#{call_id}/transcription") request = Net::HTTP::Delete.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http| http.request(request) end ``` --- ## The transfer model An attended (warm) transfer moves a live call from one employee (the controller) to another without hanging up the customer. The customer is held in the same conference with music while the target rings; after they answer, the controller can complete the handoff or pull the call back, and the target can accept the call to finish the handoff. Call `state` stays `answered` — transfer lifecycle lives on the transfer object. ### Transfer properties - **id** (`string`): Unique public identifier for the transfer. - **state** (`string`): One of `ringing`, `consulting`, `completed`, `cancelled`, or `failed`. - **from_employee** (`object`): The controller who started the transfer. Has `id`, full `name`, `first_name`, and `last_name`. - **to_employee** (`object`): The employee being transferred to. Has `id`, full `name`, `first_name`, and `last_name`. ### Transfer states - **ringing**: The customer is on hold and the target employee is being rung (up to 30 seconds). - **consulting**: The target answered. Controller and target can talk while the customer stays on hold. - **completed**: The handoff finished. The original controller left; customer and target stay connected. - **cancelled**: The transfer was pulled back or the target never answered. The controller and customer resume. - **failed**: The transfer ended because the customer hung up (or the call otherwise failed). Starting or pulling back a transfer requires an authenticated employee who is the current controller on the call — either via OAuth (mobile/web) or an API key whose creator is that employee. Completing a transfer can be done by that controller or by the employee being transferred to. Only `available` coworkers can be targeted. --- ## Get the active call Returns the authenticated employee's currently active call (if any), any open transfer on that call, and coworkers you can transfer to. Also returns a call when the employee is the target of an open transfer (ringing or consulting), even before they have joined. Returns `204 No Content` when the employee is idle. ### Response fields - **call** (`object`): Short call summary: `id`, `state`, `direction`, `from`, `to`. - **transfer** (`object`): Open transfer, or `null`. Same shape as the [transfer model](#the-transfer-model). - **employees** (`array`): Coworkers at the company, excluding the authenticated employee. Each entry has `id`, full `name`, `first_name`, `last_name`, `status` (`available`, `on_call`, `do_not_disturb`, `ringing`, `logged_out`, or `unknown`), and `do_not_disturb_expires_at` — an ISO 8601 timestamp when a timed do-not-disturb ends, or `null`. Coworkers with status `available` or `do_not_disturb` can be transferred to; do-not-disturb silences queue calls, not a deliberate transfer. A `do_not_disturb` coworker must still have at least one ringable device (a live browser session or a registered mobile device) and must not already be ringing for another call — otherwise the transfer returns `409` with `error: "employee_unavailable"`. - **available_employees** (`array`): Coworkers with status `available`. Each entry has `id`, full `name`, `first_name`, and `last_name`. Same people as the `available` rows in `employees`. ```bash curl https://app.phone.inc/api/v1/calls/active \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/calls/active', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }) if (response.status === 204) { // idle } else { const { call, transfer, employees, available_employees } = await response.json() } ``` ```python import os, requests response = requests.get( "https://app.phone.inc/api/v1/calls/active", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) if response.status_code != 204: payload = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/calls/active') response = Net::HTTP.get_response( uri, { 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY') }, ) payload = JSON.parse(response.body) unless response.code == '204' ``` ```json { "call": { "id": "0193f4ba-1234-7c00-9e3d-2b2b8a7f1c11", "state": "answered", "direction": "inbound", "from": "+14085550199", "to": "+14155551234" }, "transfer": null, "employees": [ { "id": "0193f4b0-bbbb-7c00-9e3d-2b2b8a7f1c21", "name": "Jordan Lee", "first_name": "Jordan", "last_name": "Lee", "status": "available", "do_not_disturb_expires_at": null }, { "id": "0193f4b0-cccc-7c00-9e3d-2b2b8a7f1c22", "name": "Sam Ortiz", "first_name": "Sam", "last_name": "Ortiz", "status": "do_not_disturb", "do_not_disturb_expires_at": "2026-01-15T14:30:00Z" } ], "available_employees": [ { "id": "0193f4b0-bbbb-7c00-9e3d-2b2b8a7f1c21", "name": "Jordan Lee", "first_name": "Jordan", "last_name": "Lee" } ] } ``` --- ## Start a warm transfer Starts an attended transfer to another employee. The customer is held in-conference; the target rings for up to 30 seconds. Missing `employee_id` returns `400` with `error: "invalid_request"`. Concurrent starts return `409` with `error: "transfer_in_progress"`. An ESL communication failure returns `502` with `error: "esl_unreachable"`; if cleanup cannot be confirmed, the transfer remains open until its outcome is confirmed. Fetch the active call before retrying. ### Required attributes - **employee_id** (`string`): Public ID of the coworker to transfer to. Must have status `available`, or `do_not_disturb` with at least one ringable device and no ring in progress on another call, and not be the current controller. Anything else returns `409` with `error: "employee_unavailable"`. ```bash curl https://app.phone.inc/api/v1/calls/$CALL_ID/transfers \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"employee_id":"0193f4b0-bbbb-7c00-9e3d-2b2b8a7f1c21"}' ``` ```js const response = await fetch( `https://app.phone.inc/api/v1/calls/${callId}/transfers`, { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ employee_id: employeeId }), }, ) const { transfer } = await response.json() ``` ```python import os, requests response = requests.post( f"https://app.phone.inc/api/v1/calls/{call_id}/transfers", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, json={"employee_id": employee_id}, ) transfer = response.json()["transfer"] ``` ```ruby require 'net/http' require 'json' uri = URI("https://app.phone.inc/api/v1/calls/#{call_id}/transfers") request = Net::HTTP::Post.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = { employee_id: employee_id }.to_json response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end transfer = JSON.parse(response.body)['transfer'] ``` ```json { "transfer": { "id": "0193f4c0-dddd-7c00-9e3d-2b2b8a7f1c40", "state": "ringing", "from_employee": { "id": "0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20", "name": "Alex Wong", "first_name": "Alex", "last_name": "Wong" }, "to_employee": { "id": "0193f4b0-bbbb-7c00-9e3d-2b2b8a7f1c21", "name": "Jordan Lee", "first_name": "Jordan", "last_name": "Lee" } } } ``` --- ## Complete a warm transfer Finishes a transfer that is in `consulting` (or already `completed` — idempotent). The original controller leaves; the customer and target stay connected. The controller or the employee being transferred to can call this. Attempting to complete while the target is still ringing returns `409` with `error: "transfer_not_consulting"` and does not change the transfer. ```bash curl https://app.phone.inc/api/v1/calls/$CALL_ID/transfers/$TRANSFER_ID/completion \ -X POST \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch( `https://app.phone.inc/api/v1/calls/${callId}/transfers/${transferId}/completion`, { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }, ) const { transfer } = await response.json() ``` ```python import os, requests response = requests.post( f"https://app.phone.inc/api/v1/calls/{call_id}/transfers/{transfer_id}/completion", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) transfer = response.json()["transfer"] ``` ```ruby require 'net/http' require 'json' uri = URI("https://app.phone.inc/api/v1/calls/#{call_id}/transfers/#{transfer_id}/completion") request = Net::HTTP::Post.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end transfer = JSON.parse(response.body)['transfer'] ``` ```json { "transfer": { "id": "0193f4c0-dddd-7c00-9e3d-2b2b8a7f1c40", "state": "completed", "from_employee": { "id": "0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20", "name": "Alex Wong", "first_name": "Alex", "last_name": "Wong" }, "to_employee": { "id": "0193f4b0-bbbb-7c00-9e3d-2b2b8a7f1c21", "name": "Jordan Lee", "first_name": "Jordan", "last_name": "Lee" } } } ``` --- ## Cancel a warm transfer Pulls the transfer back while it is `ringing` or `consulting`. Target legs are dropped and the customer is released from hold to the original controller. ```bash curl https://app.phone.inc/api/v1/calls/$CALL_ID/transfers/$TRANSFER_ID \ -X DELETE \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch( `https://app.phone.inc/api/v1/calls/${callId}/transfers/${transferId}`, { method: 'DELETE', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }, ) const { transfer } = await response.json() ``` ```python import os, requests response = requests.delete( f"https://app.phone.inc/api/v1/calls/{call_id}/transfers/{transfer_id}", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) transfer = response.json()["transfer"] ``` ```ruby require 'net/http' require 'json' uri = URI("https://app.phone.inc/api/v1/calls/#{call_id}/transfers/#{transfer_id}") request = Net::HTTP::Delete.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end transfer = JSON.parse(response.body)['transfer'] ``` ```json { "transfer": { "id": "0193f4c0-dddd-7c00-9e3d-2b2b8a7f1c40", "state": "cancelled", "from_employee": { "id": "0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20", "name": "Alex Wong", "first_name": "Alex", "last_name": "Wong" }, "to_employee": { "id": "0193f4b0-bbbb-7c00-9e3d-2b2b8a7f1c21", "name": "Jordan Lee", "first_name": "Jordan", "last_name": "Lee" } } } ``` --- ## Unseen activity Get the number of distinct people with unseen incoming calls, voicemails, or Notes for each business number, including incoming SMS when the company's `messaging` feature flag is enabled. Notes are included independently of messaging. Partner tokens count only resource types they can read, including Notes with `notes:read`. Numbers with no unseen activity are omitted. A person with several unseen items counts once within that business number. The messaging flag defaults to off and is managed by Phone.inc. ```bash curl https://app.phone.inc/api/v1/activity/unseen \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/activity/unseen', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }) const { numbers } = await response.json() ``` ```python import os import requests response = requests.get( "https://app.phone.inc/api/v1/activity/unseen", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) print(response.json()["numbers"]) ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/activity/unseen') request = Net::HTTP::Get.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) } puts JSON.parse(response.body)['numbers'] ``` ```json { "numbers": [ { "business_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "people": 2 } ] } ``` --- ## Mark a conversation seen Set the seen state of calls and voicemails from one person on a business number. Send `business_number_id` (the number's public ID), `phone_number` (the remote person's E.164 number), and `seen` (a boolean). Returns `204 No Content`. Setting `seen` to `true` marks unseen calls and voicemails as seen without changing whether voicemails have been listened to. Setting it to `false` marks unanswered inbound calls and voicemails as unseen and clears voicemail listened state. Answered and outbound calls stay seen. A missing or invalid `seen` returns `422`; an unknown business number or missing phone number returns `404`. ```bash curl https://app.phone.inc/api/v1/calls/seen \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"business_number_id":"0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01","phone_number":"+14155551234","seen":true}' ``` ```js await fetch('https://app.phone.inc/api/v1/calls/seen', { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ business_number_id: '0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01', phone_number: '+14155551234', seen: true, }), }) ``` ```python import os import requests requests.post( "https://app.phone.inc/api/v1/calls/seen", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, json={ "business_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "phone_number": "+14155551234", "seen": True, }, ) ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/calls/seen') request = Net::HTTP::Post.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = { business_number_id: '0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01', phone_number: '+14155551234', seen: true, }.to_json Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) } ``` --- # Company The company is the top-level account object. Use the API to read and update your business address, country, VAT ID, and two-factor authentication policy. Company two-factor authentication updates are available through the API and apps, but deliberately excluded from MCP and assistant tools. The `update_company` tool only accepts profile fields and cannot change this security policy. ## The company model There is one company per account. The `id` is the stable public identifier you can use to reference the company in your own systems. GET and PATCH responses include read-only `plan` (`free` or `pro`) and `entitlements`, an object with boolean `add_employees`, `outbound_calls`, and `add_business_numbers` fields. Use entitlements rather than deriving access from the plan: grandfathered Free accounts retain access. New Free accounts can create their first kept employee and acquire their first business number, but need Pro for additional employees, additional business numbers, outbound calls, and outbound text messages. Active Pro trials have Pro access. Existing employees can still be edited and incoming calls are unaffected. First-party mobile clients receive the same company fields in the existing authenticated `GET /api/private/me` response, plus top-level `plan`, `entitlements`, and `feature_flags`. Refresh this payload after billing changes. The server enforces all four gates. An outbound call from a Free account without `outbound_calls` is refused before it is placed, from the web dashboard, iOS, and Android alike. Outbound text messages follow the per-number `messaging.sms.can_send` flag, which is false for the same accounts. ### Properties - **id** (`string`): Unique identifier for the company. - **name** (`string`): The registered company name. - **address** (`string`): Street address. May be `null`. - **city** (`string`): City. May be `null`. - **state** (`string`): State or region. May be `null`. - **zip** (`string`): Postal code. May be `null`. - **country** (`string`): ISO 3166-1 alpha-2 country code, e.g. `"DK"`. - **vat_id** (`string`): VAT registration number, e.g. `"DK12345678"`. May be `null`. - **requires_two_factor** (`boolean`): Whether employees must use two-factor authentication. - **plan** (`string`): Read-only subscription plan: `free` or `pro`. Active Pro trials return `pro`. - **entitlements** (`object`): Read-only access decisions. `add_employees` allows creating another employee; `outbound_calls` allows placing outbound calls from any client; `add_business_numbers` allows acquiring another business number in the dashboard. All are booleans and account for grandfathered access. The public API does not support purchasing numbers. --- ## Retrieve the company Returns the company associated with the authenticated API key or OAuth token. ```bash curl https://app.phone.inc/api/v1/company \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch( 'https://app.phone.inc/api/v1/company', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }, ) const company = await response.json() ``` ```python import os, requests response = requests.get( "https://app.phone.inc/api/v1/company", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) company = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/company') response = Net::HTTP.get_response( uri, { 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY') }, ) company = JSON.parse(response.body) ``` ```json { "id": "019daef1-085e-79ca-bb4d-7f6bf51992d2", "name": "Acme ApS", "address": "Vesterbrogade 1", "city": "Copenhagen", "state": null, "zip": "1620", "country": "DK", "vat_id": "DK12345678", "requires_two_factor": false, "plan": "free", "entitlements": { "add_employees": false, "outbound_calls": false, "add_business_numbers": false } } ``` --- ## Update the company Updates one or more fields on the company. Pass only the fields you want to change — omitted fields are left unchanged. ### Optional attributes - **address** (`string`): Street address. - **city** (`string`): City. - **state** (`string`): State or region. - **zip** (`string`): Postal code. - **country** (`string`): ISO 3166-1 alpha-2 country code, e.g. `"DK"`. Must match a country Phone.inc supports. - **vat_id** (`string`): VAT registration number. - **requires_two_factor** (`boolean`): Enable or disable the company two-factor authentication requirement. Omit to leave the policy unchanged. Not accepted by MCP or assistant tools. ```bash curl -X PATCH https://app.phone.inc/api/v1/company \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"city":"Aarhus","vat_id":"DK98765432"}' ``` ```js const response = await fetch('https://app.phone.inc/api/v1/company', { method: 'PATCH', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ city: 'Aarhus', vat_id: 'DK98765432', }), }) const company = await response.json() ``` ```python import os, requests response = requests.patch( "https://app.phone.inc/api/v1/company", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, json={ "city": "Aarhus", "vat_id": "DK98765432", }, ) company = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/company') request = Net::HTTP::Patch.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = JSON.generate( city: 'Aarhus', vat_id: 'DK98765432', ) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end company = JSON.parse(response.body) ``` ```json { "id": "019daef1-085e-79ca-bb4d-7f6bf51992d2", "name": "Acme ApS", "address": "Vesterbrogade 1", "city": "Aarhus", "state": null, "zip": "1620", "country": "DK", "vat_id": "DK98765432", "requires_two_factor": false, "plan": "free", "entitlements": { "add_employees": false, "outbound_calls": false, "add_business_numbers": false } } ``` --- # Contacts Contacts are your address book. Save a phone number once and Phone.inc will label every matching call with the contact's name, the company they work for, and any note you wrote down. The first time a new number calls in (or you call it), Phone.inc also creates a contact automatically — with no name until you fill one in. --- Contacts can represent your own company's business numbers as well as external numbers. Activity appears in the other party's thread: inbound calls, voicemails, and SMS appear under the caller or sender; outbound calls and SMS appear under the recipient. Your own business number has a contact thread when it is that other party, not simply because it received an external call or message. ## The contact model A contact represents a person (or business) you talk to. Phone numbers are unique per company and stored in E.164 format. ### Properties - **id** (`string`): Unique public identifier for the contact. - **name** (`string`): Display name for the contact. Optional — useful when you have a phone number but don't yet know who it belongs to. - **email** (`string`): Email address. Optional. Format-validated when present. - **phone** (`string`): Phone number in E.164 format (e.g. `+14155552671`). Required and unique per company. Inputs with spaces or formatting characters are normalized before being saved. - **phone_formatted** (`string`): The phone number rendered in international format with spaces (e.g. `+1 415-555-2671`). Read-only. - **company_name** (`string`): The contact's employer or business. Optional. - **note** (`string`): Free-form note. Up to 10,000 characters. - **last_contact_at** (`timestamp`): ISO 8601 timestamp of the most recent call, voicemail, or message involving this contact. `null` until the company has recorded activity with them. Used to order the dashboard Inbox. - **created_at** (`timestamp`): ISO 8601 timestamp of when the contact was created. - **updated_at** (`timestamp`): ISO 8601 timestamp of the last update. Want notifications when contacts change? Subscribe to `contact.created`, `contact.updated`, and `contact.deleted` on the [Webhooks](/api/webhooks#events) endpoint. --- ## List contacts Returns every contact in your company, newest first. Add `query` to search the full company address book, including saved contacts with no calls or messages. Searching does not create contacts or mark conversations read. ### Optional attributes - **phone** (`string`): Filter to the single contact whose phone number matches the given input. The value is normalized to E.164 before lookup, so `+45 20 12 34 56` and `+4520123456` both work. Returns an empty list if the input can't be normalized to a phone number. - **query** (`string`): Search up to 128 characters. Numbers match digits anywhere in a contact's phone, ignoring spaces, parentheses, dots and hyphens. Numeric matches are ordered by latest contact activity, falling back to creation time for contacts without activity, with newest contact breaking ties. Text uses the same company-wide hybrid search as the dashboard Inbox, including contact, call and voicemail matches resolved to contacts, in relevance order. Results stay within your company and any exact `phone` filter. An empty query preserves the unfiltered listing. Invalid query types or lengths return `422`. - **limit** (`integer`): Maximum search results when `query` is present. Defaults to `20`, clamped to `1`–`30`. Invalid integers return `422`. Without `query`, listing behavior is unchanged. ```bash curl https://app.phone.inc/api/v1/contacts \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/contacts', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }) ``` ```python import os, requests response = requests.get( "https://app.phone.inc/api/v1/contacts", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) ``` ```ruby require 'net/http' uri = URI('https://app.phone.inc/api/v1/contacts') response = Net::HTTP.get_response( uri, { 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY') }, ) ``` ```json [ { "id": "01JVWX...", "name": "Niklas Stephenson", "email": "niklas@example.com", "phone": "+4520123456", "phone_formatted": "+45 20 12 34 56", "company_name": "Stephenson ApS", "note": "Always asks for the engineering team.", "last_contact_at": "2026-06-12T14:22:00Z", "created_at": "2026-06-10T10:00:00Z", "updated_at": "2026-06-10T10:00:00Z" } ] ``` --- ## Create a contact Adds a new contact. The phone number must be unique within your company — creating a second contact with the same number returns `422 Unprocessable Entity`. ### Required attributes - **phone** (`string`): Phone number in E.164 format. Spaces and other non-digit characters are stripped before validation, so `+45 20 12 34 56` is accepted. ### Optional attributes - **name** (`string`): Display name. - **email** (`string`): Email address. Validated when present. - **company_name** (`string`): The contact's employer or business. - **note** (`string`): Free-form note (up to 10,000 characters). ```bash curl -X POST https://app.phone.inc/api/v1/contacts \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Niklas Stephenson", "email": "niklas@example.com", "phone": "+4520123456", "company_name": "Stephenson ApS", "note": "Always asks for the engineering team." }' ``` ```js const response = await fetch('https://app.phone.inc/api/v1/contacts', { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Niklas Stephenson', email: 'niklas@example.com', phone: '+4520123456', company_name: 'Stephenson ApS', note: 'Always asks for the engineering team.', }), }) ``` ```python import os, requests response = requests.post( "https://app.phone.inc/api/v1/contacts", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, json={ "name": "Niklas Stephenson", "email": "niklas@example.com", "phone": "+4520123456", "company_name": "Stephenson ApS", "note": "Always asks for the engineering team.", }, ) ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/contacts') http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true request = Net::HTTP::Post.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = { name: 'Niklas Stephenson', email: 'niklas@example.com', phone: '+4520123456', company_name: 'Stephenson ApS', note: 'Always asks for the engineering team.', }.to_json response = http.request(request) ``` ```json { "id": "01JVWX...", "name": "Niklas Stephenson", "email": "niklas@example.com", "phone": "+4520123456", "phone_formatted": "+45 20 12 34 56", "company_name": "Stephenson ApS", "note": "Always asks for the engineering team.", "last_contact_at": null, "created_at": "2026-06-10T10:00:00Z", "updated_at": "2026-06-10T10:00:00Z" } ``` --- ## Retrieve a contact Returns a single contact by its ID. Returns `404 Not Found` if the contact doesn't exist or belongs to a different company. ```bash curl https://app.phone.inc/api/v1/contacts/01JVWX... \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch( 'https://app.phone.inc/api/v1/contacts/01JVWX...', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }, ) ``` ```python import os, requests response = requests.get( "https://app.phone.inc/api/v1/contacts/01JVWX...", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) ``` ```ruby require 'net/http' uri = URI('https://app.phone.inc/api/v1/contacts/01JVWX...') response = Net::HTTP.get_response( uri, { 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY') }, ) ``` ```json { "id": "01JVWX...", "name": "Niklas Stephenson", "email": "niklas@example.com", "phone": "+4520123456", "phone_formatted": "+45 20 12 34 56", "company_name": "Stephenson ApS", "note": "Always asks for the engineering team.", "last_contact_at": "2026-06-12T14:22:00Z", "created_at": "2026-06-10T10:00:00Z", "updated_at": "2026-06-10T10:00:00Z" } ``` --- ## Update a contact Updates one or more fields on an existing contact. Send only the fields you want to change. ### Optional attributes - **name** (`string`): New display name. - **email** (`string`): New email address. - **phone** (`string`): New phone number. Must remain unique within your company. - **company_name** (`string`): New employer or business name. - **note** (`string`): Replace the existing note. ```bash curl -X PATCH https://app.phone.inc/api/v1/contacts/01JVWX... \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"note": "Prefers email follow-ups."}' ``` ```js const response = await fetch( 'https://app.phone.inc/api/v1/contacts/01JVWX...', { method: 'PATCH', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ note: 'Prefers email follow-ups.' }), }, ) ``` ```python import os, requests response = requests.patch( "https://app.phone.inc/api/v1/contacts/01JVWX...", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, json={"note": "Prefers email follow-ups."}, ) ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/contacts/01JVWX...') http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true request = Net::HTTP::Patch.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = { note: 'Prefers email follow-ups.' }.to_json response = http.request(request) ``` ```json { "id": "01JVWX...", "name": "Niklas Stephenson", "email": "niklas@example.com", "phone": "+4520123456", "phone_formatted": "+45 20 12 34 56", "company_name": "Stephenson ApS", "note": "Prefers email follow-ups.", "last_contact_at": "2026-06-12T14:22:00Z", "created_at": "2026-06-10T10:00:00Z", "updated_at": "2026-06-10T14:30:00Z" } ``` --- ## Delete a contact Permanently removes a contact. Calls already in your archive keep their `from`/`to` numbers but lose the contact link. ```bash curl -X DELETE https://app.phone.inc/api/v1/contacts/01JVWX... \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch( 'https://app.phone.inc/api/v1/contacts/01JVWX...', { method: 'DELETE', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }, ) ``` ```python import os, requests response = requests.delete( "https://app.phone.inc/api/v1/contacts/01JVWX...", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) ``` ```ruby require 'net/http' uri = URI('https://app.phone.inc/api/v1/contacts/01JVWX...') request = Net::HTTP::Delete.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true response = http.request(request) ``` Returns `204 No Content` on success. --- # Custom caller context Connect any internal system — a CRM, helpdesk, ERP, or custom database — to Phone.inc's caller context by hosting a single JSON endpoint. When a call comes in, we call your URL with the phone number and display the response to your team. ## How it works 1. You expose an HTTPS endpoint that accepts a `phone` query parameter 2. In the Phone.inc dashboard, you add the URL under Integrations → Custom Endpoint 3. On every incoming call, we `GET` your URL with the caller's phone number appended 4. Your endpoint returns JSON matching the schema below 5. Your team sees the data in the sidebar before they pick up ## Setting it up Go to **Integrations** in your Phone.inc dashboard, find "Custom Endpoint" in the available integrations, and click Connect. Enter your endpoint URL and save. For authentication without API tokens in the URL, enable [request signing](#optional-request-signing). Signing is optional and off by default. Existing unsigned endpoints and URLs with query-string credentials continue to work unchanged: ``` https://your-api.com/caller-lookup?token=abc123 ``` We'll append `&phone=%2B4571999900` to that URL on each call. Enabling signing does not remove existing credentials from your URL; remove them yourself once your endpoint verifies signatures. ## Optional request signing 1. In the Custom Endpoint connection editor, enable **Sign requests**. Phone.inc automatically generates a fresh Ed25519 key pair in your browser. 2. Copy the **Public key** to your endpoint's configuration. It is a 32-byte raw public key encoded as 44 standard Base64 characters, including the final `=` padding, without PEM headers. Only the public key belongs on your server. Phone.inc stores the private key encrypted and never returns it from the editor or test response. 3. Follow the Ruby verification example, then use **Test** with an E.164 phone number. Tests use the current signing settings, including an unsaved replacement key. 4. Save the connection to apply those settings to live lookups. Each time you enable signing, a new key pair is generated. To rotate a key, switch signing off and back on in the editor without saving between those steps. Install the new public key on your endpoint alongside the old public key, test, and save. Remove the old public key after saving. Saving with signing disabled sends no signing headers. An endpoint that requires signatures will reject unsigned requests until you change its policy. Signing applies only to caller-context GET requests, not AI tool operations. HTTPS is still required. Signed endpoint URLs cannot contain embedded username/password credentials or fragments. ### Signature contract Signed requests include: | Header | Value | |--------|-------| | `X-Phone-Inc-Timestamp` | Unix timestamp in seconds | | `X-Phone-Inc-Signature` | `ed25519-v1=` followed by a standard Base64 signature | The algorithm is **Ed25519**, with a 64-byte signature (88 Base64 characters). Verify the signature over these four UTF-8 lines, joined by a single LF (`\n`), with **no trailing newline**. Pass the message directly to Ed25519; do not hash it first: ```text GET : ``` Always include the port, including `443` for the default HTTPS port. The path includes a leading `/`. Preserve the exact query encoding and order, including the appended `phone`; do not parse and re-encode it. For example: ```text 1793275200 GET your-api.com:443 /caller-lookup?account=acme&phone=%2B4571999900 ``` Use your configured public endpoint hostname and port, not an untrusted forwarded header or internal reverse-proxy hostname. Reject missing headers, unknown signature versions, malformed signatures, failed verification, and timestamps more than five minutes in the past **or future**. Keep server clocks synchronized. For strict replay prevention within that window, atomically record each verified signature in a shared cache for the remaining validity window and reject duplicates; caller-context GETs must remain read-only. This protocol is distinct from partner caller-context signing, which uses shared-secret HMAC and `v1=` signatures. ### Ruby verification For Ruby 3.4+ and Rails, no extra gems are needed. Set `PHONE_INC_CONTEXT_PUBLIC_KEY` to the public key copied from the editor. Replace `your-api.com:443` with your public endpoint's lowercase hostname and port. Add this method to your lookup controller: ```ruby require 'openssl' require 'base64' def valid_phone_inc_request?(request) timestamp = request.headers['X-Phone-Inc-Timestamp'].to_s header = request.headers['X-Phone-Inc-Signature'].to_s return false unless timestamp.match?(/\A\d{1,12}\z/) return false if (Time.now.to_i - timestamp.to_i).abs > 300 return false unless header.start_with?('ed25519-v1=') key = OpenSSL::PKey.new_raw_public_key( 'ED25519', Base64.strict_decode64(ENV.fetch('PHONE_INC_CONTEXT_PUBLIC_KEY')) ) signature = Base64.strict_decode64(header.delete_prefix('ed25519-v1=')) message = [ timestamp, request.request_method, 'your-api.com:443', request.original_fullpath ].join("\n") key.verify(nil, signature, message) rescue ArgumentError, OpenSSL::PKey::PKeyError false end ``` At the start of your lookup action, reject invalid requests before reading or returning caller data: ```ruby return head(:unauthorized) unless valid_phone_inc_request?(request) ``` If a proxy rewrites paths, verify against the original public path and raw query string before rewriting, or preserve them through a trusted proxy configuration. This example bounds replay to five minutes; add the shared replay cache described above if your policy requires single-use requests. Verify before querying your CRM or returning caller data. A valid signature authenticates Phone.inc's request, not the caller's identity. ## Endpoint contract ### Request We make a GET request to your URL with the caller's phone number appended as a query parameter: ``` GET https://your-api.com/caller-lookup?phone=%2B4571999900 ``` - Phone numbers are URL-encoded E.164 format (e.g. `+4571999900` becomes `%2B4571999900`) - If your URL already has query parameters, we append `&phone=...` - We set a timeout of 2.5 seconds - We send `Accept: application/json` ### Response Return a JSON object with `provider`, `label`, and `source`. Include `contact`, `sections`, or both — a contact-only response is valid and is normalized with an empty `sections` array: ```json { "provider": "internal_crm", "label": "Internal CRM", "source": "acme-corp", "url": "https://crm.acme.com/contacts/456", "contact": { "name": "Jamie Rivera", "email": "jamie@example.com", "company_name": "Acme Inc.", "note": "VIP customer" }, "sections": [ { "type": "fields", "fields": [ { "label": "Account Manager", "value": "Sarah Jensen" }, { "label": "Contract Value", "value": { "amount": "24000", "currency": "DKK" }, "format": "money" }, { "label": "Renewal", "value": "2026-09-01T00:00:00Z", "format": "date" } ] }, { "type": "table", "label": "Open Tickets", "columns": [ { "key": "id", "label": "Ticket" }, { "key": "subject", "label": "Subject" }, { "key": "status", "label": "Status", "format": "badge" } ], "rows": [ { "url": "https://crm.acme.com/tickets/78", "values": { "id": "#78", "subject": "Invoice question", "status": "Open" } }, { "url": "https://crm.acme.com/tickets/65", "values": { "id": "#65", "subject": "Delivery delay", "status": "Resolved" } } ] } ] } ``` ### Required fields | Field | Type | Description | |-------|------|-------------| | `provider` | string | A machine-readable slug for your system (lowercase, no spaces) | | `label` | string | Human-readable name shown in the UI | | `source` | string | Account or workspace identifier | ### Optional fields | Field | Type | Description | |-------|------|-------------| | `url` | string | Link to the matched record in your system | | `contact` | object | Identity to create or update in Phone.inc's contacts | | `sections` | array | Array of section objects (see below). Omitted or null values become an empty array. | ## Cache the matched contact Include a `contact` object when the caller matched by your endpoint should be cached in Phone.inc's address book: ```json { "contact": { "name": "Jamie Rivera", "email": "jamie@example.com", "company_name": "Acme Inc.", "note": "VIP customer" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `name` | string | Yes | Contact name, up to 128 characters | | `email` | string | No | Valid email address, truncated to 320 characters before validation. Invalid values are omitted. | | `company_name` | string | No | Business or employer name, up to 128 characters | | `note` | string | No | Note copied to the contact, up to 10,000 characters | The `phone` query parameter from our request becomes the contact's phone number. Do not return a separate phone inside `contact`. When the phone number has no Phone.inc contact, we create one. When a contact already exists, we fill only blank fields. Data from your endpoint never overwrites a name, email, company name, or note saved by a user. The `contact` object controls address-book caching. The `sections` array controls what employees see in caller context. You can return either or both in the same response. A response without `contact` continues to work exactly as before. ## Section types ### Fields section A vertical list of label/value pairs. ```json { "type": "fields", "label": "Customer Info", "fields": [ { "label": "Name", "value": "Niklas Stephenson" }, { "label": "Email", "value": "niklas@example.com", "format": "email" }, { "label": "Phone", "value": "+4571999900", "format": "phone" } ] } ``` Each field has: | Key | Type | Required | Description | |-----|------|----------|-------------| | `label` | string | Yes | The label shown to the left of the value | | `value` | string, number, or money object | Yes | The value to display | | `format` | string | No | How to render the value (see format hints) | | `url` | string | No | Makes the value a clickable link | ### Table section A compact table with column headers and rows. Columns are rendered in a two-line layout per row: the first half of columns stacks on the left, the second half on the right. For example, with four columns `[Order, Date, Total, Status]`, each row renders as: ``` #1001 $89.00 Apr 28 Paid ``` Order your columns so the primary identifier is first and the most important secondary value is in the right-hand half (at position `ceil(columns.length / 2)`). ```json { "type": "table", "label": "Recent Orders", "columns": [ { "key": "name", "label": "Order" }, { "key": "date", "label": "Date", "format": "date" }, { "key": "total", "label": "Total", "format": "money" } ], "rows": [ { "url": "https://your-system.com/orders/1001", "values": { "name": "#1001", "date": "2026-04-28T12:00:00Z", "total": { "amount": "89", "currency": "DKK" } } } ] } ``` ## Format hints | Format | Value type | Rendering | |--------|-----------|-----------| | `text` | String (default if omitted) | Rendered as-is | | `money` | `{ "amount": "89", "currency": "DKK" }` | Locale-formatted with currency symbol | | `date` | ISO 8601 string | Formatted date | | `email` | String | Clickable mailto link | | `phone` | String (E.164) | Tap-to-call on mobile | | `badge` | String | Colored status pill | To make any value clickable, use the field-level `url` property instead of a format hint. The `url` property works with every format — for example, a badge value with a `url` renders as a pill that links to the given URL. ## Limits We enforce these limits to keep the UI fast and readable: | Limit | Maximum | |-------|---------| | Sections per response | 5 | | Fields per fields section | 15 | | Columns per table section | 8 | | Rows per table section | 10 | | Value string length | 500 characters | Data beyond these limits is silently truncated. Unknown keys in the JSON are silently ignored — we will never reject a payload for having extra fields, so you can safely add internal metadata without breaking the integration. ## Error handling | Your response | Our behavior | |---------------|-------------| | HTTP 200 with valid JSON | Display the data | | HTTP 200 with empty/invalid JSON | Skip silently (no error shown) | | HTTP 404 or empty body | Skip silently — caller not found in your system | | HTTP 429 | Retry on next call, log as rate-limited | | HTTP 5xx or timeout | Log as transient error, retry on next call | | Connection refused | Log as transient error | We never mark the integration as permanently broken for transient errors. Your team won't see error states for occasional blips. ## Example implementation A minimal Node.js/Express endpoint: ```js const express = require('express') const app = express() app.get('/caller-lookup', (req, res) => { const phone = req.query.phone if (!phone) return res.status(400).json({ error: 'phone required' }) // Look up the caller in your system const customer = db.findCustomerByPhone(phone) if (!customer) return res.status(404).json({}) res.json({ provider: 'my_crm', label: 'My CRM', source: 'production', url: `https://crm.example.com/customers/${customer.id}`, contact: { name: customer.name, email: customer.email, company_name: customer.companyName, note: customer.note, }, sections: [ { type: 'fields', fields: [ { label: 'Name', value: customer.name }, { label: 'Email', value: customer.email, format: 'email' }, { label: 'Account type', value: customer.tier, format: 'badge' }, ], }, ], }) }) app.listen(3000) ``` --- # Departments A department brings employees together in one shared FIFO call queue. Calls from any business number, call flow or AI receptionist join the same queue. Employees can belong to several departments. ## The department model - **id** (`string`):Stable public UUID. Also identifies the department's queue. - **name** (`string`):Required. Unique within the account, up to 100 characters. - **description** (`string`):Required, up to 300 characters. Explains when an AI receptionist should route a call here. - **employee_ids** (`array`):Public employee UUIDs. At least one account employee is required when saving. Pending invitations may be members but cannot answer until available. Queue priority starts when a caller enters the department, not when the original call starts. Repeated entry into the same department preserves the queue timestamp and deadline. Moving to a different department starts a new position there. Employee membership is refreshed while callers wait. Each caller keeps the originating business number's waiting audio, maximum wait and no-answer destination. Calls can therefore share queue order while having different deadlines. A department selected as the no-answer destination uses the existing indefinite fallback-queue behavior. Unavailable employees do not prevent callers joining the queue. For `TransferConfig` or `WelcomeTransferConfig`, use `department_id` instead of `employee_ids` in any of the three [business-number routing slots](/api/business-numbers). Send `employee_ids: []` when replacing an employee destination. Send `department_id: null` when switching back to employees. Do not combine both destination types. Phone-menu options continue to select employees. For a receptionist, set `configuration.department_ids` to the departments it may use. These are normal queue transfers, not employee warm transfers. Names and routing descriptions are read when each AI call starts; membership stays live while waiting. Existing configurations without this optional field have no department grants. All endpoints require an API key or an authorized OAuth token and are scoped to its account. Unknown department IDs return `404`. Invalid names, descriptions, empty membership or foreign employee IDs return `422`. Failed updates preserve existing membership. ## List departments Returns all departments in name order, with public employee IDs. ```bash curl https://app.phone.inc/api/v1/departments -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js await fetch('https://app.phone.inc/api/v1/departments', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }) ``` ```python requests.get('https://app.phone.inc/api/v1/departments', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}) ``` ```ruby Net::HTTP.get(URI('https://app.phone.inc/api/v1/departments'), { 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY') }) ``` ```json {"departments":[{"id":"019daef1-085e-7000-aaaa-000000000003","name":"Sales","description":"Quotes and new orders","employee_ids":["019daef1-085e-7000-aaaa-000000000001"]}]} ``` --- ## Create a department Provide `name`, `description` and a non-empty `employee_ids` array. Returns the department with status `201`. ```bash curl https://app.phone.inc/api/v1/departments -H "X-Api-Key: $PHONE_INC_API_KEY" -H 'Content-Type: application/json' -d '{"name":"Sales","description":"Quotes and new orders","employee_ids":["019daef1-085e-7000-aaaa-000000000001"]}' ``` ```js await fetch('https://app.phone.inc/api/v1/departments', { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Sales', description: 'Quotes and new orders', employee_ids: ['019daef1-085e-7000-aaaa-000000000001'] }) }) ``` ```python requests.post('https://app.phone.inc/api/v1/departments', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, json={'name': 'Sales', 'description': 'Quotes and new orders', 'employee_ids': ['019daef1-085e-7000-aaaa-000000000001']}) ``` ```ruby uri = URI('https://app.phone.inc/api/v1/departments') request = Net::HTTP::Post.new(uri, 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY'), 'Content-Type' => 'application/json') request.body = { name: 'Sales', description: 'Quotes and new orders', employee_ids: ['019daef1-085e-7000-aaaa-000000000001'] }.to_json Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } ``` ```json {"id":"019daef1-085e-7000-aaaa-000000000003","name":"Sales","description":"Quotes and new orders","employee_ids":["019daef1-085e-7000-aaaa-000000000001"]} ``` --- ## Retrieve a department Returns the current department and membership. Use its public UUID, not an internal database ID. ```bash curl "https://app.phone.inc/api/v1/departments/$DEPARTMENT_ID" -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js await fetch(`https://app.phone.inc/api/v1/departments/${departmentId}`, { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }) ``` ```python requests.get(f'https://app.phone.inc/api/v1/departments/{department_id}', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}) ``` ```ruby Net::HTTP.get(URI("https://app.phone.inc/api/v1/departments/#{department_id}"), { 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY') }) ``` ```json {"id":"019daef1-085e-7000-aaaa-000000000003","name":"Sales","description":"Quotes and new orders","employee_ids":["019daef1-085e-7000-aaaa-000000000001"]} ``` --- ## Update a department Omitted fields are unchanged. Providing `employee_ids` replaces the entire membership, so read the current department first. Returns status `200`. ```bash curl -X PATCH "https://app.phone.inc/api/v1/departments/$DEPARTMENT_ID" -H "X-Api-Key: $PHONE_INC_API_KEY" -H 'Content-Type: application/json' -d '{"description":"New orders and product advice"}' ``` ```js await fetch(`https://app.phone.inc/api/v1/departments/${departmentId}`, { method: 'PATCH', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ description: 'New orders and product advice' }) }) ``` ```python requests.patch(f'https://app.phone.inc/api/v1/departments/{department_id}', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, json={'description': 'New orders and product advice'}) ``` ```ruby uri = URI("https://app.phone.inc/api/v1/departments/#{department_id}") request = Net::HTTP::Patch.new(uri, 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY'), 'Content-Type' => 'application/json') request.body = { description: 'New orders and product advice' }.to_json Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } ``` ```json {"id":"019daef1-085e-7000-aaaa-000000000003","name":"Sales","description":"New orders and product advice","employee_ids":["019daef1-085e-7000-aaaa-000000000001"]} ``` --- ## Delete a department Returns `204` with no body. Remove call-flow and receptionist assignments first. Queue entries, including retained queue history, also prevent deletion. In-use departments return `422`. ```bash curl -X DELETE "https://app.phone.inc/api/v1/departments/$DEPARTMENT_ID" -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js await fetch(`https://app.phone.inc/api/v1/departments/${departmentId}`, { method: 'DELETE', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }) ``` ```python requests.delete(f'https://app.phone.inc/api/v1/departments/{department_id}', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}) ``` ```ruby uri = URI("https://app.phone.inc/api/v1/departments/#{department_id}") request = Net::HTTP::Delete.new(uri, 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY')) Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } ``` --- # Employees An employee is someone on your team who can answer calls, make outbound calls, and access the Phone.inc dashboard. Use the Employees API to add new team members, update their details, and remove people who've left. ## The employee model Each employee has a stable public `id`, a display name, contact details, and an invitation status that tells you whether they've accepted their account invitation. ### Properties - **id** (`string`): Unique identifier for the employee. - **name** (`string`): The employee's full display name, e.g. `Alex Wong`. - **departments** (`array`): Department memberships, each containing a public `id` and `name`. Manage memberships through the [Departments API](/api/departments). An employee can belong to several departments. - **first_name** (`string`): The employee's first name. - **last_name** (`string`): The employee's last name. - **email** (`string`): The employee's email address. Must be unique across all Phone.inc accounts. - **phone** (`string`): The employee's phone number. May be `null`. Not used for inbound call routing. - **invitation_pending** (`boolean`): `true` if the employee hasn't signed in yet (invitation was sent but not accepted). - **status** (`string`): Live presence for this employee. One of `on_call`, `do_not_disturb`, `ringing`, `available`, `logged_out`, or `unknown`. Point-in-time snapshot — poll the endpoint to refresh. See status values below. - **do_not_disturb** (`boolean`): `true` when the employee has enabled do-not-disturb and will not be offered inbound calls. - **do_not_disturb_activated_at** (`timestamp`): ISO 8601 timestamp of when do-not-disturb was last enabled. `null` when do-not-disturb is off. - **do_not_disturb_expires_at** (`timestamp`): ISO 8601 timestamp of when do-not-disturb will turn off automatically. `null` when do-not-disturb is off or set indefinitely. - **created_at** (`timestamp`): ISO 8601 timestamp of when the employee was created. - **updated_at** (`timestamp`): ISO 8601 timestamp of when the employee was last modified. Passwords and two-factor authentication settings are not exposed through this API and cannot be changed via API calls. Employees manage these through the dashboard. ### Status values `status` is derived from live signals (browser softphone, mobile app reachability, do-not-disturb, and in-progress calls). Precedence is `on_call` > `do_not_disturb` > `ringing` > `available` > `logged_out`. - **on_call**: The employee is on an active call right now. - **do_not_disturb**: The employee has enabled do-not-disturb and will not be offered inbound calls. If they enable it while on a call, status stays `on_call` until the call ends. - **ringing**: An inbound call is currently ringing this employee. May not be reported on all accounts. - **available**: The employee has a live browser softphone session or a reachable mobile app and can take calls. - **logged_out**: No live browser session and no reachable mobile app — or the invitation is still pending. - **unknown**: Status could not be determined. Treat as a defensive fallback. --- ## List all employees Returns every employee on the authenticated company. The response is a single array — there's no pagination. ```bash curl https://app.phone.inc/api/v1/employees \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch( 'https://app.phone.inc/api/v1/employees', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }, ) const { employees } = await response.json() ``` ```python import os, requests response = requests.get( "https://app.phone.inc/api/v1/employees", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) employees = response.json()["employees"] ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/employees') response = Net::HTTP.get_response( uri, { 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY') }, ) employees = JSON.parse(response.body)['employees'] ``` ```json { "employees": [ { "id": "0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20", "name": "Alex Wong", "first_name": "Alex", "last_name": "Wong", "email": "alex@example.com", "phone": "+14155551234", "invitation_pending": false, "status": "available", "do_not_disturb": false, "do_not_disturb_activated_at": null, "do_not_disturb_expires_at": null, "created_at": "2026-04-01T10:00:00Z", "updated_at": "2026-05-10T08:30:00Z" }, { "id": "0193f4b0-bbbb-7c00-9e3d-2b2b8a7f1c21", "name": "Jamie Chen", "first_name": "Jamie", "last_name": "Chen", "email": "jamie@example.com", "phone": null, "invitation_pending": true, "status": "logged_out", "do_not_disturb": false, "do_not_disturb_activated_at": null, "do_not_disturb_expires_at": null, "created_at": "2026-05-14T16:00:00Z", "updated_at": "2026-05-14T16:00:00Z" } ] } ``` --- ## Create an employee When the company's `entitlements.add_employees` is false, this endpoint returns HTTP `403` with `{"error":"upgrade_required","feature":"add_employees"}`. No employee or invitation is created. Upgrade to Pro before retrying. Existing employee updates remain available. Read the current entitlements from [the company API](/api/company). Creates a new employee and sends them an invitation email. The employee will appear with `invitation_pending: true` until they accept the invitation and sign in for the first time. A random password is generated server-side — the employee sets their own password through the invitation flow. Provide `email` and either `name` or both `first_name` and `last_name`. When structured name fields are present, they take precedence over `name`. ### Required attributes - **name** (`string`): The employee's full display name. Required unless both `first_name` and `last_name` are provided. Must contain at least two words. The final word is stored as the last name. - **first_name** (`string`): The employee's first name. If supplied, `last_name` must also be supplied, even when `name` is present. - **last_name** (`string`): The employee's last name. If supplied, `first_name` must also be supplied, even when `name` is present. - **email** (`string`): The employee's email address. Must be unique. ### Optional attributes - **phone** (`string`): The employee's phone number. Not used for inbound call routing. ```bash curl -X POST https://app.phone.inc/api/v1/employees \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Jamie Chen","email":"jamie@example.com","phone":"+14155559876"}' ``` ```js const response = await fetch('https://app.phone.inc/api/v1/employees', { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Jamie Chen', email: 'jamie@example.com', phone: '+14155559876', }), }) const employee = await response.json() ``` ```python import os, requests response = requests.post( "https://app.phone.inc/api/v1/employees", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, json={ "name": "Jamie Chen", "email": "jamie@example.com", "phone": "+14155559876", }, ) employee = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/employees') request = Net::HTTP::Post.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = JSON.generate( name: 'Jamie Chen', email: 'jamie@example.com', phone: '+14155559876', ) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end employee = JSON.parse(response.body) ``` ```json { "id": "0193f4b0-bbbb-7c00-9e3d-2b2b8a7f1c21", "name": "Jamie Chen", "first_name": "Jamie", "last_name": "Chen", "email": "jamie@example.com", "phone": "+14155559876", "invitation_pending": true, "status": "logged_out", "do_not_disturb": false, "do_not_disturb_activated_at": null, "do_not_disturb_expires_at": null, "created_at": "2026-05-15T16:00:00Z", "updated_at": "2026-05-15T16:00:00Z" } ``` --- ## Retrieve an employee Returns a single employee by their public `id`. Returns `404` if the employee doesn't exist on this company's account. ```bash curl https://app.phone.inc/api/v1/employees/0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20 \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch( `https://app.phone.inc/api/v1/employees/${employeeId}`, { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }, ) const employee = await response.json() ``` ```python import os, requests response = requests.get( f"https://app.phone.inc/api/v1/employees/{employee_id}", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) employee = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI("https://app.phone.inc/api/v1/employees/#{employee_id}") response = Net::HTTP.get_response( uri, { 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY') }, ) employee = JSON.parse(response.body) ``` ```json { "id": "0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20", "name": "Alex Wong", "first_name": "Alex", "last_name": "Wong", "email": "alex@example.com", "phone": "+14155551234", "invitation_pending": false, "status": "available", "do_not_disturb": false, "do_not_disturb_activated_at": null, "do_not_disturb_expires_at": null, "created_at": "2026-04-01T10:00:00Z", "updated_at": "2026-05-10T08:30:00Z" } ``` --- ## Update an employee Updates an employee's profile fields. Pass only the fields you want to change. Passwords and two-factor authentication settings cannot be changed through this endpoint. Returns `409 Conflict` if another request changes or deletes the employee while the update is in progress. Retrieve the employee again before retrying; a deleted employee returns `404`. ### Optional attributes - **name** (`string`): New full display name. Must contain at least two words. The final word is stored as the last name. - **first_name** (`string`): New first name. Takes precedence over `name` when either structured name field is present. - **last_name** (`string`): New last name. Takes precedence over `name` when either structured name field is present. - **email** (`string`): New email address. Must be unique. - **phone** (`string`): New phone number, or `null` to clear it. Not used for inbound call routing. ```bash curl -X PATCH https://app.phone.inc/api/v1/employees/0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20 \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Alex W."}' ``` ```js const response = await fetch( `https://app.phone.inc/api/v1/employees/${employeeId}`, { method: 'PATCH', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Alex W.' }), }, ) const employee = await response.json() ``` ```python import os, requests response = requests.patch( f"https://app.phone.inc/api/v1/employees/{employee_id}", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, json={"name": "Alex W."}, ) employee = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI("https://app.phone.inc/api/v1/employees/#{employee_id}") request = Net::HTTP::Patch.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = JSON.generate(name: 'Alex W.') response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end employee = JSON.parse(response.body) ``` ```json { "id": "0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20", "name": "Alex W.", "first_name": "Alex", "last_name": "W.", "email": "alex@example.com", "phone": "+14155551234", "invitation_pending": false, "status": "available", "do_not_disturb": false, "do_not_disturb_activated_at": null, "do_not_disturb_expires_at": null, "created_at": "2026-04-01T10:00:00Z", "updated_at": "2026-05-15T16:10:00Z" } ``` --- ## Delete an employee Marks the employee as deleted and erases their name, email, phone numbers, and authentication data. Deleted employees disappear from employee lists and cannot sign in. Their billable seat is removed through an asynchronous subscription update; the company's subscription stays active. The employee record is retained so calls, transfers, messages, and other historical references remain intact. Historical employee references use the name `Deleted employee`. Devices are removed, sessions and OAuth credentials are revoked, and company API keys are retained without an employee owner. Anonymization applies to the Phone.inc employee record. Existing contacts in external CRM, support, or marketing systems, including Zero, Plain, and Loops, are not erased by this endpoint. Returns an empty response with a `204` status code on success. Retrieving, updating, or deleting the employee again returns `404 Not Found`. Their email address can be used for a new employee. You cannot delete the employee who created the API key you're authenticating with. The API returns `403 Forbidden` if you try. You also can't delete the last employee, an employee assigned as a call target on a business number, or the last kept member of a department. Reassign call targets and add another department member or delete the department first. Successful employee deletion removes their department memberships. These safeguards return `422 Unprocessable Entity`. ```bash curl -X DELETE https://app.phone.inc/api/v1/employees/0193f4b0-bbbb-7c00-9e3d-2b2b8a7f1c21 \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js await fetch( `https://app.phone.inc/api/v1/employees/${employeeId}`, { method: 'DELETE', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }, ) ``` ```python import os, requests requests.delete( f"https://app.phone.inc/api/v1/employees/{employee_id}", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) ``` ```ruby require 'net/http' uri = URI("https://app.phone.inc/api/v1/employees/#{employee_id}") request = Net::HTTP::Delete.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end ``` --- ## Get do not disturb Returns whether do-not-disturb is enabled for the employee, when it was activated, when it expires (if timed), and which business numbers would go straight to no answer if they enable it (because no other assigned employee is currently available, ringing, or on a call). Returns `404` if the employee doesn't exist on this company's account. Use this before enabling do-not-disturb if you want to warn about coverage gaps — the same check the dashboard uses. Success responses use `200`. ```bash curl https://app.phone.inc/api/v1/employees/0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20/do_not_disturb \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch( `https://app.phone.inc/api/v1/employees/${employeeId}/do_not_disturb`, { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }, ) const dnd = await response.json() ``` ```python import os, requests response = requests.get( f"https://app.phone.inc/api/v1/employees/{employee_id}/do_not_disturb", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) dnd = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI("https://app.phone.inc/api/v1/employees/#{employee_id}/do_not_disturb") request = Net::HTTP::Get.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end dnd = JSON.parse(response.body) ``` ```json { "enabled": false, "activated_at": null, "expires_at": null, "at_risk_business_numbers": [ { "id": "0193f4b0-cccc-7c00-9e3d-2b2b8a7f1c22", "name": "Support" } ] } ``` --- ## Set do not disturb Enables or disables do-not-disturb for an employee. While enabled, they are not offered inbound calls on any business number. Assignment on transfer configs is left alone — turning do-not-disturb off restores them automatically. Returns `404` if the employee doesn't exist on this company's account. Enabling cancels any in-flight ring offers for that employee so their devices stop ringing immediately. Success responses use `200` and return the updated employee. Pass an optional `expires_at` when enabling to turn do-not-disturb off automatically at that time. Omit it (or send `null`) for indefinite do-not-disturb. `expires_at` is ignored when `enabled` is `false`. ### Required attributes - **enabled** (`boolean`): `true` to enable do-not-disturb, `false` to disable it. ### Optional attributes - **expires_at** (`timestamp`): ISO 8601 timestamp in the future when do-not-disturb should turn off. Omit or `null` for indefinite. Must be in the future when provided; past values return `422`. ```bash curl -X PUT https://app.phone.inc/api/v1/employees/0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20/do_not_disturb \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"enabled\": true, \"expires_at\": \"$(date -u -v+1H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '+1 hour' +%Y-%m-%dT%H:%M:%SZ)\"}" ``` ```js const expiresAt = new Date(Date.now() + 60 * 60 * 1000).toISOString() const response = await fetch( `https://app.phone.inc/api/v1/employees/${employeeId}/do_not_disturb`, { method: 'PUT', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ enabled: true, expires_at: expiresAt, }), }, ) const employee = await response.json() ``` ```python import os, requests from datetime import datetime, timedelta, timezone expires_at = (datetime.now(timezone.utc) + timedelta(hours=1)).strftime("%Y-%m-%dT%H:%M:%SZ") response = requests.put( f"https://app.phone.inc/api/v1/employees/{employee_id}/do_not_disturb", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, json={"enabled": True, "expires_at": expires_at}, ) employee = response.json() ``` ```ruby require 'net/http' require 'json' require 'time' expires_at = (Time.now.utc + 3600).iso8601 uri = URI("https://app.phone.inc/api/v1/employees/#{employee_id}/do_not_disturb") request = Net::HTTP::Put.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = JSON.generate( enabled: true, expires_at: expires_at, ) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end employee = JSON.parse(response.body) ``` ```json { "id": "0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20", "name": "Alex Wong", "first_name": "Alex", "last_name": "Wong", "email": "alex@example.com", "phone": "+14155551234", "invitation_pending": false, "status": "do_not_disturb", "do_not_disturb": true, "do_not_disturb_activated_at": "2026-08-31T16:10:00Z", "do_not_disturb_expires_at": "2026-08-31T17:10:00Z", "created_at": "2026-04-01T10:00:00Z", "updated_at": "2026-08-31T16:10:00Z" } ``` --- # Errors Every Phone.inc API error has a JSON body and a meaningful HTTP status code. Most failures fall into a small handful of categories — bad input, missing or invalid auth, or a resource that doesn't exist. Use the status code to decide how to react and the body to figure out what to fix. --- ## Status codes - **200 OK**: The request succeeded. The body contains the resource. - **400 Bad Request**: A required parameter is missing or malformed. - **401 Unauthorized**: The credential is missing, malformed, expired, or revoked. For API keys, fix the key. For OAuth tokens, refresh and retry. - **403 Forbidden**: The credential is valid but doesn't grant access to the requested resource. - **404 Not Found**: The resource doesn't exist, or it belongs to a different company than the authenticated credential. - **409 Conflict**: An idempotency key was reused with different SMS input, a text is not safe to retry, or an employee changed or was deleted during an update. Inspect the persisted message or retrieve the employee again before retrying. - **422 Unprocessable Entity**: The request was well-formed but failed validation. The body lists every field-level problem. - **429 Too Many Requests**: Rate limit hit. Look at `Retry-After` for how long to wait before retrying. - **5xx Server Error**: Something broke on our side. Retry reads with exponential backoff. For SMS sends, reuse the same idempotency key and inspect the message: acceptance may be unknown, so a new key could send a duplicate. If it persists, email [support@phone.inc](mailto:support@phone.inc). --- ## Error response shapes Single-message errors use an `error` key — most 400/401/403/404/429 responses look like this: ```json { "error": "Voicemail not found" } ``` Validation errors (422) return an `errors` object keyed by field, mirroring the request body: ```json { "errors": { "listened": ["must be a boolean"] } } ``` OAuth endpoints (`/oauth/token`, `/oauth/authorize`, `/oauth/revoke`) follow the OAuth 2.0 spec and use a different shape — see [OAuth 2.0 for applications](/api/oauth#error-responses) for those. --- ## Authentication errors A `401 Unauthorized` from `/api/v1/*` always means the credential is the problem. The reason depends on whether you sent an API key or an OAuth bearer token. ### API keys Tokens that start with `phk_` are looked up as API keys. If the lookup fails — wrong token, revoked key, typo — you get: ```json { "error": "Invalid API key" } ``` There is no expiry on API keys. A `401` means the key doesn't exist on our side, full stop. Don't retry — fix the key. Generate a new one at [app.phone.inc/api_keys](https://app.phone.inc/api_keys) if needed. ### OAuth bearer tokens Tokens *without* the `phk_` prefix are validated as OAuth access tokens. The response includes a `WWW-Authenticate` header with the specific reason: ```text WWW-Authenticate: Bearer realm="Doorkeeper", error="invalid_token", error_description="The access token expired" ``` Common reasons: - **invalid_token**: The token doesn't exist or was malformed. - **expired_token**: The token expired (access tokens last 1 hour). Use your refresh token to mint a new one. - **revoked_token**: The token was revoked — either by your app calling `/oauth/revoke` or by an admin. The user has to re-authorize. The right move is almost always: refresh the token and retry the request once. If the refresh itself fails, send the user back through the [authorization flow](/api/oauth). ### Partner installations and permissions A partner token also needs an active installation whose current application and customer permissions cover the token. Otherwise `/api/v1/*` returns: ```json { "error": "Application is disconnected" } ``` Start a fresh [authorization flow](/api/oauth) rather than repeatedly refreshing or retrying a disconnected installation. An active installation with a token missing an endpoint's required permissions receives `403 Forbidden`. The body includes `error: "insufficient_scope"` and a `required_scopes` array. For example, a read-only company token attempting to update company details receives: ```json { "error": "insufficient_scope", "required_scopes": ["company:write", "company:read"] } ``` The response also includes the required scopes as a space-separated Bearer challenge: ```text WWW-Authenticate: Bearer error="insufficient_scope", scope="company:write company:read" ``` Enable the required scopes in your application. Then ask the customer to grant fresh consent and exchange a new authorization code. Refresh cannot expand the old token's permissions. An action unavailable to partner tokens returns the same error with an empty `required_scopes` array and `scope=""`; requesting more permissions does not enable that action. --- ## Rate limits Company-owned OAuth applications share fixed one-minute budgets across all tokens and MCP requests: **600 requests per application**, with **120 per application/customer company**. MCP's internal REST dispatch does not consume a second request. Caller-context previews and synthetic webhook tests share a separate budget of **30 per application**, with **5 per application/customer company**, including tests started from the dashboard or through an API key. Regular API keys and first-party clients do not consume the partner API budget. Other limits still apply. Exceeding either partner budget returns `429`, `{ "error": "Application rate limit exceeded. Retry after the indicated delay." }`, and a `Retry-After` header with the seconds until the next minute. Honour the delay; changing tokens does not reset the budget. The public API limits SMS sending and protects against credential-stuffing on `/api/v1/*`. After **10 invalid-key attempts from the same IP within 60 seconds**, that IP is blocked for 60 seconds. Clients sharing a public IP address share this limit. Supplying forwarding headers does not let a client choose a different rate-limit identity. Subsequent requests get: ```json { "error": "Too many failed API key attempts. Wait a moment and try again." } ``` The response includes a `Retry-After: 60` header. Honour it. Valid keys are *not* throttled here — only failed lookups count toward the budget. If you're hitting this in production, your code is probably sending the wrong token; double-check what's in the `X-Api-Key` header before retrying. --- ## SMS send limits New SMS sends, explicit retries, and auto-replies share a limit of **30 send attempts per business number in a rolling minute**. Safe replays of an existing idempotency key do not consume another attempt. Requests over that limit return `429`, `Retry-After: 60`, and `{ "error": "At most 30 message send attempts per business number per minute" }`. ## Common mistakes A few patterns trip up most integrators on day one: - **Forgot the `X-Api-Key` header.** Empty header = `401`. Make sure your HTTP client is actually attaching the key. - **Pasted a key with surrounding whitespace.** Some shells add a trailing newline when copying. Strip whitespace before sending. - **Using a non-E.164 phone number.** Endpoints that accept a phone number (`/api/v1/calls?phone_number=`, `/api/v1/caller_context?phone=`) expect [E.164 format](https://en.wikipedia.org/wiki/E.164) like `+14155551234`. Anything else is silently treated as no match. - **Querying a resource that belongs to another company.** API keys and OAuth tokens are scoped to a single company. A `404` here doesn't mean the ID is wrong globally — just that it's not visible under this credential. - **OAuth: ignoring `expires_in`.** Access tokens expire after 1 hour. Refresh proactively when there are fewer than ~5 minutes left, not on the first `401`. --- ## Retrying Retry reads after `5xx` responses with exponential backoff (e.g. 1s, 2s, 4s, capped at 30s) and a small jitter. Do not blindly retry side-effecting requests. For SMS sends, reuse the original idempotency key and inspect the persisted message's status; a new key can send a duplicate, chargeable text. Only definitively failed texts support the [explicit retry endpoint](/api/texting#retry-a-failed-text). `429` is retryable — wait at least the `Retry-After` value before retrying. Other `4xx` responses need an input or credential fix before you try again. If an error doesn't tell you what to fix, [send us feedback](/api/feedback) so we can make it clearer. --- # Feedback When the API, an MCP tool, or these docs get in your way, tell us. Your integration or AI agent can report a confusing error, wrong or missing docs, or a capability it needs, right from the moment it gets stuck. We read every report, and once we've fixed the API or the docs, we mark it resolved so your agent knows when to try again. Connected over [MCP](/mcp)? The same endpoints are available as the `submit_feedback`, `list_feedback`, and `get_feedback` tools, and the server tells your agent when to use them. ## The feedback model - **id** (`string`):Stable public UUID. - **category** (`string`):Required. One of `bug` (the API behaved differently from its documentation), `documentation` (docs or a tool description are wrong, missing, or unclear), `unclear_error` (an error didn't explain how to recover), `missing_feature` (the API can't do what you need), or `other`. - **summary** (`string`):Required. One sentence describing the problem, up to 200 characters. - **details** (`string`):Required, up to 5,000 characters. What you tried, what happened, and what you expected. - **operation** (`string | null`):Optional, up to 200 characters. The endpoint or MCP tool involved, such as `POST /api/v1/calls/{id}/transfers` or `start_call_transfer`. - **request_id** (`string | null`):Optional, up to 100 characters. The `X-Request-Id` response header of a failing request, so we can find it in our logs. - **status** (`string`):`open` until we've dealt with it. `resolved` means we fixed the API or the docs, so try again. `closed` means we closed it without a change, for example because it duplicates another report or the API already works as intended. - **created_at** (`string`):ISO 8601 timestamp of the report. - **closed_at** (`string | null`):When the report was resolved or closed. `null` while open. Leave API keys, tokens, and personal data such as caller phone numbers out of reports. We don't need them to fix the problem. Reports belong to the account. Any API key or OAuth token for the account can list and read them. Tokens issued to company-owned [applications](/applications) can't use these endpoints and receive `403`. API and MCP submissions share a limit of 20 reports per account per hour; after that, submitting returns `429` with a `Retry-After` header. The list can also include technical reports from your AI receptionist. These contain fixed problem codes and tool names, not caller words or contact details. Their call association stays internal and is not returned by the API or sent to Linear. Receptionist reports have a separate limit of 20 per account per hour and do not use your API submission allowance. ## List feedback Returns the account's 100 most recent reports, newest first. Check here before retrying something you reported. ```bash curl https://app.phone.inc/api/v1/feedback -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js await fetch('https://app.phone.inc/api/v1/feedback', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }) ``` ```python requests.get('https://app.phone.inc/api/v1/feedback', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}) ``` ```ruby Net::HTTP.get(URI('https://app.phone.inc/api/v1/feedback'), { 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY') }) ``` ```json {"feedback":[{"id":"019daef1-085e-7000-aaaa-000000000009","category":"unclear_error","operation":"POST /api/v1/calls/{id}/transfers","summary":"The 422 does not say which field is wrong","details":"Sent employee_id and got an empty errors object. Expected the response to name the missing field.","request_id":"5c1f2a7e-9b3d-4e8a-a1c2-3f4d5e6a7b8c","status":"resolved","created_at":"2026-11-09T14:03:12.481920Z","closed_at":"2026-11-10T09:41:05.120334Z"}]} ``` --- ## Submit feedback Send `category`, `summary`, and `details`, plus `operation` and `request_id` when you have them. Submit once per problem, after trying the documented approach. Returns the report with status `201`. Invalid or missing fields return `422`. ```bash curl https://app.phone.inc/api/v1/feedback -H "X-Api-Key: $PHONE_INC_API_KEY" -H 'Content-Type: application/json' -d '{"category":"unclear_error","operation":"POST /api/v1/calls/{id}/transfers","summary":"The 422 does not say which field is wrong","details":"Sent employee_id and got an empty errors object. Expected the response to name the missing field.","request_id":"5c1f2a7e-9b3d-4e8a-a1c2-3f4d5e6a7b8c"}' ``` ```js await fetch('https://app.phone.inc/api/v1/feedback', { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ category: 'unclear_error', operation: 'POST /api/v1/calls/{id}/transfers', summary: 'The 422 does not say which field is wrong', details: 'Sent employee_id and got an empty errors object. Expected the response to name the missing field.', request_id: '5c1f2a7e-9b3d-4e8a-a1c2-3f4d5e6a7b8c' }) }) ``` ```python requests.post('https://app.phone.inc/api/v1/feedback', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, json={'category': 'unclear_error', 'operation': 'POST /api/v1/calls/{id}/transfers', 'summary': 'The 422 does not say which field is wrong', 'details': 'Sent employee_id and got an empty errors object. Expected the response to name the missing field.', 'request_id': '5c1f2a7e-9b3d-4e8a-a1c2-3f4d5e6a7b8c'}) ``` ```ruby uri = URI('https://app.phone.inc/api/v1/feedback') request = Net::HTTP::Post.new(uri, 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY'), 'Content-Type' => 'application/json') request.body = { category: 'unclear_error', operation: 'POST /api/v1/calls/{id}/transfers', summary: 'The 422 does not say which field is wrong', details: 'Sent employee_id and got an empty errors object. Expected the response to name the missing field.', request_id: '5c1f2a7e-9b3d-4e8a-a1c2-3f4d5e6a7b8c' }.to_json Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } ``` ```json {"id":"019daef1-085e-7000-aaaa-000000000009","category":"unclear_error","operation":"POST /api/v1/calls/{id}/transfers","summary":"The 422 does not say which field is wrong","details":"Sent employee_id and got an empty errors object. Expected the response to name the missing field.","request_id":"5c1f2a7e-9b3d-4e8a-a1c2-3f4d5e6a7b8c","status":"open","created_at":"2026-11-09T14:03:12.481920Z","closed_at":null} ``` --- ## Retrieve feedback Returns one report and its current status. Reports from other accounts return `404`. ```bash curl "https://app.phone.inc/api/v1/feedback/$FEEDBACK_ID" -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js await fetch(`https://app.phone.inc/api/v1/feedback/${feedbackId}`, { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }) ``` ```python requests.get(f'https://app.phone.inc/api/v1/feedback/{feedback_id}', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}) ``` ```ruby Net::HTTP.get(URI("https://app.phone.inc/api/v1/feedback/#{feedback_id}"), { 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY') }) ``` ```json {"id":"019daef1-085e-7000-aaaa-000000000009","category":"unclear_error","operation":"POST /api/v1/calls/{id}/transfers","summary":"The 422 does not say which field is wrong","details":"Sent employee_id and got an empty errors object. Expected the response to name the missing field.","request_id":"5c1f2a7e-9b3d-4e8a-a1c2-3f4d5e6a7b8c","status":"resolved","created_at":"2026-11-09T14:03:12.481920Z","closed_at":"2026-11-10T09:41:05.120334Z"} ``` --- # Inbox Read calls, voicemails, Notes, and messages grouped by external phone number, then open a timeline and mark observed activity seen. Partner OAuth reads of `/api/v1/inbox`, `/api/v1/inbox/people`, `/api/v1/inbox/:phone/activity`, and `/api/v1/activity/unseen` require at least one of `calls:read`, `messages:read`, `voicemails:read`, or `notes:read`. Only granted resource types contribute rows, latest items, previews, timestamps, unseen counts, and pagination. Call reads include recordings, transcripts, summaries, and search; voicemail reads include recordings and transcripts; message reads include texts; Note reads include text and collected details. An explicit `sources` filter can narrow but never expand access; no readable selected source returns `422`. Contact metadata and text searches require `contacts:read`. Phone filters and phone-only queries do not. Embedded employee, contact, department, and business-number details require their matching read scopes; reference IDs remain available. Marking inbox activity seen requires at least one corresponding `:write` plus its dependency `:read`, and only updates writable sources. Read-only types remain untouched. Legacy `/api/v1/calls/seen` checks `calls:write` and `voicemails:write` individually, so call write access cannot alter voicemails. API keys and first-party and public MCP behavior are unchanged. See [OAuth scopes](/api/oauth#scopes). ## The inbox model An inbox thread is a read view, not a persisted conversation. There is no conversation ID or create-conversation endpoint. Threads aggregate activity across the company's business numbers unless a business-number filter is supplied. Contacts with no activity do not produce threads; [Search people](#search-people) lists them next to threads for a typed query. An empty timeline read does not create a contact. Calls linked to a voicemail are represented by the voicemail instead of appearing twice. Threads and timelines are ordered newest first, with deterministic type and record-ID tie-breakers. Calls, voicemails, Notes, and messages are included. See [Texting and inbox](/api/texting) for SMS-specific fields, sending, delivery state, and automatic replies. Written messages taken by the receptionist are [Notes](/api/notes), with activity `type: "note"`, `text`, structured `details`, and nullable `call_id`. Notes have their own `seen_at` and no kind, transcription, listened state, or audio fields. They remain available when SMS messaging is disabled. Note email preferences are separate from voicemail preferences, per employee and business number, and enabled by default. SMS activity continues to use `type: "message"`. Messages are included only when the company's `messaging` feature flag is enabled. The flag defaults to off and is managed by Phone.inc. With messaging off, calls, voicemails, and Notes remain available; SMS is excluded from previews, timelines, unseen counts, and seen updates. Stored messages remain unseen until messaging is enabled and the thread is opened or acknowledged. ### Thread properties - **phone_number** (`string`):Normalized E.164 external phone number. This is the thread address. - **contact** (`object | null`):Existing contact reference, including ID, display name, phone, and saved contact fields; null when no contact exists. - **last_activity_at** (`string`):ISO 8601 creation timestamp of the latest activity. - **unseen_count** (`integer`):Number of unseen inbound activity items, including received messages, after call/voicemail folding. Outbound calls do not count as unseen. - **business_number_ids** (`array`):Public IDs of business numbers represented in this thread at the observation boundary. - **preview** (`string`):Call summary, voicemail transcription, Note text, or SMS message text, with a fallback label; truncated to 160 characters. - **latest_item** (`object`):Latest activity metadata. Full summary, transcription, message text, and recording URL are omitted. For an ended, unanswered inbound call recorded as arriving outside business hours, `preview` is `Outside business hours`, even when a call summary exists. Answered calls retain their summary or `Incoming call` label. Historical calls with an unknown business-hours decision retain their existing preview. ### Activity properties - **id** (`string`):Stable call, voicemail, Note, or message public ID. - **type** (`string`):call, voicemail, note, or message. MMS is not implemented. - **format** (`string`):Message format, currently `sms`. Present only on message items; future formats use the same `message` activity type. - **created_at** (`string`):ISO 8601 storage timestamp, used for ordering and seen boundaries. - **business_number_id** (`string`):Owning business number public ID. - **business_number_name** (`string`):Owning business number name. - **seen_at** (`string | null`):ISO 8601 timestamp when the team marked this activity seen. - **direction** (`string`):inbound or outbound; voicemails are inbound. - **from** (`string`):Originating E.164 phone number. - **to** (`string`):Destination phone number; present on calls and SMS. - **duration** (`integer | null`):Call duration or analyzed voicemail recording length in seconds. Call items also include `state`, `missed`, `summary`, nullable `employee` with `id` and `name`, and `has_transcription`. Voicemail items include `transcription`, `recording_url`, `listened`, and nullable linked `call_id`. Note items use the [Note model](/api/notes#the-note-model): `id`, `type`, `text`, `details`, `from`, nullable `call_id`, nullable `seen_at`, `created_at`, `business_number_id`, and `business_number_name`. The call, voicemail, and SMS-specific properties above are not added to Notes. ### Extensible activity types Treat activity `type` as extensible. Clients should skip types they do not understand without discarding the thread, and still follow `next_cursor` when a page contains no renderable items. An unfamiliar `latest_item.type` must not hide the thread. The seen endpoint acknowledges the entire thread through `observed_at`, not just the items a client rendered. Clients that ignore activity types must not assume those items remain unseen after acknowledging that boundary. ### Pagination and seen state List responses include nullable `next_cursor`. Supply it unchanged as `cursor` to fetch the next page. Cursors are signed and bound to the company, selected business number, endpoint, and filters. Pages share the first request's observation boundary, so later arrivals do not reshuffle that result set. Timeline responses also include `observed_at`. Pass that timestamp to the seen endpoint, rather than generating a timestamp on the client. Seen state is shared by the team, not per employee. The update covers unseen inbound calls, voicemails, Notes, and received messages stored through that boundary, including folded calls, and preserves later arrivals. Seeing a voicemail does not mark it listened. Partner tokens need `notes:write` and `notes:read` to mark Notes seen; write access to another resource does not grant this permission. Invalid filters, phone numbers, timestamps, or cursors return `422`. Future seen timestamps are rejected. Foreign or unknown business numbers return `404`; missing authentication returns `401`. Company API keys and OAuth tokens are supported. The legacy `/api/v1/calls/seen` endpoint updates calls and voicemails only; use the inbox seen endpoint to acknowledge Notes and messages. `/api/v1/activity/unseen` includes people with unseen Notes independently of messaging, and unseen incoming SMS when messaging is enabled. --- ## List the inbox List grouped activity previews. Filter by optional business_number_id, query, or unseen=true. Text queries use the company-isolated keyword and semantic search index, the same search as the web inbox: contact name, company name, email, and note; call transcriptions, summaries, and caller context; and voicemail transcriptions. Call and voicemail matches count only for sources the request can read. At most 100 indexed candidates are resolved to this company's threads; new or edited records become searchable after indexing. Text messages are not indexed. Phone-only queries accept spaces, parentheses, dots, and dashes and match the normalized phone substring directly, without requiring the search index. Mixed text-and-digit queries are searched intact rather than reduced to digits. The maximum query length is 128 characters. limit defaults to 50 and is clamped to 1–100. Supply cursor for another page. ```bash curl 'https://app.phone.inc/api/v1/inbox?limit=50' \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/inbox?limit=50', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }) const data = await response.json() ``` ```python import os import requests response = requests.get( 'https://app.phone.inc/api/v1/inbox?limit=50', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']} ) response.raise_for_status() data = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/inbox?limit=50') request = Net::HTTP::Get.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } data = JSON.parse(response.body) ``` ```json { "threads": [ { "phone_number": "+4523909778", "contact": null, "last_activity_at": "2026-10-07T09:40:59Z", "unseen_count": 1, "business_number_ids": [ "019daef1-085e-762f-98a5-ed28d44138b8" ], "preview": "Missed call", "latest_item": { "id": "019daef1-085e-7700-a1b2-c3d4e5f67890", "type": "call", "direction": "inbound", "missed": true } } ], "next_cursor": null } ``` --- ## Search people Resolve typed digits or a name to the people they point at, as one list: inbox threads first, newest first, then saved contacts with no activity. Use it behind a recipient or keypad field. query is required and at most 128 characters. Phone-only queries match the normalized phone substring of thread numbers and contact numbers. Text queries match contacts only, on name, company name, email, and note, through the company-isolated search index; call and voicemail content is not searched, so a word said in a voicemail never suggests a person. Matching contacts with activity become thread rows, the rest contact rows, most relevant first. A person appears once; a contact who also has a thread is listed as that thread. limit defaults to 10 and is clamped to 1–30. There is no pagination. sources narrows the thread rows as on the inbox. Each row has the [thread properties](#thread-properties). A contact with no activity has `latest_item`, `last_activity_at`, and `preview` set to null, `unseen_count` 0, and an empty `business_number_ids`. Partner OAuth needs an activity read scope. Text queries also require `contacts:read`, and contact-only rows are included only when `contacts:read` is granted. ```bash curl 'https://app.phone.inc/api/v1/inbox/people?query=2390&limit=5' \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/inbox/people?query=2390&limit=5', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }) const data = await response.json() ``` ```python import os import requests response = requests.get( 'https://app.phone.inc/api/v1/inbox/people', params={'query': '2390', 'limit': 5}, headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']} ) response.raise_for_status() data = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/inbox/people?query=2390&limit=5') request = Net::HTTP::Get.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } data = JSON.parse(response.body) ``` ```json { "people": [ { "phone_number": "+4523909778", "contact": { "id": "019daef1-085e-7c00-9e3d-2b2b8a7f1c01", "name": "Lisa Kim", "display_name": "Lisa Kim", "phone": "+4523909778" }, "last_activity_at": "2026-10-07T09:40:59Z", "unseen_count": 1, "business_number_ids": [ "019daef1-085e-762f-98a5-ed28d44138b8" ], "preview": "Missed call", "latest_item": { "id": "019daef1-085e-7700-a1b2-c3d4e5f67890", "type": "call", "direction": "inbound", "missed": true } }, { "phone_number": "+4523909999", "contact": { "id": "019daef1-085e-7c00-9e3d-2b2b8a7f1c02", "name": "Lisa Saved", "display_name": "Lisa Saved", "phone": "+4523909999" }, "last_activity_at": null, "unseen_count": 0, "business_number_ids": [], "preview": null, "latest_item": null } ] } ``` --- ## List activity Read one external phone number’s calls, voicemails, Notes, and messages. E.164 is recommended; national numbers are normalized using the company country. The path phone number takes precedence over query/body values. Optional business_number_id selects one business number. limit defaults to 50 and is clamped to 1–100. Supply cursor for another page. ```bash curl 'https://app.phone.inc/api/v1/inbox/+4523909778/activity?limit=50' \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/inbox/+4523909778/activity?limit=50', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }) const data = await response.json() ``` ```python import os import requests response = requests.get( 'https://app.phone.inc/api/v1/inbox/+4523909778/activity?limit=50', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']} ) response.raise_for_status() data = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/inbox/+4523909778/activity?limit=50') request = Net::HTTP::Get.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } data = JSON.parse(response.body) ``` ```json { "phone_number": "+4523909778", "contact": null, "items": [ { "id": "019daef1-085e-7700-a1b2-c3d4e5f67890", "type": "call", "created_at": "2026-10-07T09:40:59Z", "business_number_id": "019daef1-085e-762f-98a5-ed28d44138b8", "business_number_name": "Office", "seen_at": null, "direction": "inbound", "from": "+4523909778", "to": "+4592457318", "state": "ended", "missed": true, "summary": null, "duration": 0, "employee": null, "has_transcription": false } ], "next_cursor": null, "observed_at": "2026-10-07T09:41:00Z" } ``` --- ## Mark activity seen Mark this thread seen through the required through timestamp returned as observed_at by the activity endpoint. Optional business_number_id limits the update to that business number. Returns 204 No Content. The operation is idempotent and broadcasts a metadata-only unseen-count invalidation. ```bash curl -X POST 'https://app.phone.inc/api/v1/inbox/+4523909778/seen' \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"through":"2026-10-07T09:41:00Z"}' ``` ```js const response = await fetch('https://app.phone.inc/api/v1/inbox/+4523909778/seen', { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({"through":"2026-10-07T09:41:00Z"}) }) if (!response.ok) throw new Error(await response.text()) ``` ```python import os import requests response = requests.post( 'https://app.phone.inc/api/v1/inbox/+4523909778/seen', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, json={"through":"2026-10-07T09:41:00Z"} ) response.raise_for_status() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/inbox/+4523909778/seen') request = Net::HTTP::Post.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = '{"through":"2026-10-07T09:41:00Z"}' response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } raise response.body unless response.is_a?(Net::HTTPSuccess) ``` --- --- # Integrations See which integrations are configured for your account and whether each connection is connected, disconnected, or in an error state. The read-only endpoints use saved connection metadata and do not contact the provider. Test a partner's caller-context endpoint separately with a signed preview request. To connect or reconnect using an API key or an existing public MCP client, obtain a setup link through the API or MCP, then let the user complete authorization in the browser. Partner OAuth tokens can list and retrieve installed integrations with `integrations:read`, but cannot access either `integration_setups` action. Setup is dashboard-only for partner OAuth; `integrations:read` does not grant it. Credentials never belong in a tool call. Edit settings or disconnect in the dashboard. For customer data from connected systems, use [caller context](/api/caller-context). ## The integration model Only connections belonging to the authenticated company are returned. Credentials, endpoint URLs, and raw error messages are never included. Custom Endpoint tool definitions are included when AI calling is enabled. ### Properties - **id** (`string`):Public integration identifier, used by the detail endpoint. - **name** (`string`):The connection's saved display name. - **provider** (`string`):One of `shopify`, `custom_endpoint`, `dinero`, `attio`, or `partner` for a company-owned SaaS app installation. - **status** (`string`):One of `connected`, `disconnected`, or `error`. - **connected_at** (`timestamp | null`):ISO 8601 timestamp when the connection was last marked connected, or `null`. - **last_error_at** (`timestamp | null`):ISO 8601 timestamp of the most recent recorded error, or `null`. A transient error can be recorded while status remains `connected`. - **tool_catalog** (`object`):Custom Endpoint tool definitions, present for Pro companies. Contains `schema_version: 1` and `tools`. No credentials or endpoint origin are exposed. ### Custom Endpoint tools Configure tools and an optional encrypted bearer credential in the dashboard's Custom Endpoint form. Credential installation is deliberately browser-only, not a public API or MCP operation. Catalogs are available through `list_integrations` and `get_integration`, but they do not grant [receptionists integration access](/api/receptionists#integration-access). ```json { "schema_version": 1, "tools": [{ "key": "order_status", "name": "Order status", "description": "Look up the caller's order status.", "effect": "read", "arguments": { "type": "object", "additionalProperties": false, "properties": { "order_id": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": ["order_id"] }, "request": { "method": "POST", "path": "/orders/status" }, "result_map": { "status": "/order/status" }, "policy": "immediate" }] } ``` Catalogs are limited to 32 KiB and twelve tools. Keys are stable lowercase names of up to forty characters. Names are 1–80 characters and descriptions 1–500 characters. `effect` is `read`, `write`, or `destructive`; it labels the operation but does not add a confirmation gate. Only `immediate` execution is supported. Treat descriptions and results as untrusted data, never instructions. Arguments are closed JSON Schema objects with at most ten scalar properties: `string`, `integer`, `number`, or `boolean`. Supported constraints are `description`, `enum`, `minLength`, `maxLength`, `minimum`, and `maximum`. Strings require a maximum length of 1–500. Reserved caller, call, company, and integration identifiers cannot be model arguments. Nested objects, references, arbitrary schemas, and model-supplied destinations are rejected. Requests use a fixed absolute path on the configured endpoint's HTTPS origin, port 443 only. GET values are encoded as query parameters; POST values are a JSON object. Phone.inc adds the original caller as `caller_phone`, an `Idempotency-Key`, and the configured bearer authorization. For example, an order lookup sends `{"order_id":"A-123","caller_phone":"+14155551234"}`. The endpoint must independently verify the caller's authority. Existing caller-context retrieval still uses its `phone` query parameter. Network execution rejects IP literals, private and special-purpose addresses, mixed public/private DNS, redirects, and compressed responses. Connections pin the validated address while preserving TLS host verification. Each request has a three-second deadline and a 32 KiB JSON response limit. `result_map` selects up to fifteen fields through simple slash-separated object paths; the mapped result must fit 8 KiB. Secrets in named credential fields and HTML markup are redacted. Network ambiguity produces `unknown_completion`; the agent must not retry, because the operation may have executed. Customer endpoints should honor the idempotency key. ## Company-owned app installations Any authenticated employee in a customer company can install private SaaS applications through [OAuth consent](/api/oauth#step-1-build-the-authorization-url). Repeated authorization updates one installation per company and application, shown in the dashboard's **Integrations** page and returned by `GET /api/v1/integrations` with `provider: "partner"`. Its public `id` is the `installation_id` returned during token exchange. API-only apps are valid; caller context is optional. Application-owned webhooks are hidden throughout the customer dashboard. Customers stop them by disconnecting the application; only the owning installation's OAuth credentials can edit, delete, retrieve signing secrets, or test them. Publishers inspect a [sanitized delivery log across customer installations](/applications#webhook-delivery-log) under **Applications**. API keys and legacy tokens retain listing and per-subscription delivery-history access for their own company. See [webhook ownership](/api/webhooks#partner-oauth-permissions). These installations are not public marketplace listings or new entries in the built-in provider setup catalog below. The publisher starts authorization with its own OAuth client ID. An ordinary company manages its private app at [Applications](https://app.phone.inc/applications), alongside API keys. See [Applications](/applications) to get started. App creation, rotation, and deletion remain interactive dashboard credential management; no app-credential creation MCP tools are added. Existing integrations and customer-resource API and MCP tools remain available under the same API permission enforcement. When the publisher enables more scopes, **Integrations** shows **Additional permissions available**. **Update permissions** opens the publisher's optional HTTPS Connection URL (`connect_url`); without it, customers are instructed to open the SaaS. Disconnected apps can reconnect through that URL. It starts OAuth in the SaaS's own user session with state and fresh S256 PKCE, not at the OAuth callback. The dashboard does not grant access or automatically expand tokens. The SaaS requests the full desired scope set; consent distinguishes additional, already approved, and omitted (removed) permissions. Approval updates the same installation; cancelling changes nothing. Adding enabled scopes leaves existing installations, tokens, caller context, and webhooks working. Tokens and refresh cannot gain scopes. Reducing installation or application permissions revokes only credentials containing removed scopes; unaffected narrower tokens and installations continue. Removing every installed permission disconnects that installation. Webhook scope ceilings and event lists shrink permanently; expanded access requires a new subscription even if a removed scope is readded. See the [installation lifecycle](/api/oauth#disconnect-rotate-and-reauthorize). Disconnect in the dashboard to revoke the installation's access tokens, refresh tokens, and pending codes and stop caller lookups and webhook deliveries, including queued deliveries and retries. App deletion, secret rotation, and authenticated revocation of a partner token also revoke the whole installation. Changes to redirect URIs or the context endpoint still disconnect installations and require new consent; name, description, and Connection URL changes do not. Historical call context is retained. --- ## List integrations Returns all saved connections, including disconnected connections and connections in an error state, ordered by name. An account with no configured connections returns `[]`. There are no query parameters. MCP equivalent: `list_integrations`. ```bash curl https://app.phone.inc/api/v1/integrations \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/integrations', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }) const integrations = await response.json() ``` ```python import os import requests integrations = requests.get( 'https://app.phone.inc/api/v1/integrations', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, ).json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/integrations') request = Net::HTTP::Get.new(uri, 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY')) response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } integrations = JSON.parse(response.body) ``` ```json [ { "id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc", "name": "Acme Workspace", "provider": "attio", "status": "connected", "connected_at": "2026-10-12T12:00:00Z", "last_error_at": null } ] ``` --- ## List integration providers Returns available installation options: Shopify, Custom Endpoint, Dinero, and Attio. These are providers you can set up, not connections already installed. Use `GET /v1/integrations` for current connections. No query parameters. MCP equivalent: `list_integration_providers`. Each entry contains `provider`, `name`, `description`, `authorization_required`, `setup_path`, and `setup_url`. `authorization_required` is false for Custom Endpoint, which uses a configuration form rather than OAuth. Shopify setup depends on the company's `shopify_app` feature flag. By default, the browser uses the existing merchant-owned app flow with a store URL, Client ID, and Secret. When the flag is enabled, it uses the native Phone.inc Shopify app instead. Existing merchant-owned connections continue to work; reconnecting through the native flow upgrades their credentials. The API and MCP do not accept Shopify app credentials; use these setup endpoints to obtain a browser authorization link. Dinero and Attio require server-side OAuth app configuration. ```bash curl https://app.phone.inc/api/v1/integration_setups \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const providers = await fetch('https://app.phone.inc/api/v1/integration_setups', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }).then(response => response.json()) ``` ```python import os, requests providers = requests.get( 'https://app.phone.inc/api/v1/integration_setups', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, ).json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/integration_setups') providers = JSON.parse(Net::HTTP.get_response(uri, 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY')).body) ``` ```json [ { "provider": "shopify", "name": "Shopify", "description": "Match callers to their Shopify customer record and recent orders.", "authorization_required": true, "setup_path": "/integration_authorizations/shopify?company_id=019daef1-085e-73f0-85f6-a71e2d8dd2cc", "setup_url": "https://app.phone.inc/integration_authorizations/shopify?company_id=019daef1-085e-73f0-85f6-a71e2d8dd2cc" } ] ``` --- ## Get an integration setup link Prepare installation for one provider: `shopify`, `custom_endpoint`, `dinero`, or `attio`. Unknown providers return `404`. MCP equivalent: `get_integration_setup`, with required `provider`. Present `setup_url` as a button or link for the user to click. The dashboard assistant renders an authorization card automatically. Opening the link requires a signed-in browser session for the same company as the API credentials; an account mismatch sends the user back to integrations with an error. The relative `setup_path` is for clients already running on the app host. Obtaining a link does not create a connection, contact the provider, or grant access. The browser flow handles OAuth state, permissions, callback verification, and secrets. The dashboard assistant automatically updates its card after the server verifies and saves the connection; closing the setup tab does not count as success. Credentials and provider errors never enter the assistant's completion status. External API clients should query the integrations list after setup to verify the saved connection. Never claim installation succeeded just because the link was returned. ```bash curl https://app.phone.inc/api/v1/integration_setups/shopify \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const setup = await fetch('https://app.phone.inc/api/v1/integration_setups/shopify', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }).then(response => response.json()) ``` ```python import os, requests setup = requests.get( 'https://app.phone.inc/api/v1/integration_setups/shopify', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, ).json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/integration_setups/shopify') setup = JSON.parse(Net::HTTP.get_response(uri, 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY')).body) ``` ```json { "provider": "shopify", "name": "Shopify", "description": "Match callers to their Shopify customer record and recent orders.", "authorization_required": true, "setup_path": "/integration_authorizations/shopify?company_id=019daef1-085e-73f0-85f6-a71e2d8dd2cc", "setup_url": "https://app.phone.inc/integration_authorizations/shopify?company_id=019daef1-085e-73f0-85f6-a71e2d8dd2cc" } ``` --- ## Get an integration Returns one connection by its public `id` from the list endpoint. An unknown ID or an ID belonging to another company returns `404 Not Found`. MCP equivalent: `get_integration`, with required `id`. ```bash curl https://app.phone.inc/api/v1/integrations/019daef1-085e-73f0-85f6-a71e2d8dd2cc \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const id = '019daef1-085e-73f0-85f6-a71e2d8dd2cc' const response = await fetch(`https://app.phone.inc/api/v1/integrations/${id}`, { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }) const integration = await response.json() ``` ```python import os import requests integration = requests.get( 'https://app.phone.inc/api/v1/integrations/019daef1-085e-73f0-85f6-a71e2d8dd2cc', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, ).json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/integrations/019daef1-085e-73f0-85f6-a71e2d8dd2cc') request = Net::HTTP::Get.new(uri, 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY')) response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } integration = JSON.parse(response.body) ``` ```json { "id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc", "name": "Acme Workspace", "provider": "attio", "status": "connected", "connected_at": "2026-10-12T12:00:00Z", "last_error_at": null } ``` --- ## Test partner caller context Sends a synchronous, signed lookup to one installed partner application's configured context endpoint. Uses the same [request body and signature](/api/caller-context#signed-partner-lookups) as live lookups, but strictly validates the returned context schema before sanitizing it for preview. It does not create or update Phone.inc contacts or enrich a call. Success clears the integration's last error; a provider failure records a transient error without disconnecting an active installation. API keys can test partner installations in their company. Partner OAuth requires `caller_context:provide` and can test only its own installation, not another app in the same company. `caller_context:read` and `integrations:read` do not grant this operation. The installation must be connected, grant `caller_context:provide`, and have a configured endpoint. Built-in providers are not supported here. The dashboard's partner integration test offers the same preview. MCP equivalent: `test_integration_context`, with required `integration_id` and `phone`. ### Required attributes - **phone** (`string`):E.164 phone number: `+` followed by 8–15 digits, with a nonzero first digit. For example, `+14155550199`. ### Status and errors - `200`: returns `context` and the submitted `phone`. `context` is `null` when the partner returns `204` or `404` (no match). - `403`: the OAuth token lacks the required scope. - `404`: unknown integration, another company's integration, a non-partner provider, or an installation not owned by the calling partner. - `422`: invalid or missing phone, with `errors.phone` explaining the required E.164 format. - `429`: the application used its test budget. Each application gets 30 tests per minute, and 5 per minute for each customer. Context and webhook tests share the budget. Wait for the number of seconds in the `Retry-After` header. - `424`: disconnected installation, missing caller-context authorization or endpoint, transport failure, timeout, rate limiting, oversized response, invalid JSON, invalid schema, or other provider failure. The response includes `error` and a `hint` to use a publicly reachable HTTPS endpoint. Tests do not relax SSRF protections: HTTPS and TLS verification remain required; private, loopback, and internal destinations (including private tunnel DNS) are blocked, and redirects are not followed. The same 3-second connect/read timeouts, overall 5-second budget, and 256 KiB response limit apply. Use a public endpoint for development tests. ```bash curl -X POST https://app.phone.inc/api/v1/integrations/019daef1-085e-73f0-85f6-a71e2d8dd2cc/context_test \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"phone":"+14155550199"}' ``` ```js const response = await fetch('https://app.phone.inc/api/v1/integrations/019daef1-085e-73f0-85f6-a71e2d8dd2cc/context_test', { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ phone: '+14155550199' }), }) ``` ```python import os, requests response = requests.post( 'https://app.phone.inc/api/v1/integrations/019daef1-085e-73f0-85f6-a71e2d8dd2cc/context_test', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, json={'phone': '+14155550199'}, ) ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/integrations/019daef1-085e-73f0-85f6-a71e2d8dd2cc/context_test') request = Net::HTTP::Post.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = { phone: '+14155550199' }.to_json response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } ``` ```json { "context": null, "phone": "+14155550199" } ``` A matching `context` uses the [context-entry schema](/api/caller-context#the-caller-context-model), with the registered app's provider identity and label. --- # Link to call Open a URL and Phone.inc places the call for you. Drop the link in a CRM, a support ticket, or an internal tool — when someone clicks it, the web dialer opens and starts calling that number. ## The URL ``` https://app.phone.inc/call/+14155551234 ``` The path is `/call/` followed by the destination phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format (a leading `+` and digits only — no spaces, dashes, or parentheses). | Part | Value | |------|-------| | Host | `https://app.phone.inc` | | Path | `/call/:phone_number` | | `phone_number` | E.164, e.g. `+14155551234` | Anything that doesn't match `+` plus digits returns a 404. ## How it works 1. The person clicking the link must be signed in to Phone.inc. If they aren't, they're sent to the sign-in page first, then continue. 2. The dashboard opens with the number already filled into the dialer. 3. Once WebRTC is ready and a business number is selected, a three-second countdown starts ("Calling in 3…"). 4. When the countdown hits zero, the call goes out from the selected business number. They can cancel during the countdown or while the dialer is still connecting. If they're already on a call, the auto-dial is cancelled so it doesn't interrupt them. This is a dashboard deep link, not an API endpoint. It lives on `app.phone.inc` and requires a signed-in employee. To place calls programmatically, use the web dialer in the browser — there is no REST endpoint for outbound calling yet. ## Encoding the number Most browsers accept the `+` in the path as-is. Some HTTP clients and link shorteners are stricter — if the link breaks, URL-encode the `+` as `%2B`: ``` https://app.phone.inc/call/%2B14155551234 ``` Both forms resolve to the same place. ## Example uses **CRM "Call" button.** Point a contact's Call action at the link so agents dial from Phone.inc instead of their desk phone: ```html Call in Phone.inc ``` **Support tickets.** Include the link in a ticket note or Slack message so whoever picks it up can call the customer in one click. **Internal tools.** Build the URL from any E.164 number you already store: ```js const callUrl = `https://app.phone.inc/call/${encodeURIComponent(phoneE164)}` ``` --- # Notes Notes are written messages taken by your receptionist. Read the message and collected caller details, mark it seen or unseen, or delete it through the API. The receptionist's **Take a note** action saves a Note, not a voicemail or SMS. Enable it in the receptionist's [message-taking configuration](/api/receptionists#messages-and-transfers). The API does not support creating Notes or editing their text or details. ## The Note model The same object represents a Note in this API, [inbox activity](/api/inbox), and [Note webhooks](/api/webhooks#payload-structure). Notes have no kind distinctions, transcription, listened state, or audio fields. Partner OAuth requires `notes:read` to list or retrieve Notes, and `notes:write` plus `notes:read` to update seen state or delete them. The same permissions govern Notes in combined inbox results and seen updates. The Messaging feature flag is not required. Business-number names require `business_numbers:read`; reference IDs remain available. See [OAuth scopes](/api/oauth#scopes). Each employee has a separate Note email notification preference for each business number, enabled by default. It is independent of voicemail email preferences. Notes also appear in the inbox and support `note.created` and `note.deleted` webhooks. The Notes notification setting does not require a receptionist feature flag or environment switch. The four [Note MCP tools](/mcp#notes) follow the same Pro or test-company access rules as receptionist tools; the REST API and inbox still allow access to existing Notes. Previously saved written receptionist messages move from voicemails to Notes, preserving their IDs, content, and seen state. Retrieve them through `/api/v1/notes`, not a voicemail compatibility alias. ### Properties - **id** (`string`):The Note's unique public ID. - **type** (`string`):Always `note`. - **direction** (`string`):Always `inbound` for notes taken during incoming calls. - **text** (`string`):The caller's written message. - **details** (`object`):Selected caller details: `name`, `email`, `company_name`, `reference`, and `callback_time`. Selected fields the caller declined or could not provide are `null`; unselected fields are omitted. `reference` is an order, booking, or customer reference. `callback_time` is the caller's preference as stated, not a scheduled callback or promise. - **from** (`string`):The caller's phone number in E.164 format. - **call_id** (`string | null`):The linked call's public ID, or `null`. - **seen_at** (`string | null`):ISO 8601 timestamp when the team marked the Note seen, or `null` when unseen. Seen state is shared by the team. - **created_at** (`string`):ISO 8601 timestamp when the Note was saved. - **business_number_id** (`string`):The owning business number's public ID. - **business_number_name** (`string`):The owning business number's name. Email uncertainty does not block saving a Note. The captured address remains in `details` even when it cannot populate the contact email. Deleting a Note does not remove details already saved on the contact. --- ## List Notes Retrieve your company's Notes. The response contains `notes` and `unseen_count`, the number of Notes that have not been marked seen. ```bash curl https://app.phone.inc/api/v1/notes \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/notes', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }) const { notes, unseen_count } = await response.json() ``` ```python import os, requests response = requests.get( 'https://app.phone.inc/api/v1/notes', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, ) notes = response.json()['notes'] ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/notes') response = Net::HTTP.get_response(uri, 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY')) notes = JSON.parse(response.body)['notes'] ``` ```json { "notes": [ { "id": "0193f4cb-7777-7c00-9e3d-2b2b8a7f1c33", "type": "note", "text": "Please call Dana back about invoice 1042 tomorrow morning.", "details": { "name": "Dana", "email": null, "reference": "1042", "callback_time": "Tomorrow morning" }, "from": "+14085550199", "call_id": null, "seen_at": null, "created_at": "2026-05-15T14:20:00Z", "business_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "business_number_name": "Sales" } ], "unseen_count": 1 } ``` --- ## Get a Note Retrieve one Note by its public ID. The response is the Note object itself, without a `note` wrapper. ```bash curl https://app.phone.inc/api/v1/notes/0193f4cb-7777-7c00-9e3d-2b2b8a7f1c33 \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch(`https://app.phone.inc/api/v1/notes/${noteId}`, { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }) const note = await response.json() ``` ```python import os, requests response = requests.get( f'https://app.phone.inc/api/v1/notes/{note_id}', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, ) note = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI("https://app.phone.inc/api/v1/notes/#{note_id}") response = Net::HTTP.get_response(uri, 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY')) note = JSON.parse(response.body) ``` ```json { "id": "0193f4cb-7777-7c00-9e3d-2b2b8a7f1c33", "type": "note", "text": "Please call Dana back about invoice 1042 tomorrow morning.", "details": { "name": "Dana", "email": null, "reference": "1042", "callback_time": "Tomorrow morning" }, "from": "+14085550199", "call_id": null, "seen_at": null, "created_at": "2026-05-15T14:20:00Z", "business_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "business_number_name": "Sales" } ``` --- ## Update a Note Mark a Note seen or unseen. This endpoint does not edit its text or collected details. ### Required attributes - **seen** (`boolean`):Send `true` to mark seen or `false` to mark unseen. ```bash curl -X PATCH https://app.phone.inc/api/v1/notes/0193f4cb-7777-7c00-9e3d-2b2b8a7f1c33 \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"seen":true}' ``` ```js const response = await fetch(`https://app.phone.inc/api/v1/notes/${noteId}`, { method: 'PATCH', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ seen: true }), }) const note = await response.json() ``` ```python import os, requests response = requests.patch( f'https://app.phone.inc/api/v1/notes/{note_id}', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, json={'seen': True}, ) note = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI("https://app.phone.inc/api/v1/notes/#{note_id}") request = Net::HTTP::Patch.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = { seen: true }.to_json response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } note = JSON.parse(response.body) ``` ```json { "id": "0193f4cb-7777-7c00-9e3d-2b2b8a7f1c33", "type": "note", "text": "Please call Dana back about invoice 1042 tomorrow morning.", "details": { "name": "Dana", "email": null, "reference": "1042", "callback_time": "Tomorrow morning" }, "from": "+14085550199", "call_id": null, "seen_at": "2026-05-15T14:25:00Z", "created_at": "2026-05-15T14:20:00Z", "business_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "business_number_name": "Sales" } ``` --- ## Delete a Note Delete a Note. Returns `204 No Content` with no response body. The `note.deleted` webhook contains a metadata snapshot with `text: null` and empty `details`, not the deleted content. ```bash curl -X DELETE https://app.phone.inc/api/v1/notes/0193f4cb-7777-7c00-9e3d-2b2b8a7f1c33 \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch(`https://app.phone.inc/api/v1/notes/${noteId}`, { method: 'DELETE', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }) ``` ```python import os, requests response = requests.delete( f'https://app.phone.inc/api/v1/notes/{note_id}', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, ) ``` ```ruby require 'net/http' uri = URI("https://app.phone.inc/api/v1/notes/#{note_id}") request = Net::HTTP::Delete.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } ``` --- # OAuth 2.0 for applications Let customers connect their Phone.inc company to your SaaS without sharing passwords or API keys. This guide covers company-owned, confidential applications: S256 PKCE, resource-specific scopes, and client authentication on your server. Start with [Applications](/applications) for use cases. For your own company's scripts, use an [API key](/api/authentication). Public MCP connectors and existing native or legacy clients use a [separate OAuth reference](/api/oauth-public); their secretless `api` flow is not the registration or authorization flow for company-owned applications. All endpoints below use `https://app.phone.inc`. ## Company-owned SaaS applications Application management is available to every company. If Phone.inc turns it off for your publishing company, that blocks application management and the [application webhook delivery log API](/applications#list-application-webhook-deliveries). Existing OAuth connections and your customers' API access keep working. Phone.inc support can separately suspend an application. Suspension blocks API and MCP access, new authorizations, code exchanges, refreshes, caller-context requests, and queued webhook deliveries. It retains installations and credentials rather than revoking them. Resuming restores access for credentials that remain valid; deliveries skipped during suspension are not replayed automatically. Requests already in flight may finish. Suspension is an internal support control, not a partner API or MCP tool. Sign in with your ordinary Phone.inc company and open [Applications](https://app.phone.inc/applications), alongside API keys. Create a private application at `/applications/new` with a name, description, and exact redirect URIs, one per line. Edit it at `/applications/:id/edit`. No separate partner account or public marketplace is required. Do not register these applications through `/oauth/register`. Redirect URIs must use HTTPS, except HTTP loopback callbacks on `127.0.0.1` or `[::1]`. Register the exact callback, including its port and path; `localhost` and custom schemes are not supported for these apps. Optionally configure an HTTPS `context_endpoint_url` without credentials, a query string, or a fragment. API-only applications do not need a context endpoint. Optionally register `connect_url`, labeled **Connection URL** in the dashboard. This HTTPS URL on your SaaS starts OAuth using your own signed-in user session, state, and fresh S256 PKCE. It is not the OAuth callback URL. Customers can use it to update permissions or reconnect a disconnected app. Changing it alone is metadata and does not disconnect installations. Enable only the [resource-specific scopes](#scopes) your app needs. No scopes are preselected. Every authorization request must ask for a nonempty subset of enabled scopes, including their dependencies. Company-owned applications cannot request `api`, `web`, `api:read`, or `api:write`. Adding `messages:*` permissions requires your publishing company's **Messaging** feature flag, including when creating an application. Disabling that flag does not remove previously enabled permissions or disconnect existing installations. Customers still need their own Messaging flag to use messaging endpoints, and Message attachments to retrieve attachments. Copy the client ID, client secret, and separate context signing secret when shown on creation or rotation. Secrets are shown only once. Keep them server-side in a secret manager, never in browser code, mobile binaries, URLs, or logs. App credential creation, management, rotation, and deletion are interactive dashboard actions, not API or MCP tools. ## Discovery metadata Fetch `https://app.phone.inc/.well-known/oauth-authorization-server` for endpoint URLs, supported grants, S256 PKCE, and client authentication methods. Company-owned apps use `client_secret_basic` or `client_secret_post`, not `none`. The server advertises both public and confidential clients; advertised `api` support does not make that scope available to company-owned apps. Protected-resource discovery is available at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-protected-resource/mcp`. The latter identifies `https://app.phone.inc/mcp`. See the [public-client discovery reference](/api/oauth-public#discovery-metadata) for the shared metadata contract. ## Step 1: Build the authorization URL Generate a fresh random PKCE verifier, its base64url-encoded SHA-256 challenge (without padding), and a random `state`. Store the verifier and state in your server-side session, bound to the signed-in SaaS user and intended tenant. Redirect the customer's browser to `/oauth/authorize` with: | Parameter | Value | | --- | --- | | `response_type` | `code` | | `client_id` | Your application's client ID | | `redirect_uri` | An exact registered callback URI | | `scope` | Space-separated, nonempty subset of enabled resource scopes, including dependencies | | `state` | Fresh random value to validate at the callback | | `code_challenge` | Base64url-encoded SHA-256 of the verifier | | `code_challenge_method` | `S256` | For example, an app enabled for `calls:read` can send the browser to this URL, replacing the state and challenge with freshly generated values: ```text https://app.phone.inc/oauth/authorize?response_type=code&client_id=your_client_id&redirect_uri=https%3A%2F%2Fyour-app.com%2Fcallback&scope=calls%3Aread&state=random_csrf_token&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256 ``` Any authenticated employee in the customer company can approve installation. Consent shows the publisher, application, and requested permissions. Requesting `caller_context:provide` explicitly discloses that caller phone numbers will be sent to your app. No customer company-admin role is required. For an existing installation, consent distinguishes additional permissions, already approved permissions, and previously approved permissions omitted from this request, which will be removed. Request the full desired scope set, including permissions to keep and their dependencies, not just the additions. Approval updates the same installation; cancelling changes nothing. Approval redirects to your callback with `code` and `state`. Denial returns `error=access_denied` and `state` instead. Validate state against the saved session before proceeding, including on error callbacks. Never accept a callback for a different SaaS tenant. ## Step 2: Exchange the code for an access token Exchange the code within 10 minutes at `POST /oauth/token`. Send form-encoded fields and authenticate the confidential client. PKCE is mandatory even with a client secret. Use **one** authentication method per request: HTTP Basic (`client_secret_basic`), or the `client_id` and `client_secret` form fields (`client_secret_post`). The examples below run on your server and use Basic authentication. ```bash curl https://app.phone.inc/oauth/token \ --user "$PHONE_INC_CLIENT_ID:$PHONE_INC_CLIENT_SECRET" \ --data-urlencode grant_type=authorization_code \ --data-urlencode "code=$AUTHORIZATION_CODE" \ --data-urlencode redirect_uri=https://your-app.com/callback \ --data-urlencode "code_verifier=$PKCE_VERIFIER" ``` ```js const response = await fetch('https://app.phone.inc/oauth/token', { method: 'POST', headers: { Authorization: `Basic ${Buffer.from(`${process.env.PHONE_INC_CLIENT_ID}:${process.env.PHONE_INC_CLIENT_SECRET}`).toString('base64')}`, 'Content-Type': 'application/x-www-form-urlencoded', }, body: new URLSearchParams({ grant_type: 'authorization_code', code: codeFromCallback, redirect_uri: 'https://your-app.com/callback', code_verifier: verifierFromSession, }), }) const tokens = await response.json() ``` ```python import os, requests response = requests.post( 'https://app.phone.inc/oauth/token', auth=(os.environ['PHONE_INC_CLIENT_ID'], os.environ['PHONE_INC_CLIENT_SECRET']), data={ 'grant_type': 'authorization_code', 'code': code_from_callback, 'redirect_uri': 'https://your-app.com/callback', 'code_verifier': verifier_from_session, }, ) tokens = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/oauth/token') request = Net::HTTP::Post.new(uri) request.basic_auth(ENV.fetch('PHONE_INC_CLIENT_ID'), ENV.fetch('PHONE_INC_CLIENT_SECRET')) request.set_form_data( grant_type: 'authorization_code', code: code_from_callback, redirect_uri: 'https://your-app.com/callback', code_verifier: verifier_from_session, ) response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } tokens = JSON.parse(response.body) ``` ```json { "access_token": "access_token_value", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "refresh_token_value", "scope": "calls:read", "created_at": 1792584000, "installation_id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc", "company_id": "019daef1-085e-73f0-85f6-a71e2d8dd2cd" } ``` Map `installation_id` to the correct SaaS tenant. It is the installed integration's public UUID; `company_id` is the customer company's public UUID. Repeated authorization updates one installation per company and app, visible on the customer's **Integrations** page. Supplying another `company_id` or `installation_id` to authorization cannot select another tenant. Tokens remain bound to the approved company and installation. ## Step 3: Call the API Send the access token as `Authorization: Bearer ` to the existing `/api/v1/*` endpoints. Resource-page examples use API keys; replace that credential with the installation's OAuth Bearer token. Only granted actions and data are accessible. For the example `calls:read` grant: ```bash curl https://app.phone.inc/api/v1/calls \ -H "Authorization: Bearer $PHONE_INC_ACCESS_TOKEN" ``` Existing [MCP tools](/mcp) can also use partner tokens under the same API permissions. They do not bypass consent or provide app-credential management. ## Refreshing tokens Access tokens last one hour. Refresh tokens are valid for 30 days from issue. Refresh server-side with the current refresh token and confidential client authentication, just as at code exchange: ```bash curl https://app.phone.inc/oauth/token \ --user "$PHONE_INC_CLIENT_ID:$PHONE_INC_CLIENT_SECRET" \ --data-urlencode grant_type=refresh_token \ --data-urlencode "refresh_token=$PHONE_INC_REFRESH_TOKEN" ``` For `client_secret_post`, replace `--user` with form fields `client_id` and `client_secret`. Store the latest returned access and refresh tokens and discard the previous refresh token. Refresh responses contain `scope`, `installation_id`, and `company_id` as at code exchange; refresh cannot change the installation or company binding. If refresh fails because access was disconnected or revoked, start a new authorization flow rather than retrying indefinitely. Existing tokens cannot gain newly enabled or approved scopes, and refresh cannot expand their scope set. To obtain additional permissions, your SaaS must initiate a fresh S256 PKCE authorization requesting the full desired scope set and exchange the resulting code. ## Revoking tokens Send an access or refresh token to `POST /oauth/revoke`, authenticating the confidential client as at code exchange: ```bash curl https://app.phone.inc/oauth/revoke \ --user "$PHONE_INC_CLIENT_ID:$PHONE_INC_CLIENT_SECRET" \ --data-urlencode "token=$PHONE_INC_ACCESS_TOKEN" ``` For `client_secret_post`, send `client_id` and `client_secret` as form fields instead of Basic authentication. Successful revocation returns `200 OK`; unknown tokens also return success per RFC 7009. Missing or invalid client authentication is not a successful revocation. Revoking one of this application's installation tokens revokes the **whole installation**, not just that token. All installation access tokens, refresh tokens, and pending authorization codes are revoked. Caller lookups stop, webhook subscriptions are deleted, and queued deliveries and retries are blocked. An expired access token can still disconnect its installation. Tokens already revoked return success without affecting a later reconnection; use a token from the current connection to disconnect it. ## Disconnect, rotate, and reauthorize Any authenticated employee in the customer company can disconnect the application from **Integrations**. Dashboard disconnect and application deletion have the same installation-wide effect as revocation. Adding enabled application scopes does not disconnect installations, revoke existing tokens, stop caller context, or delete webhooks. It makes additional permissions available for fresh consent, not automatically granted. In **Integrations**, customers see **Additional permissions available** and an **Update permissions** link to the configured Connection URL. Without that URL, the dashboard instructs them to open your SaaS. The dashboard does not itself grant access or expand tokens. Reducing installation permissions through consent, or removing enabled application scopes, revokes only credentials containing removed scopes. Unaffected narrower tokens and installations continue. Removing every installed permission disconnects that installation. Webhook scope ceilings and event lists shrink permanently when permissions are removed; readding a scope cannot restore an old subscription's removed access. Create a new subscription for expanded access. Changing redirect URIs or the context endpoint still disconnects installations and requires fresh consent. Name, description, and Connection URL changes do not. Rotation replaces both the client secret and context signing secret and disconnects installations. Update your server's secrets and ask customers to reauthorize; this is not the overlapping rotate-then-revoke procedure used for API keys. Historical call context remains available after disconnection. Reconnecting cannot resurrect old webhook subscriptions or deliveries; create new subscriptions after consent. See [webhook permissions](/api/webhooks#partner-oauth-permissions). If you configure caller lookup, implement the [signed context request](/api/caller-context#signed-partner-lookups). It uses the separate context signing secret, not the OAuth client secret. ## Scopes Company-owned partner applications use these 25 resource-specific scopes. Every `:write` scope requires its matching `:read` scope in both enabled and requested permissions. `calls:control` also requires `calls:read`. Other scopes have no dependencies: `messages:send` is independent and is not implied by `messages:write`. | Scope | Permission | | --- | --- | | `calls:read` | Read calls, recordings, and transcripts | | `calls:write` | Mark calls read or unread | | `calls:control` | Transfer and control active calls | | `messages:read` | Read text messages | | `messages:write` | Manage text templates and texting settings | | `messages:send` | Send text messages | | `employees:read` | Read employees | | `employees:write` | Manage employees | | `business_numbers:read` | Read business numbers and routing | | `business_numbers:write` | Manage business numbers and routing | | `contacts:read` | Read contacts | | `contacts:write` | Manage contacts | | `voicemails:read` | Read voicemails, recordings, and transcripts | | `voicemails:write` | Manage and delete voicemails | | `notes:read` | Read Notes, including text and collected details | | `notes:write` | Mark Notes seen or unseen and delete Notes | | `departments:read` | Read departments | | `departments:write` | Manage departments | | `company:read` | Read company details | | `company:write` | Update company details | | `integrations:read` | Read installed integrations | | `webhooks:read` | Read this application's webhooks | | `webhooks:write` | Manage this application's webhooks | | `caller_context:read` | Look up caller context | | `caller_context:provide` | Receive caller phone numbers and provide caller context | ### API action permissions Permissions follow explicit API actions, not HTTP methods alone. Unlisted actions are not available to partner OAuth tokens. | API actions | Required scope | | --- | --- | | List and retrieve calls; retrieve active calls | `calls:read` | | Update calls; mark calls seen | `calls:write` and `calls:read` | | Create or cancel transfers; complete transfers | `calls:control` and `calls:read` | | List and retrieve voicemails | `voicemails:read` | | Update or delete voicemails | `voicemails:write` and `voicemails:read` | | List and retrieve Notes | `notes:read` | | Update Note seen state or delete Notes | `notes:write` and `notes:read` | | List and retrieve business numbers | `business_numbers:read` | | Update business numbers and incoming-call, outside-hours, or no-answer routing; create or remove terminations; create porting requests or voice previews | `business_numbers:write` and `business_numbers:read` | | Retrieve texting settings, messages, message attachments, or text snippets; list text snippets | `messages:read` | | Update texting settings; create, update, or delete text snippets | `messages:write` and `messages:read` | | Send business-number messages; retry messages | `messages:send` | | List or retrieve employees, contacts, or departments; retrieve employee do-not-disturb settings | Matching resource `:read` | | Create, update, or delete employees, contacts, or departments; update employee do-not-disturb settings | Matching resource `:write` and `:read` | | Retrieve or update company details | `company:read`, plus `company:write` for updates | | List or retrieve installed integrations | `integrations:read` | | Look up caller context | `caller_context:read` | | List webhooks; list webhook deliveries | `webhooks:read` | | Create, update, or delete webhooks; send a webhook test | `webhooks:write` and `webhooks:read` | | Test partner caller context | `caller_context:provide` | Combined `/api/v1/inbox`, `/api/v1/inbox/:phone/activity`, and `/api/v1/activity/unseen` require at least one of `calls:read`, `voicemails:read`, `notes:read`, or `messages:read`. Rows, latest items, previews, timestamps, unseen counts, and pagination include only granted resource types. Notes do not require the Messaging feature flag. An explicit `sources` filter can narrow access, never expand it; selecting no readable source returns `422`. Contact metadata and text searches require `contacts:read`; phone filters and phone-only queries do not. Marking inbox activity seen requires at least one corresponding `:write` scope with its dependency `:read`, and only marks writable sources. Read-only sources remain untouched. The legacy `/api/v1/calls/seen` endpoint checks call and voicemail write permissions separately: `calls:write` cannot alter voicemail seen state. ### Response fields and outbound delivery `calls:read` includes each call's recordings, transcriptions, summaries, and search. `voicemails:read` includes voicemail recordings and transcriptions. `notes:read` includes Note text and collected details. `messages:read` includes text content and attachment metadata and download links when both Messaging and Message attachments are enabled for the customer. These permissions also apply to embedded content; there is no independent content scope. Reference IDs remain available, but embedded employee, contact, department, and business-number details require `employees:read`, `contacts:read`, `departments:read`, and `business_numbers:read`, respectively. This includes business-number names, numbers, and formatted-number fields. `caller_context:provide` alone is a valid context-only installation and requires an app context endpoint. Phone.inc sends caller phone numbers only when that installation grants `caller_context:provide`. `caller_context:read` permits the lookup API, not outbound phone-number delivery. See [signed partner lookups](/api/caller-context#signed-partner-lookups). Webhook subscriptions belong to the creating installation and retain a granted-scope ceiling that can shrink but never expand. Events require only the event resource's read scope: call transcript and summary events need `calls:read`; voicemail transcript events need `voicemails:read`; `note.created` and `note.deleted` need `notes:read`. Payloads redact ungranted embedded data. Subscriptions never silently gain permissions. See [webhook permissions](/api/webhooks#partner-oauth-permissions). Integration setup actions (`integration_setups`) are dashboard-only for partner OAuth and are not granted by `integrations:read`. Ordinary installed-integration reads remain available. App credential management is also dashboard-only and excluded from MCP; no tool names or counts change. Legacy `api` access for older clients and public MCP clients, first-party `api`/`web` behavior, and API keys remain compatible. These restrictions do not change API-key permissions. `web` remains reserved for first-party browser sessions. Use the [public and legacy reference](/api/oauth-public) when maintaining those clients; do not use its secretless examples for company-owned applications. ## Error responses OAuth endpoints return the standard OAuth error shape: ```json { "error": "invalid_grant", "error_description": "The provided authorization grant is invalid, expired, revoked, or does not match the redirection URI." } ``` | Error | Meaning | | --- | --- | | `invalid_request` | Required parameter missing, malformed, or repeated | | `invalid_client` | Unknown client or missing/invalid confidential client authentication | | `invalid_grant` | Code or refresh token invalid, expired, revoked, or already used | | `invalid_scope` | Scope unknown, not enabled, or missing required dependencies | | `unauthorized_client` | Client not authorized for this grant type | | `access_denied` | User denied consent; returned as a callback parameter | An invalid, expired, or revoked API token returns `401`. Refresh an expired token and retry once. If the installation is disconnected, obtain fresh consent. A suspended application receives `401` for API/MCP access and `invalid_client` on new authorization attempts; code exchanges and refreshes return `invalid_grant`. Contact support rather than repeatedly retrying. Do not retry permission errors by requesting unrelated data. ## Security checklist - Use fresh S256 PKCE and state for every authorization; validate state before exchanging the code. - Authenticate the client at code exchange, refresh, and revocation. PKCE does not replace client authentication. - Keep client secrets, signing secrets, and tokens server-side. The client ID is not a secret. - Bind callbacks and installation IDs to the intended SaaS tenant; keep each customer's tokens isolated. - Request only enabled resource scopes and their dependencies. - Provide a disconnect and reauthorization path; revocation affects the entire installation. --- # Public and legacy OAuth clients This reference covers dynamically registered MCP connectors and existing public native and legacy OAuth clients. They use authorization code flow with S256 PKCE. Public clients have no embedded client secret; hosted connectors can register with a server-side client secret. Building a SaaS that customer companies install? Use [Applications](/applications) and the [confidential company-app guide](/api/oauth) instead. Dashboard-created applications require resource-specific scopes and server-side client authentication; the secretless `api` examples here do not apply to them. The existing public-client `api` scope and first-party `api`/`web` behavior remain compatible. `web` is reserved for first-party browser sessions, not dynamically registered clients. API keys keep their existing permissions. See [MCP](/mcp) for connector setup and available tools. ## Discovery metadata Fetch these JSON documents from the Phone.inc origin (`https://app.phone.inc` in production), not your own application's origin: - `GET /.well-known/oauth-authorization-server` — issuer, authorization, token, revocation, and registration endpoints; supported response types, grants, PKCE methods, client authentication methods, and scopes. - `GET /.well-known/oauth-protected-resource` — the root resource identifier, linked authorization server, Bearer methods, and scopes. - `GET /.well-known/oauth-protected-resource/mcp` — the same protected-resource metadata for `resource: https://app.phone.inc/mcp`. The issuer matches the host called. The root protected resource uses that host as `resource`; the MCP document includes `/mcp`. Authorization-server metadata advertises `response_types_supported: ["code"]`, `grant_types_supported: ["authorization_code", "refresh_token"]`, and `code_challenge_methods_supported: ["S256"]`. Client authentication methods are `none`, `client_secret_basic`, and `client_secret_post`. Protected-resource documents advertise `bearer_methods_supported: ["header"]`. The MCP document's `scopes_supported` is `["api"]`, the only scope dynamically registered clients receive, so MCP clients that request every advertised scope can authorize. The authorization-server and root protected-resource documents list `api` and the [25 company-app scopes](/api/oauth#scopes); company-owned apps request their enabled resource scopes. ## Register an OAuth client `POST /oauth/register` implements RFC 7591 dynamic registration for MCP connectors. Send JSON. The following example registers a public client: ```bash curl https://app.phone.inc/oauth/register \ -H "Content-Type: application/json" \ -d '{"client_name":"My MCP connector","redirect_uris":["http://127.0.0.1:8765/callback"],"token_endpoint_auth_method":"none"}' ``` ```js const response = await fetch('https://app.phone.inc/oauth/register', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ client_name: 'My MCP connector', redirect_uris: ['http://127.0.0.1:8765/callback'], token_endpoint_auth_method: 'none', }), }) const client = await response.json() ``` ```python import requests client = requests.post('https://app.phone.inc/oauth/register', json={ 'client_name': 'My MCP connector', 'redirect_uris': ['http://127.0.0.1:8765/callback'], 'token_endpoint_auth_method': 'none', }).json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/oauth/register') response = Net::HTTP.post(uri, { client_name: 'My MCP connector', redirect_uris: ['http://127.0.0.1:8765/callback'], token_endpoint_auth_method: 'none', }.to_json, 'Content-Type' => 'application/json') client = JSON.parse(response.body) ``` ```json { "client_id": "a1b2c3d4e5f6g7h8i9j0", "client_id_issued_at": 1730895600, "redirect_uris": ["http://127.0.0.1:8765/callback"], "token_endpoint_auth_method": "none", "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"], "client_name": "My MCP connector", "scope": "api" } ``` Dynamically registered clients are always scoped to `api` and show consent. Dynamic registration does not create a company-owned SaaS application or grant first-party privileges. Choose `token_endpoint_auth_method` according to where the client runs: - `none` creates a public client without a `client_secret`. For compatibility with existing clients, omitting the method also selects `none`; send it explicitly in new integrations. - `client_secret_basic` or `client_secret_post` creates a confidential client for a hosted connector. The response echoes the selected method and includes a generated `client_secret` and `client_secret_expires_at: 0` (no scheduled expiry). Store the secret securely on your server. Phone.inc stores only its hash and sends registration responses with `Cache-Control: no-store`. Confidential clients must authenticate code exchange, refresh, and revocation requests using their secret. The registration response echoes the requested method, but does not restrict the client to that transport: both HTTP Basic and `client_id`/`client_secret` form fields are accepted for either confidential registration. Use only one method per request. Both require the same valid secret; neither permits secretless authentication. S256 PKCE is required in addition to the secret for code exchange. Existing public registrations remain public; adding support for confidential registration does not change their credentials. Register exact redirect URIs. HTTPS callbacks and loopback HTTP on `127.0.0.1`, `localhost`, or `[::1]` with any port are supported. Custom schemes are not accepted by dynamic registration; they are only available to manually registered first-party native clients. These rules differ from [company-owned application callbacks](/api/oauth#company-owned-saas-applications), which do not accept `localhost`. ## Authorize with PKCE Generate a fresh random verifier and state for each request. The challenge is base64url-encoded SHA-256 of the verifier, without padding. Keep the verifier and state securely until the callback. Open this authorization URL in the user's browser, substituting your registered client ID, exact callback, and freshly generated state and challenge: ```text https://app.phone.inc/oauth/authorize?response_type=code&client_id=your_client_id&redirect_uri=http%3A%2F%2F127.0.0.1%3A8765%2Fcallback&scope=api&state=random_csrf_token&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256 ``` All public clients and dynamically registered confidential clients require PKCE with `code_challenge_method=S256`. The user signs in and approves access on behalf of the authenticated employee. The callback includes `code` and `state`, or `error=access_denied` and `state` on denial. Validate state before exchanging the code. ## Exchange the code Within 10 minutes, send form-encoded fields to `/oauth/token`. The redirect URI must match the authorization request exactly. Public clients send their client ID and verifier without a client secret: ```bash curl https://app.phone.inc/oauth/token \ --data-urlencode grant_type=authorization_code \ --data-urlencode "client_id=$PHONE_INC_CLIENT_ID" \ --data-urlencode "code=$AUTHORIZATION_CODE" \ --data-urlencode redirect_uri=http://127.0.0.1:8765/callback \ --data-urlencode "code_verifier=$PKCE_VERIFIER" ``` ```json { "access_token": "access_token_value", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "refresh_token_value", "scope": "api", "created_at": 1730895600 } ``` ## Use and refresh tokens Send `Authorization: Bearer ` to `/api/v1/*` or the [MCP endpoint](/mcp). Tokens act on behalf of the authorizing employee. Access tokens last one hour; refresh tokens are valid for 30 days from issue. Store tokens in secure platform storage, never in source code or browser `localStorage`. Public clients refresh without a secret: ```bash curl https://app.phone.inc/oauth/token \ --data-urlencode grant_type=refresh_token \ --data-urlencode "client_id=$PHONE_INC_CLIENT_ID" \ --data-urlencode "refresh_token=$PHONE_INC_REFRESH_TOKEN" ``` Confidential clients authenticate with their secret, for example using HTTP Basic: ```bash curl https://app.phone.inc/oauth/token \ --user "$PHONE_INC_CLIENT_ID:$PHONE_INC_CLIENT_SECRET" \ --data-urlencode grant_type=refresh_token \ --data-urlencode "refresh_token=$PHONE_INC_REFRESH_TOKEN" ``` The response has the same token fields as code exchange. Store the newly issued refresh token and discard the previous one. The previous refresh token is invalidated when the new access token is first used on an authenticated API or MCP request, not immediately when the refresh response is issued. An invalid, expired, or revoked API token returns `401`; refresh and retry once, or restart authorization if refresh fails. OAuth endpoint errors use `error` and `error_description`; see [OAuth errors](/api/oauth#error-responses). ## Revoke a token Public clients send their client ID: ```bash curl https://app.phone.inc/oauth/revoke \ --data-urlencode "client_id=$PHONE_INC_CLIENT_ID" \ --data-urlencode "token=$PHONE_INC_ACCESS_TOKEN" ``` Confidential clients also authenticate with their secret: ```bash curl https://app.phone.inc/oauth/revoke \ --user "$PHONE_INC_CLIENT_ID:$PHONE_INC_CLIENT_SECRET" \ --data-urlencode "token=$PHONE_INC_ACCESS_TOKEN" ``` Send an access or refresh token. Successful revocation returns `200 OK`, including for unknown tokens, per RFC 7009. Do not apply the confidential company-app installation lifecycle to public clients; [company-app revocation](/api/oauth#revoking-tokens) requires client authentication and disconnects the whole installation. ## First-party native compatibility Native builds installed side by side should use distinct callback schemes and register each exact redirect URI with their client. Standard Phone.inc mobile builds keep `phoneinc://oauth/callback`. Android previews use `inc.phone.preview.pr://oauth/callback`, accepted only for our first-party public mobile client. These custom schemes are not accepted by dynamic registration or company-owned applications. Token exchange must use the same redirect URI as authorization. Android preview exchanges require an exact string match, including rejecting added query parameters. First-party clients retain their existing consent behavior; dynamic registration cannot opt a client into first-party status. --- # Quickstart This guide gets you from zero to your first authenticated API request. We'll create an API key, list the business numbers on your account, and point you at the resource pages once you're up and running. All endpoints live under `https://app.phone.inc/api/v1`. Every request must include an API key. If you don't have one yet, the next section walks you through creating one. Building a multi-tenant integration instead? See [OAuth 2.0 for applications](/api/oauth). ## Create an API key 1. Sign in to your Phone.inc dashboard at [https://app.phone.inc](https://app.phone.inc). 2. Open **Your account → API Keys**, or go directly to [https://app.phone.inc/api_keys](https://app.phone.inc/api_keys). 3. Click **Create API key**, name it (e.g. `Local development`), and copy the token. It's shown to you exactly once — store it somewhere safe. Tokens look like `phk_a1B2c3D4e5F6g7H8j9K1m2N3p4Q5r6S7`. Set it as an environment variable so you can paste the snippets below directly: ```bash export PHONE_INC_API_KEY="phk_a1B2c3D4e5F6g7H8j9K1m2N3p4Q5r6S7" ``` For the full key lifecycle — rotation, revocation, security — see [Authentication](/api/authentication). ## Make your first request Hit the `business_numbers` endpoint to fetch every phone number on your account. It's the simplest call and a good way to confirm your key works. ```bash curl https://app.phone.inc/api/v1/business_numbers \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/business_numbers', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }) const { business_numbers: businessNumbers } = await response.json() console.log(businessNumbers) ``` ```python import os, requests response = requests.get( "https://app.phone.inc/api/v1/business_numbers", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) print(response.json()["business_numbers"]) ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/business_numbers') response = Net::HTTP.get_response( uri, { 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY') }, ) puts JSON.parse(response.body)['business_numbers'] ``` You'll get back something like: ```json { "business_numbers": [ { "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "name": "Sales", "number": "+14155551234", "number_formatted": "+1 415-555-1234" }, { "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c02", "name": "Support", "number": "+14155555678", "number_formatted": "+1 415-555-5678" } ] } ``` If you see a `401 Invalid API key`, double-check the value of `$PHONE_INC_API_KEY` and confirm the key still exists at [app.phone.inc/api_keys](https://app.phone.inc/api_keys). ## Where to go next You're authenticated and the API is responding. Pick what you need: - **[Business numbers](/api/business-numbers)** — list the phone numbers on your account. - **[Calls](/api/calls)** — list and inspect inbound and outbound calls, filter by phone number, direction, or state. - **[Voicemails](/api/voicemails)** — fetch voicemail recordings and mark them as listened. - **[Caller context](/api/caller-context)** — look up customer context (Shopify orders today) for an inbound caller. When something goes wrong, check the [Errors](/api/errors) page for the response shape and how to handle it. --- # Receptionists Beta Create an AI receptionist that answers business questions, takes written messages, and connects callers with your team. A receptionist belongs to your company and can serve several business numbers. Create it here, then select its ID in a [business-number call flow](/api/business-numbers#receptionists). ## The receptionist model - **id** (`string`):Stable public UUID. Use this as `ai_receptionist_id` when configuring a number's routing. - **name** (`string`):Required when creating. A nonblank name of up to 100 characters. - **language** (`string`):One of the 32 [supported language codes](#supported-languages). Defaults to `da` when creating. The same primary caller language applies to every number using this receptionist. - **voice_id** (`string`):Optional when creating or updating. An ElevenLabs voice ID from the [shared voice catalog](#voices). Defaults to Simon. Omitting it on update preserves the selected voice. - **configuration** (`object`):The receptionist's greeting, business knowledge, permitted transfer destinations, and optional message-taking settings. See [Configuration](#configuration). - **lock_version** (`integer`):Read the current value and send it with every update. A missing or stale value returns `422`. - **knowledge_index** (`object or null`):Website import status, or `null` when no website is configured. See [Retrieve the knowledge index](#retrieve-the-knowledge-index). All endpoints use [API-key authentication](/api/authentication) or an authorized [OAuth token](/api/oauth) and are scoped to the authenticated company. Unknown or foreign IDs return `404`. The dashboard manages the same resources on the **Receptionists** page. These operations are also available through [MCP](/mcp). ## Supported languages Receptionists and business numbers offer the same 32 language choices: | Language | Code | Language | Code | | --- | --- | --- | --- | | Arabic | `ar` | Bulgarian | `bg` | | Croatian | `hr` | Czech | `cs` | | Danish | `da` | Dutch | `nl` | | English | `en` | Filipino | `fil` | | Finnish | `fi` | French | `fr` | | German | `de` | Greek | `el` | | Hindi | `hi` | Hungarian | `hu` | | Indonesian | `id` | Italian | `it` | | Japanese | `ja` | Korean | `ko` | | Malay | `ms` | Mandarin Chinese | `zh` | | Norwegian | `no` | Polish | `pl` | | Portuguese | `pt` | Romanian | `ro` | | Russian | `ru` | Slovak | `sk` | | Spanish | `es` | Swedish | `sv` | | Tamil | `ta` | Turkish | `tr` | | Ukrainian | `uk` | Vietnamese | `vi` | Choose one primary language per receptionist. Calls do not automatically switch languages. Write `configuration.opening_text` in that language. Changing the language in the dashboard, API, MCP or Ping does not translate or change your greeting. Have a native speaker review greetings and business information before use. Private employee introductions use the receptionist's language and voice from the revision captured when the call starts. For example, an English-speaking receptionist on a Danish number introduces calls to employees in English. Updating the receptionist does not change calls already in progress. The business number's `language` controls number greetings and other number messages, not receptionist introductions. Changing a number's language does not translate saved greeting text. Recorded-call and voicemail transcription detect the spoken language automatically; these settings do not translate transcripts. Voice quality and accents vary by language. Receptionists remain in beta. ## Voices Receptionists use the same voice names and picker as business-number greetings: | Voice | ID | Style | | --- | --- | --- | | Mark | `gs0tAILXbY5DNrJrsM6F` | Energetic and informative | | Simon | `KH1SQLVulwP6uG4O3nmT` | Casual and friendly, the default | | Ellen | `BIvP0GN1cAtSRTxNHnWS` | Friendly and conversational | | Sarah | `aMSt68OGf4xUZAnLpTU8` | Clear and professional | Send `voice_id` alongside `name` or `language`, not inside `configuration`. All four voices can be selected with any of the 32 supported languages. Voice and language changes leave `opening_text` unchanged. Write the greeting in the chosen language and review pronunciation with a native speaker. The dashboard plays your current greeting with the selected voice. For the four catalog voices, previews and Custom/legacy agents use `eleven_v4`. Realtime Max and Mini keep the selected voice and language, but ElevenLabs manages their speech model, so calls can sound different from previews. Realtime availability depends on the ElevenLabs workspace and its compliance and data-residency settings. Preview synthesis follows the greeting text's language rather than translating it. Provider availability and pronunciation quality are not guaranteed for every voice-language combination. Preview generation is an interactive dashboard action, not an MCP or Ping tool. Existing receptionists receive Simon as their selected setting when the database migration runs. The migration does not contact ElevenLabs. Saving a receptionist or explicitly deploying it from **Admin → Receptionist models** prepares and verifies a replacement agent with that voice. A pending voice update can be deployed even when the target model already matches. Current calls retain their published revision. Restoring a revision restores its saved voice, language and configuration too; older revisions can restore a legacy voice. Legacy voices use `eleven_v4_turbo` for Custom agents, rather than the `eleven_v3` model used for their standalone previews. ## Access and pricing Receptionists require Pro regardless of the `pro_feature_gates` rollout flag, except for companies internally marked as test companies. Test companies can use receptionists without a subscription; this does not grant other Pro entitlements. Active, trialing and past-due subscriptions retain Pro access. Other Free companies see an upgrade prompt; receptionist API and MCP access and AI call execution are unavailable. AI usage costs $0.29 USD per minute, billed by connected seconds, in addition to the Pro subscription and any phone charges. AI usage is not covered by included local calling hours and is not rounded up to whole minutes. Prices exclude tax. Creating a receptionist automatically queues the AI usage item for the company's active USD subscription. Existing receptionists are also checked when subscriptions change. Trial accounts gain the usage item when their subscription becomes active. Billing requires the deployment's `STRIPE_AI_METERED_PRICE_ID`; calls before the usage item was added are not billed retroactively. No company feature flag or environment switch is required. External AI credentials are still required to provision agents and handle calls. For other Free companies, receptionist API endpoints return `404`, new AI routing is rejected, and runtime sessions and tool callbacks are blocked. Existing saved configurations are retained, not deleted. Business-number API responses still identify a saved `AiAgentConfig` routing type but omit its receptionist ID and configuration while access is unavailable. Its `expected_revision_id` and corresponding `call_flow_revision_ids` entry are `null`, so the saved AI revision identifier is not exposed. Calls attempting an unavailable AI destination use the existing failure/fallback path. ## Configuration - **schema_version** (`integer`):Required. Must be `1`. - **opening_text** (`string`):Required. Between 1 and 1,000 characters after trimming. Dynamic-variable templates are not allowed. This changes only the first spoken message; Phone.inc controls the instructions and model. Choose the voice separately with `voice_id`. Your company is responsible for any required disclosure. - **transfer_targets** (`array`):Optional. Up to ten unique active employees from the same company. Each entry has an `employee_id` and a `description` of 1–300 characters explaining when to transfer to them. - **department_ids** (`array`):Optional. Up to ten unique company department UUIDs. These permit transfers into shared department queues, not employee warm transfers. See [Departments](/api/departments). - **knowledge** (`object`):Optional business context, Q&As, exact-page imports and an automatically indexed website. See [Business knowledge](#business-knowledge). - **message_taking** (`object`):Optional. Message taking starts disabled. Set `enabled` and the `fields` to collect. See [Messages and transfers](#messages-and-transfers). - **tone** (`string`):Optional. `friendly_professional` (the default) uses warm, courteous conversation; `formal_direct` uses neutral, businesslike sentences without small talk; `fun_light` uses upbeat, relaxed wording with restrained playfulness when appropriate. Tone changes wording independently of the selected voice. All tones stay calm and straightforward for complaints, distress, sensitive information and private transfer introductions. Phone.inc safety, privacy, language and tool rules always take priority. The configured opening text is unchanged. Configuration updates replace the entire object, not individual nested fields. Retrieve it first and preserve settings you want to keep. Omitting `configuration` from an update preserves it. Unknown configuration keys are rejected. Portraits, receptionist integration grants and remote MCP-server connections are unavailable. Saving a receptionist creates and validates its ElevenLabs agent, even before it is assigned to a business number. Configuration, imported page content or language changes prepare one replacement immutable version shared by all linked flows, then activate it atomically. A preparation or persistence failure leaves the saved receptionist and previous flows unchanged. Current calls keep their captured version, permissions and usage, except that removed integration tools remain blocked. Renaming does not itself reprovision the voice agent, except when publishing updated system instructions. Existing agents and live sessions remain intact through migration; linked legacy flows converge on one version when the receptionist is next saved. ## List receptionists Returns all company receptionists as a JSON array, ordered by name and ID. There is no pagination wrapper. ```bash curl https://app.phone.inc/api/v1/receptionists -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js await fetch('https://app.phone.inc/api/v1/receptionists', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }) ``` ```python requests.get('https://app.phone.inc/api/v1/receptionists', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}) ``` ```ruby uri = URI('https://app.phone.inc/api/v1/receptionists') request = Net::HTTP::Get.new(uri, 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY')) Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } ``` ```json [ { "id": "01a00000-0000-7000-8000-000000000003", "name": "Customer support", "language": "en", "voice_id": "KH1SQLVulwP6uG4O3nmT", "configuration": { "schema_version": 1, "opening_text": "Hello, you are speaking with our AI assistant. How can I help?" }, "lock_version": 1, "knowledge_index": null } ] ``` --- ## Create a receptionist Send `name`, a valid `configuration`, and optionally `language` and `voice_id`. Creation publishes the voice agent and returns the receptionist with status `201`. It does not assign the receptionist to a number. Use the returned ID in a [routing slot](/api/business-numbers#receptionists). Invalid attributes or provider preparation failures return `422`. ```bash curl https://app.phone.inc/api/v1/receptionists \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"name":"Customer support","language":"en","configuration":{"schema_version":1,"opening_text":"Hello, you are speaking with our AI assistant. How can I help?"}}' ``` ```js await fetch('https://app.phone.inc/api/v1/receptionists', { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Customer support', language: 'en', configuration: { schema_version: 1, opening_text: 'Hello, you are speaking with our AI assistant. How can I help?' } }), }) ``` ```python requests.post('https://app.phone.inc/api/v1/receptionists', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, json={'name': 'Customer support', 'language': 'en', 'configuration': {'schema_version': 1, 'opening_text': 'Hello, you are speaking with our AI assistant. How can I help?'}}) ``` ```ruby uri = URI('https://app.phone.inc/api/v1/receptionists') request = Net::HTTP::Post.new(uri, 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY'), 'Content-Type' => 'application/json') request.body = { name: 'Customer support', language: 'en', configuration: { schema_version: 1, opening_text: 'Hello, you are speaking with our AI assistant. How can I help?' } }.to_json Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } ``` ```json { "id": "01a00000-0000-7000-8000-000000000003", "name": "Customer support", "language": "en", "voice_id": "KH1SQLVulwP6uG4O3nmT", "configuration": { "schema_version": 1, "opening_text": "Hello, you are speaking with our AI assistant. How can I help?" }, "lock_version": 1, "knowledge_index": null } ``` --- ## Retrieve a receptionist Returns one receptionist. Read its `lock_version` before updating and its full configuration before replacing configuration settings. ```bash curl https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003 -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js await fetch('https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }) ``` ```python requests.get('https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}) ``` ```ruby uri = URI('https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003') request = Net::HTTP::Get.new(uri, 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY')) Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } ``` ```json { "id": "01a00000-0000-7000-8000-000000000003", "name": "Customer support", "language": "en", "voice_id": "KH1SQLVulwP6uG4O3nmT", "configuration": { "schema_version": 1, "opening_text": "Hello, you are speaking with our AI assistant. How can I help?" }, "lock_version": 1, "knowledge_index": null } ``` --- ## Update a receptionist Send the current `lock_version` and any of `name`, `language`, `voice_id` or `configuration`. Voice changes publish a replacement agent using the currently selected model. Admin model deployments retain the selected voice. The example renames the receptionist without replacing its configuration. Use the `lock_version` returned by your own retrieve request, not the illustrative value below. Returns the updated receptionist. Missing or stale versions, validation failures, and provider preparation failures return `422`. If a linked call flow changes while the agent is being prepared, the update also fails without replacing the previous version. Reload before retrying. ```bash curl -X PATCH https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003 \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"name":"Support team","lock_version":1}' ``` ```js await fetch('https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003', { method: 'PATCH', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Support team', lock_version: 1 }) }) ``` ```python requests.patch('https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, json={'name': 'Support team', 'lock_version': 1}) ``` ```ruby uri = URI('https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003') request = Net::HTTP::Patch.new(uri, 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY'), 'Content-Type' => 'application/json') request.body = { name: 'Support team', lock_version: 1 }.to_json Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } ``` ```json { "id": "01a00000-0000-7000-8000-000000000003", "name": "Support team", "language": "en", "voice_id": "KH1SQLVulwP6uG4O3nmT", "configuration": { "schema_version": 1, "opening_text": "Hello, you are speaking with our AI assistant. How can I help?" }, "lock_version": 2, "knowledge_index": null } ``` --- ## Delete a receptionist Returns `204` with no body. Remove the receptionist from every business-number call flow before deleting it. An assigned receptionist returns `422`. Historical call and revision records are preserved. ```bash curl -X DELETE https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003 -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js await fetch('https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003', { method: 'DELETE', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }) ``` ```python requests.delete('https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}) ``` ```ruby uri = URI('https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003') request = Net::HTTP::Delete.new(uri, 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY')) Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } ``` --- ## Retrieve the knowledge index Returns `{ "knowledge_index": null }` when no website is configured. Otherwise `knowledge_index` contains `status` (`queued`, `crawling`, `ready` or `failed`), `page_count`, `last_updated_at`, `next_refresh_at` and `retry_at`. Timestamps are ISO 8601 strings or `null`. This same object appears on receptionist responses. ```bash curl https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003/knowledge -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js await fetch('https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003/knowledge', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }) ``` ```python requests.get('https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003/knowledge', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}) ``` ```ruby uri = URI('https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003/knowledge') request = Net::HTTP::Get.new(uri, 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY')) Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } ``` ```json { "knowledge_index": { "status": "ready", "page_count": 12, "last_updated_at": "2026-11-09T09:00:00Z", "next_refresh_at": "2026-11-10T09:00:00Z", "retry_at": null } } ``` --- ## Refresh the knowledge index Queues a manual website refresh and returns `202` with the knowledge-index object. No request body is required. First save a public website as `configuration.knowledge.website_url`; no configured website returns `422`. Requests during an active import reuse it and return `202`. Otherwise, requests within five minutes of the previous refresh request return `429`. This endpoint also has a company-wide limit of ten requests per minute. Use `retry_at` to find when the five-minute refresh interval ends. A `202` response means the import was accepted, not that indexing has completed; retrieve the index to check its status. ```bash curl -X POST https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003/knowledge -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js await fetch('https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003/knowledge', { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }) ``` ```python requests.post('https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003/knowledge', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}) ``` ```ruby uri = URI('https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003/knowledge') request = Net::HTTP::Post.new(uri, 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY')) Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } ``` ```json { "knowledge_index": { "status": "queued", "page_count": 12, "last_updated_at": "2026-11-09T09:00:00Z", "next_refresh_at": null, "retry_at": "2026-11-09T10:05:00Z" } } ``` ## Business knowledge The optional `configuration.knowledge` object is supported by the dashboard, REST API, MCP and the in-app assistant. It contains optional `context` (up to 5,000 characters), `website_url` (one website for automatic crawling), `urls` (up to five unique exact-page URLs), and `questions` (up to twenty objects with a nonblank `question` of up to 300 characters and `answer` of up to 2,000 characters). Send an empty `knowledge` object to clear it while preserving the other fields in your complete configuration. Dynamic-variable templates are not allowed in employee-entered knowledge. For example, use this as `configuration.knowledge` inside a complete configuration: ```json { "context": "We repair bicycles and sell spare parts in Copenhagen.", "urls": ["https://yourbusiness.com/services", "https://yourbusiness.com/returns"], "questions": [ { "question": "Where can I park?", "answer": "There is free parking behind our building." } ] } ``` Each save fetches the exact `urls` and snapshots their readable text into the immutable agent version. Save again to refresh these imported pages; unchanged page text reuses the version. These exact-page imports do not execute JavaScript or crawl links. URLs must use public HTTPS on port 443 without credentials, query strings or fragments. Requests reject redirects, private/reserved DNS addresses and compressed responses; connections are pinned to verified public addresses. Each page has a five-second timeout, 256 KiB response limit and 10,000-character text limit. The complete prompt knowledge snapshot, including JSON structure, is limited to 40,000 characters. An unreadable, oversized or unavailable exact page rejects the save with `422`, preserving the published agent and linked flows. Context, Q&As and exact-page imports are encrypted with the receptionist configuration and revision snapshot, redacted from request logs and supplied as bounded reference text in the agent prompt. Q&As take priority over context and website content. All imported content remains untrusted: it cannot grant tool permissions or override Phone.inc's instructions. Do not include secrets or unnecessary personal data. Knowledge increases the model's context and may increase provider usage. Existing calls keep their prior prompt knowledge snapshot. ### Automatically indexed website Set `configuration.knowledge.website_url` to a public HTTPS URL without credentials, query or fragment. Saving queues a Cloudflare Browser Run crawl with JavaScript rendering, sitemap and link discovery, limited to 100 pages on the configured hostname. A verified HTTPS redirect between that host and its `www` alias is accepted, with source links normalized to the redirected hostname. Redirect verification checks public DNS addresses and pins the connection to a verified address. External sites, other subdomains, account/cart/checkout/login paths and query-string URLs are excluded. Robots and content-use restrictions apply; bot protection may prevent importing a site. This is a bounded crawl, not a guarantee of complete website coverage. Existing `urls` never silently opt into crawling. Public website text and document IDs are cached as unencrypted JSON in Rails. Source URLs and crawl identifiers remain encrypted. Text is chunked into an isolated turbopuffer namespace per receptionist, separate from private call/contact search. Up to 100,000 characters per page and 4 MiB of cached page data are accepted. Only changed content is re-embedded. A complete index is published atomically; partial writes are never searchable. Pages confirmed as HTTP `404`/`410` or disallowed are removed. Missing crawl records are not proof of deletion. Temporary errors preserve the last successful index. Removing the website revokes retrieval immediately and queues external index deletion. Changing the website does not serve the old site's index while the new import is pending. Successful imports refresh after 24 hours, checked every 15 minutes. Failures retry with exponential backoff from 15 minutes to 24 hours; imports time out locally after 30 minutes. Use the [knowledge-index endpoints](#retrieve-the-knowledge-index) to check status or request a refresh. Agents published with a website expose `phone_inc_knowledge_search`, a read-only tool accepting only a `query` of 1–500 characters. The authenticated session determines the company and receptionist. It returns at most three source-linked passages within an 8 KiB result budget, or an explicit unavailable response on failure. The current index is read on every search, so successful background refreshes reach active calls without republishing voice agents. Removing or changing the website revokes the old source even on active calls. Searches use the existing encrypted audit trail. Retrieved content and search relevance are not authority; agents must not obey page instructions or invent answers from irrelevant results. Opening hours still come from the live business-hours tool. Operators must configure `CLOUDFLARE_BROWSER_RUN_ACCOUNT_ID`, `CLOUDFLARE_BROWSER_RUN_API_TOKEN` (Browser Run Edit permission), and the existing `TURBOPUFFER_API_KEY`/region configuration in the backend and job worker. No customer credentials or browser cookies are forwarded. Cloudflare retains crawl results for 14 days; indexed public website text is also sent to turbopuffer's configured embedding provider. Review these processors and content permissions before enabling website imports. Crawling, embeddings and retrieval incur provider costs. ## Messages and transfers Enable conversational message taking with `configuration.message_taking`. It defaults to disabled: ```json { "enabled": true, "fields": ["name", "email", "company_name", "reference", "callback_time"] } ``` The agent asks briefly for selected fields, then saves a Note without requiring a full readback or explicit confirmation. Callers may decline or finish without all details; selected but unavailable values are stored as `null`, and unselected fields are omitted. Email uncertainty never blocks a save: the agent may ask one short clarification but does not repeatedly validate or spell back an address. Spacing in valid email addresses is normalized; uncertain addresses remain in the Note's `details` for the team but do not populate a contact's email. `reference` is an order, booking, or customer reference; `callback_time` is the caller's preferred time as stated, not a promise. The incoming caller number is used automatically, with no callback-number question. Name, syntactically valid email and company fill only blank contact fields in the same company. The action is labeled **Take a note**. Notes appear in the inbox and [Notes API](/api/notes), without a recording. Each employee has a separate Note email notification setting for each business number, enabled by default and independent of voicemail email preferences. Notes also support inbox activity and [webhooks](/api/webhooks); no additional delivery channels are introduced. Disabling the tool revokes new saves on active calls too. Saving a Note does not end the conversation or change the number's whole-call recording settings. Updated conversation instructions apply when a receptionist is saved and its agent version is republished; existing calls keep their captured version. Phone.inc supplies the selected employees' names alongside their IDs and routing descriptions, so callers can ask for a person by first or full name. The agent is instructed to clarify ambiguous names. Names come from employee records, not configuration arguments, and are captured when publishing an agent version. Reselecting a receptionist only reuses its published version; changing transfer targets or their descriptions publishes a refreshed directory. The agent can check live availability for those selected employees: available, on another call, do not disturb, ringing, offline, or unknown. It is instructed to check when a caller asks for someone and before offering a transfer, explain unavailability, and offer an alternative or a message. It does not receive details about other callers. AI transfers respect DND and recheck availability after preparing the private introduction, immediately before requesting ringing. Deliberate human-to-human transfers retain their existing DND policy. Warm transfers contact only selected employees, never repeat a target, and return to the caller between attempts. When transfers are exhausted, the receptionist can offer a written message only if message taking is enabled. Department transfers join a shared queue rather than guaranteeing an answer. Ordinary call-flow voicemail remains a separate recording action. ## Call behavior and limits Each AI session is limited to ten minutes. Calls exceeding that limit use the existing fallback. Media or connection failure runs no-answer once; an AI fallback cannot loop back to itself. Phone.inc does not impose a per-company daily start limit, simultaneous AI call limit or per-call tool-operation cap. Fallback and recording settings remain number-specific. See the [customer setup guide](/help/call-routing#ai-receptionist) for the dashboard workflow. Every newly published agent includes `phone_inc_business_hours`. This read-only tool takes no model-supplied arguments and reads the business number from the authenticated call session, so one receptionist can serve numbers with different hours. It returns the number's public ID, timezone, current local timestamp, whether hours are configured, the current open/closed result and a seven-day schedule. Closing time `24:00` means the end of the day. Without any configured hours, open-now is `null` (unknown), not closed. Configured schedules treat missing weekdays as closed. Hours are live on each invocation and use the same tenant isolation and tool audit path. Opening hours take priority over saved website hours; they are not employee availability and do not include holiday exceptions. Older published agents gain the tool when republished by saving changed receptionist settings. Newly published agents also include `phone_inc_last_conversation`. It accepts no arguments: Rails fixes the company and exact incoming caller number from the authenticated session. It returns the latest earlier answered call that is now completed, across the company's business numbers, including outbound callbacks. The result contains the call ID, start time, direction, recorded employee participants and saved summary, not transcripts, recordings, voicemail or SMS. Missed and active calls are excluded. Failed transfer targets are not added as participants. A missing summary is `null`; the tool does not substitute an older conversation. Summaries are stripped of HTML and limited to 2,000 characters, with `summary_truncated` indicating incomplete text. An unidentified caller returns `unavailable`; no matching call returns `not_found`. This limited history lookup uses caller ID without verifying identity. Spoofed, shared or reassigned numbers can therefore expose another person's previous summary to the AI provider. The agent is instructed to use it when the caller refers to their last call, treat it as untrusted data, and not recite private details unprompted; these instructions are not an identity-verification boundary. Historical participants do not grant transfer permission. Lookups use the existing independently retained encrypted tool audit trail. Saving a receptionist republishes its agent with the new tool; existing calls keep their version. This is an internal live-call tool, not a new public API or MCP endpoint; authenticated account tools already expose calls separately. AI audio and transcription follow the number's existing recording and retention settings. ElevenLabs conversation recording and transcript retention are disabled. Tool audits are retained independently of conversational recording and are returned as `ai_tools` on the [call model](/api/calls). The dashboard shows friendly action cards with optional technical details, placed approximately in the transcript rather than aligned to exact speech timestamps. ## Integration access Receptionists cannot fetch caller context from integrations, look up live orders or bookings, execute remote MCP tools, or schedule callbacks. A collected callback time is a preference, not an appointment or promise. Generic remote MCP-server connections are no longer supported. The former nested `mcp_servers` endpoints and their four management tools have been removed. Saved legacy grants are excluded from receptionist configuration responses and discarded on the next save. Remote MCP execution is denied even for previously published agents, active call snapshots and cached tool results; actions already dispatched before rollout cannot be undone. Saving a receptionist republishes its agent without remote MCP tools. Historical call and revision records are preserved. Receptionist integrations are also unavailable. Non-empty `configuration.integrations` grants are rejected; legacy empty arrays are accepted but omitted from responses. Saved grants cannot fetch caller context or execute integration tools, including on existing calls or through cached results. Saving republishes the agent without integration tools. Company-wide integrations and Phone.inc's authenticated [public MCP API](/mcp) remain unchanged. --- # Texting and inbox Read calls, voicemails, and texts in one history. Send from a business number, check delivery, and share reusable replies with your team. ## The activity model Messages use shared persistence (`messages` and `message_send_attempts`), rather than separate SMS and MMS tables. A message retains its identity across retries; each provider submission has its own potentially chargeable attempt. Sending supports SMS only. Incoming inMobile MMS attachments are persisted alongside messages and can be retrieved when **Message attachments** is enabled. Sending uses `/business_numbers/:id/messages`, retrieval uses `/messages/:id`, and explicit retries use `/messages/:message_id/retries`. The unused proof-of-concept `/business_numbers/:id/sms_messages` sending route is not exposed. The optional send body `format` defaults to `sms`; MMS is rejected before any provider request. Message activity uses `type: "message"` with a separate `format: "sms"`. Future formats share the same message activity type. List grouped previews with `GET /api/v1/inbox`, load a number's timeline with `GET /api/v1/inbox/:phone_number/activity`, and mark observed items seen with `POST /api/v1/inbox/:phone_number/seen`. The existing `/api/v1/activity/unseen` endpoint includes people with unseen incoming SMS when messaging is enabled. Messages create or update the external phone number's contact touchpoint, advancing `last_contact_at` like calls and voicemails. Web and API inbox aggregation includes calls, voicemails, and [Notes](/api/notes), plus messages when the company's `messaging` feature flag is enabled. Notes are written messages taken by the receptionist, not SMS, and remain available with messaging disabled. With messaging disabled, SMS is excluded from timelines, previews, unseen counts, and seen updates. Unknown activity types are skipped by the web renderer. The inbox API derives message ordering directly from message timestamps. A conversation is a grouped view of activity for a company and external phone number. There is no conversation resource to create, no conversation ID, and no requirement to save a named contact before texting. Business-number filters narrow that view without changing the underlying records. Use the existing [contacts API](/api/contacts) for recipient details and the [caller context API](/api/caller-context) for integration panels. Every endpoint below accepts company API keys or OAuth tokens. Sending and retrying additionally require a current employee belonging to that company. ### Properties - **id** (`string`):Stable public record ID. SMS IDs identify stored Phone.inc messages, not provider send attempts. - **type** (`string`):One of `call`, `voicemail`, `note`, or `message`. Notes use the separate [Note model](/api/notes#the-note-model), not the SMS-specific fields below. - **format** (`string`):Message format, currently `sms`. Present only on message items; future formats use the same `message` activity type. - **created_at** (`string`):ISO 8601 UTC timestamp with microseconds. For incoming SMS this is when Phone.inc stored the message; `received_at` retains the provider timestamp. - **business_number_id** (`string`):Business number public ID for this activity. - **business_number_name** (`string | null`):Business number label. - **seen_at** (`string | null`):Shared team seen timestamp. Incoming texts start unseen. - **direction** (`string`):Inbound or outbound. - **from / to** (`string`):Phone numbers in E.164, except incoming SMS `from` may contain an alphanumeric sender ID such as `CryoVital` (up to 11 ASCII letters, digits, or spaces, including at least one letter). Sender IDs are preserved as received and cannot receive replies. Voicemail items include `from` only. - **text** (`string`):SMS body, encrypted at rest. Present on SMS items, not on call or voicemail items. - **author** (`object`):SMS author: `type` is `customer`, `employee`, or `automation`. Employee authors include their public `id` and `name` when the employee still exists. Automation includes `name: "Auto-reply"`. - **status** (`string`):SMS status: `queued`, `accepted`, `delivered`, `failed`, `unknown`, or `received`. Acceptance is not delivery. `unknown` includes provider timeouts and unknown delivery reports. - **sms_count / encoding** (`integer | null / string | null`):Provider-reported SMS segment count and `gsm7` or `ucs2` encoding. inMobile delivery reports can refresh these values after the initial send response. Segment count alone does not confirm a charge. May be null before acceptance, when the response was lost, or for DIDWW sends, whose acceptance response does not report these values. - **received_at / delivered_at** (`string | null`):Provider receive timestamp for incoming SMS, or confirmed delivery timestamp for outgoing SMS. - **failure_code** (`string | null`):Sanitized SMS failure code, such as `provider_rejected`, `sending_unavailable`, or `inmobile_-1`. Not a raw provider error message. - **attachments** (`array`):Only on `GET /messages/:id` when **Message attachments** is enabled. Ordered attachment metadata: `id` (public UUID), `status` (`pending` or `ready`), `filename`, `content_type`, and `byte_size`. Pending files have null file metadata. An empty list means no attachments. Omitted entirely when the flag is off. Download links require the attachment endpoint; inbox previews and activity responses do not include this field. - **can_retry** (`boolean`):True only for a definitively failed outgoing message whose sender still supports sending. - **summary / duration / state / missed / employee / has_transcription** (`call fields`):Call summary, duration in seconds, state, missed flag, nullable employee reference, and whether transcription is available. Fetch the existing call endpoint for full transcription. - **transcription / recording_url / listened / call_id** (`voicemail fields`):Voicemail transcript, playback URL, listened flag, and linked call public ID when present. Voicemails also include duration in seconds when known. Inbox threads include `phone_number`, a nullable contact reference, `last_activity_at`, `unseen_count`, `business_number_ids`, `reply_business_number_id`, `preview`, and `latest_item`. The preview is limited to 160 characters. The latest-item metadata omits full text, summary, transcript, and recording URL; load activity for the full content. The suggested reply number is the latest item's number when it supports sending, otherwise null. Always select the sender explicitly for a send. Thread unseen counts include incoming calls, voicemails, Notes, and incoming texts with no seen timestamp. Outgoing activity never contributes to unread counts, even if its seen timestamp is cleared. A voicemail and its linked missed call count as one item. The existing [unseen activity API](/api/calls#unseen-activity) counts distinct people per business number rather than summing message counts. The unread endpoint includes Notes independently of messaging and incoming SMS when messaging is enabled. Partner tokens see only readable resource types and can acknowledge only writable ones; Notes require `notes:read` and, for seen updates, `notes:write`. The legacy `/calls/seen` endpoint remains calls-and-voicemails-only; use the inbox seen endpoint to acknowledge Notes and SMS. Clients should ignore unknown activity types and continue cursor pagination even when a page contains only unsupported items. A whole-thread seen acknowledgement applies to every writable activity type through its observation boundary, including items a client did not render. ### Messaging capabilities Read `messaging` from the [business-number API](/api/business-numbers#the-business-number-model): ```json { "messaging": { "sms": { "can_send": true, "can_receive": true }, "mms": { "can_send": false, "can_receive": false } } } ``` The company's `messaging` feature flag defaults to off and is managed by Phone.inc. Messaging endpoints (messages, retries, text snippets, and texting settings) return `404` while it is off. SMS is excluded from inbox previews, timelines, unseen counts, and seen updates. Sending requires this flag and provider capability, including queued sends, retries, and automatic replies. inMobile numbers need an associated inventory record marked SMS-capable. DIDWW numbers need a provisioned DID and a stored carrier feature snapshot containing `p2p`. Missing provider capability, an inactive number, a disallowed destination, or a plan without outbound messages makes `messaging.sms.can_send` false and rejects new sends with `422`. Receive capability does not depend on the company messaging feature: authenticated carrier callbacks keep storing supported inbound messages and updating delivery state while messaging is off, so messages become visible when it is enabled. DIDWW directions are derived independently from carrier features; check `can_send` and `can_receive` separately. DIDWW numbers that can send support SMS sends, retries after definitive failures, and automatic replies through the same endpoints as inMobile. The number's existing provider handles voice and messaging. Inbound inMobile MMS attachments are stored, but the existing MMS send/receive capability flags remain false; they do not indicate attachment-history access. Unsupported or inactive senders cannot send, retry, or dispatch queued attempts. Existing history remains available when the company's messaging flag is enabled; delivery callbacks continue regardless of that flag. The message endpoints are format-neutral; stored inbound MMS retains the existing `sms` format and exposes files separately through the attachment API. Automatic replies remain SMS-only and are not sent to alphanumeric sender IDs. Incoming messages from these IDs are stored and available through the message endpoint, but do not create phone-number contacts. Phone-number conversation endpoints do not accept sender IDs. Messages from alphanumeric sender IDs do not contribute to inbox unseen counts or unread badges. ### Delivery, retries, and live updates Send with the existing [Send an SMS endpoint](/api/business-numbers#send-an-sms). Use a new idempotency key for each intentional send and reuse that key after a transport interruption. Keys are scoped to the sender business number. Reusing a key with changed recipient, body, or employee returns `409`. Messages are persisted before the provider request. A send error after persistence includes the stable message `id`. Check that record before taking further action. There are no automatic provider-request retries. A process interrupted after claiming an attempt leaves its state `unknown`, not safely retryable. inMobile incoming messages and delivery callbacks use signature verification. DIDWW incoming messages use a server-configured bearer token over HTTPS. Incoming provider message IDs are deduplicated permanently while their SMS record exists, independently of receipt retention. Provider timestamps do not control the arrival/seen boundary. Texts and settings are not governed by call-data retention; they remain until their owning number or company is removed. The authenticated `CallsChannel` sends `sms_update` notifications containing `id` and `phone_number`, plus `unseen_update` notifications. Treat these as invalidations: refresh the inbox, activity, or message endpoint. Refresh on reconnect as well. No message body is broadcast. Mobile background notification registration and delivery are not part of this API. Incoming callbacks persist texts only for active business numbers belonging to the callback's provider. DIDWW numbers also require `sms_in` in their stored carrier features. Authenticated callbacks for unknown, inactive, or mismatched-provider numbers are archived and acknowledged without creating a message or reserving a receipt. Canonical inMobile webhooks are `/webhooks/inmobile/messages` for incoming messages and `/webhooks/inmobile/delivery_reports` for outgoing delivery reports. The existing `/webhooks/inmobile/sms` and `/webhooks/inmobile/sms_statuses` URLs remain direct aliases, so existing provider configuration and preview callback URLs keep working. DIDWW SMS directions come from the number’s stored carrier features: `p2p` supports outbound P2P SMS and `sms_in` supports inbound SMS. There are no separate per-number enablement switches. Company messaging, plan, active-number, and destination-country restrictions still apply to sending. A2P support does not imply outbound P2P support. Phone.inc records these features during purchase provisioning, port completion, and temporary-number restoration. DID replacements update the feature snapshot with the DID; a missing DID group blocks the swap. Moving to an inventory provider clears DIDWW-specific feature data. A one-time migration fetches missing snapshots for existing active, unreleased DIDWW numbers with a carrier DID ID. It preserves all known snapshots, including an empty feature list. Numbers without stored carrier features report both SMS directions as unavailable until their features are populated. The stored features are not client-writable. Number search marks a DIDWW number SMS-capable only when its DID group supports both `sms_in` and `p2p`. Operators can preview the backfill using the new revision’s backend code and the target environment’s DIDWW credentials and API mode: ```bash bin/rails didww:backfill_features_dry_run ``` The dry run performs the same read-only DIDWW lookups and reports proposed updates. It does not write database records or mark the migration as applied. Apply through the normal database migration process after reviewing the output. Both modes log carrier errors (including 404s), missing group features, and mismatched DIDs, then continue with the next number. Failed numbers remain unchanged and are included in the summary error count; the migration can finish and be marked applied with outstanding lookup errors. Applied rows are committed individually. After resolving the errors, rerun the dry-run task to review remaining missing snapshots; retrying writes requires explicitly rerunning the backfill. Database write failures still stop the migration. Concurrent changes to the DID, phone number, provider, lifecycle, or snapshot are not overwritten. The backfill never changes carrier routing, and rollback does not clear snapshots. Carrier support does not verify trunk configuration. Operators must configure inbound SMS routing in the DIDWW portal; an unassigned SMS IN trunk is a provisioning error, not a separate disabled state. The published DIDWW v3 API does not expose SMS trunk provisioning. Outbound P2P SMS requires a verified DIDWW account and an HTTP OUT trunk whose source rules permit the DID. Configure `DIDWW_SMS_USERNAME` and `DIDWW_SMS_PASSWORD`, using the EU (AMS) endpoint (`https://eu.sms-out.didww.com/outbound_messages`). Outbound HTTP trunks do not use the inbound DID-to-trunk assignment. See [DIDWW’s SMS service guide](https://doc.didww.com/sms/how-sms-service-works.html#p2p-outbound-sms-access) for the account verification requirement. DIDWW sends start as `accepted` after submission. Processing callbacks can report a failure or the fragment count, but only a delivery receipt confirms delivery. Provider timeouts remain `unknown` and cannot be retried automatically. DIDWW outbound callbacks use `POST /webhooks/didww/delivery_reports`. Set a separate, randomly generated `DIDWW_SMS_DELIVERY_WEBHOOK_TOKEN` in each environment, then configure the HTTP OUT trunk’s Callback URL as `https:///webhooks/didww/delivery_reports?token=`. Treat the full URL as a secret: do not share it in tickets or public logs. Rails filters the token from request logs; raw Rack tracing is disabled for this endpoint to avoid recording the query credential. Configure any external access logs to omit or redact the query string. This URL-based credential is specific to HTTP OUT callbacks, whose documented trunk settings do not offer custom authorization headers; it is separate from the HTTP IN bearer token below. DIDWW sends JSON:API bodies with `Content-Type: application/vnd.api+json`. Both callback types correlate to the provider message ID stored on the individual send attempt: - `outbound_message_callbacks`: `Success` keeps the attempt `accepted`, never `delivered`. `fragments_sent` updates `sms_count`; `price` records the total carrier charge for all fragments on that send attempt, without multiplying by the fragment count. `Routing error` and `Failed` mark a definitive failure with a sanitized `didww_` failure code. - `dlr_event`: `DELIVERED`, `DELIVRD`, `DLVRD`, `DELIVERD`, or `DELIV` marks delivery and sets `delivered_at` from `time_start`. DIDWW support confirms that carrier status spellings vary and that documented values are examples, not an exhaustive enum. Phone.inc accepts these exact confirmed spellings without fuzzy matching. `FAILED` and `EXPIRED` mark definitive failures. Unrecognized DLR statuses emit a structured WARN log containing the callback type, provider message ID, and JSON-escaped status, without the callback token, message content, or full payload. They remain `unknown` unless the attempt already has a final delivered or failed state, which is preserved. Warnings are emitted even for attempts already in a final state. Valid callbacks with unrecognized statuses are still acknowledged with `200`; unknown status alone does not make a send retryable. DIDWW carrier cost is stored internally as `carrier_cost` and `carrier_cost_currency` on each send attempt, separately from customer pricing. The callback does not include a currency field; Phone.inc records `USD` because [DIDWW lists all rates in USD](https://doc.didww.com/billing/billing-and-prices/didww-pricing.html). Amounts use decimal storage with eight fractional digits. A missing or null `price` leaves cost unknown; an explicit zero records a known zero charge. Negative, nonnumeric, overprecision, or out-of-range prices reject the processing callback with `400` without changing the attempt. Duplicate callbacks never add another charge. If callbacks report different totals, the highest reported total is retained so a lower late callback cannot erase a charge. Delivery updates preserve cost, and a processing callback arriving after delivery can still populate it. Retries have separate cost records. Existing DIDWW attempts remain unknown unless a processing callback supplies a price. There is no historical cost backfill. inMobile reports provide charging metadata, not a monetary cost. Carrier costs are not included in customer API or MCP message responses. Contact [DIDWW support](mailto:support@didww.com) to enable **DLR event notifications**; setting the Callback URL alone does not enable them. See [DIDWW’s callback documentation](https://doc.didww.com/sms/outbound-sms-api/status-callbacks-and-delivery-receipts.html). Duplicate callbacks are safe. A delivered attempt cannot be downgraded by a late callback, and late processing success cannot clear a definitive failure. Callbacks still update existing attempts when messaging or outbound sending is disabled. An unknown provider ID returns `503` so DIDWW can retry if the callback arrived before the send response was saved; callbacks cannot be correlated if the send response was lost entirely. Missing server credentials also return `503`, invalid credentials return `401`, malformed callbacks return `400`, and bodies above 16 KiB return `413`. DIDWW inbound SMS uses `POST /webhooks/didww/messages`. Phone.inc operators must configure an HTTP IN trunk and assign that trunk or its SMS trunk group to each inbound-capable DID in the DIDWW portal. There is no separate receive-enablement flag. Set a separate, randomly generated `DIDWW_SMS_WEBHOOK_TOKEN` in each environment and configure the trunk's `Authorization` header as `Bearer `. Do not put the token in the request URL. Missing server configuration or missing inbound carrier support in the stored feature snapshot returns `503`; invalid credentials return `401`. Configure the HTTP IN trunk body as JSON using DIDWW's variables: ```json { "message_id": "{SMS_UUID}", "from": "{SMS_SRC_ADDR}", "to": "{SMS_DST_ADDR}", "text_base64": "{SMS_TEXT_BASE64_ENCODED}", "received_at": "{SMS_TIME}" } ``` Use `Content-Type: application/json` and the base64 text variable so quotes, line breaks, and Unicode do not corrupt the payload. `received_at` is DIDWW's HTTP-date timestamp. The DIDWW receiver accepts up to 64 KiB of UTF-8 text, matching DIDWW's documented transport limit; its request body is limited to 100,000 bytes. Outbound text is limited to 10,000 characters for every provider. Stored inbound messages have no application-level text-length limit; inMobile inbound text is not restricted by the outbound limit. DIDWW reassembles concatenated SMS before forwarding it. Successful delivery returns `200` with no body; malformed payloads return `400` and oversized requests return `413`. DIDWW retries non-2xx deliveries for up to one hour. Duplicate message UUIDs are acknowledged without duplicating messages, notifications, or automatic replies. For delivery callbacks, configure the server-owned `INMOBILE_SMS_STATUS_CALLBACK_URL` to your public `/webhooks/inmobile/sms_statuses` URL and configure InMobile signing keys through `INMOBILE_WEBHOOK_PUBLIC_KEYS`. The URL is attached to outgoing provider requests; clients cannot override it. Without a callback configuration, accepted messages cannot advance to confirmed delivery through this integration. inMobile's [status reports](https://api.inmobile.com/docs/index.html?url=/swagger/v1/swagger.json) can include `chargeInfo`. Phone.inc stores `isCharged` as an internal, nullable `carrier_charged` flag on the send attempt: null means no explicit charging flag has been received, false means the provider says it will not charge, and true means it says it will charge. Supplied `smsCount` and `encoding` refresh the existing `sms_count` and `encoding` values. Absent or null `chargeInfo` preserves existing metadata; partial objects update only supplied fields. Supplied fields must have valid types and values, otherwise the entire report batch returns `400` without partial updates. Charging is independent of delivery: failed messages can still be charged, and later billing metadata is processed even when delivery is already final. Once an attempt is reported charged, a later uncharged report cannot erase that flag or its segment/encoding metadata. Repeated identical reports do not add segments or rewrite unchanged state. Reports affect only the matching outbound inMobile attempt, so retries retain separate metadata. inMobile does not report a monetary amount or currency here; `carrier_cost` and `carrier_cost_currency` remain unknown rather than being estimated or set to zero. The charging flag is not exposed through customer API or MCP responses, and raw reports are not archived. Existing attempts are not backfilled, and DIDWW cost handling is unchanged. --- ## List the inbox Returns one thread per external phone number, newest activity first. Optional `business_number_id` restricts history to that number. `query` matches contact name, company name, or phone number (up to 128 characters); it does not search message bodies. `unseen=true` returns only threads with unseen timeline items. `limit` defaults to 50 and is clamped to 1–100. Pass `next_cursor` as `cursor` to load more. A cursor is bound to the company, business-number filter, query, and unseen filter; malformed or mismatched cursors return `422`. ```bash curl --get https://app.phone.inc/api/v1/inbox \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ --data-urlencode 'limit=50' ``` ```js const response = await fetch('https://app.phone.inc/api/v1/inbox' + '?' + new URLSearchParams({"limit":50}), { method: 'GET', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, }, }) const result = await response.json() ``` ```python import os import requests response = requests.get( 'https://app.phone.inc/api/v1/inbox', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, params={"limit":50}, ) result = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/inbox') uri.query = URI.encode_www_form(JSON.parse('{"limit":50}')) request = Net::HTTP::Get.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, max_retries: 0) do |http| http.request(request) end result = JSON.parse(response.body) ``` ```json { "threads": [ { "phone_number": "+4523909778", "contact": null, "last_activity_at": "2026-10-06T10:41:00.000000Z", "unseen_count": 1, "business_number_ids": [ "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01" ], "reply_business_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "preview": "Is the basket included?", "latest_item": { "id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc", "type": "message", "format": "sms", "business_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "direction": "inbound", "status": "received" } } ], "next_cursor": null } ``` --- ## List activity The `phone_number` path parameter identifies the external person. National-format numbers are normalized using the company's country; E.164 is recommended; URL-encode the leading `+` as `%2B`. Optional `business_number_id` filters the history. `limit` defaults to 50 and is clamped to 1–100. Items are newest first; render them in reverse order for a chat timeline. Pass `next_cursor` as `cursor` for older items. Stable tie-breaking prevents duplicate items when timestamps match. A voicemail replaces its linked call's timeline item. An unknown number returns an empty list and does not create a contact. The response includes the normalized E.164 `phone_number` and nullable contact reference for the conversation header; use that normalized number when sending from a national-number draft. Reading does not change seen state. Save `observed_at` for the mark-seen request. Cursor pages preserve that original observation timestamp, so paging through older history does not mark newer arrivals seen. Pass `observed_at` unchanged as a string when marking seen; converting it through a client date type can lose microsecond precision. ```bash curl --get https://app.phone.inc/api/v1/inbox/%2B4523909778/activity \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ --data-urlencode 'limit=50' ``` ```js const response = await fetch('https://app.phone.inc/api/v1/inbox/%2B4523909778/activity' + '?' + new URLSearchParams({"limit":50}), { method: 'GET', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, }, }) const result = await response.json() ``` ```python import os import requests response = requests.get( 'https://app.phone.inc/api/v1/inbox/%2B4523909778/activity', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, params={"limit":50}, ) result = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/inbox/%2B4523909778/activity') uri.query = URI.encode_www_form(JSON.parse('{"limit":50}')) request = Net::HTTP::Get.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, max_retries: 0) do |http| http.request(request) end result = JSON.parse(response.body) ``` ```json { "phone_number": "+4523909778", "contact": null, "items": [], "next_cursor": null, "observed_at": "2026-10-06T10:41:00.000000Z" } ``` --- ## Mark activity seen Marks incoming calls, voicemails, Notes, and texts from this number seen through the `observed_at` timestamp returned by List activity, subject to resource write permissions. Optional `business_number_id` restricts the change to one business number; omitting it applies across the company. `through` is required, must be ISO 8601, and must not be in the future. Later arrivals remain unseen, including texts whose provider timestamp predates your observation. Seen state is shared by the team, not per employee. Voicemail listened state is unchanged. Returns `204 No Content`. ```bash curl -X POST https://app.phone.inc/api/v1/inbox/%2B4523909778/seen \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"through":"2026-10-06T10:41:00.000000Z"}' ``` ```js const response = await fetch('https://app.phone.inc/api/v1/inbox/%2B4523909778/seen', { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({"through":"2026-10-06T10:41:00.000000Z"}), }) ``` ```python import os import requests response = requests.post( 'https://app.phone.inc/api/v1/inbox/%2B4523909778/seen', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, json={"through":"2026-10-06T10:41:00.000000Z"}, ) ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/inbox/%2B4523909778/seen') request = Net::HTTP::Post.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = "{\"through\":\"2026-10-06T10:41:00.000000Z\"}" response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, max_retries: 0) do |http| http.request(request) end ``` --- ## Retrieve a text {{ tag: 'GET', label: '/v1/messages/{id}' }} Returns a persisted message by its public `id`, including its current delivery status. With the company's **Message attachments** flag enabled (default off, managed by Phone.inc), this response also includes an `attachments` array of metadata ordered as received. Use [Retrieve an attachment](#retrieve-an-attachment) for download links. With the flag off, the field is omitted. Inbound attachment persistence continues regardless of the flag; enabling it exposes already-stored files. Attachment-only messages may have empty `text`. Unknown or foreign-company IDs return `404`. Use this after a network interruption or a send response with an `id`; do not create another send just to check whether the first succeeded. ```bash curl https://app.phone.inc/api/v1/messages/019daef1-085e-73f0-85f6-a71e2d8dd2cc \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/messages/019daef1-085e-73f0-85f6-a71e2d8dd2cc', { method: 'GET', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, }, }) const result = await response.json() ``` ```python import os import requests response = requests.get( 'https://app.phone.inc/api/v1/messages/019daef1-085e-73f0-85f6-a71e2d8dd2cc', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, ) result = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/messages/019daef1-085e-73f0-85f6-a71e2d8dd2cc') request = Net::HTTP::Get.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, max_retries: 0) do |http| http.request(request) end result = JSON.parse(response.body) ``` ```json { "id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc", "type": "message", "format": "sms", "created_at": "2026-10-06T10:41:00.000000Z", "business_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "business_number_name": "Sales", "seen_at": "2026-10-06T10:41:00.000000Z", "direction": "outbound", "from": "+4592450113", "to": "+4523909778", "text": "Your appointment is confirmed.", "author": { "type": "employee", "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "name": "Lea" }, "status": "accepted", "sms_count": 1, "encoding": "gsm7", "delivered_at": null, "received_at": null, "failure_code": null, "can_retry": false } ``` --- ## Retrieve an attachment Retrieve metadata and a short-lived download link for a stored inbound attachment. Use the message's public ID and an attachment public ID from `GET /api/v1/messages/:id`. Both **Messaging** and **Message attachments** must be enabled for the company. Missing authentication returns `401`; disabled flags, unknown IDs, another company's message, or an attachment belonging to another message return `404`. The JSON response includes `id`, `status`, `filename`, `content_type`, `byte_size`, `download_url`, and `expires_at`. Status is `pending` until the background download has been stored; pending files have null metadata, download URL, and expiry. Poll this endpoint to check again. A failed background download remains pending; no provider error or source URL is exposed. A `ready` file has a storage download URL valid for **five minutes** and an ISO 8601 UTC `expires_at`. Follow that URL without sending your Phone.inc API key. The download uses attachment disposition rather than inline display. The URL is a temporary bearer credential: anyone holding it can download the file until expiry. Do not log or share it. Obtain a fresh URL through this authenticated endpoint after expiry. Disabling either feature flag blocks new URLs but does not revoke already-issued URLs before expiry. Responses use `Cache-Control: private, no-store`. ```bash curl https://app.phone.inc/api/v1/messages/$MESSAGE_ID/attachments/$ATTACHMENT_ID \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch( `https://app.phone.inc/api/v1/messages/${messageId}/attachments/${attachmentId}`, { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }, ) const attachment = await response.json() ``` ```python import os import requests response = requests.get( f'https://app.phone.inc/api/v1/messages/{message_id}/attachments/{attachment_id}', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, ) attachment = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI("https://app.phone.inc/api/v1/messages/#{message_id}/attachments/#{attachment_id}") request = Net::HTTP::Get.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, max_retries: 0) do |http| http.request(request) end attachment = JSON.parse(response.body) ``` ```json { "id": "019daef1-085e-73f0-85f6-a71e2d8dd2cd", "status": "ready", "filename": "attachment-1", "content_type": "image/jpeg", "byte_size": 154230, "download_url": "https://storage.example/attachment?signature=temporary", "expires_at": "2026-10-26T11:05:00Z" } ``` --- ## Retry a failed text {{ tag: 'POST', label: '/v1/messages/{id}/retries' }} Explicitly retries a definitively `failed` text with the same sender and body, keeping its message `id` and recording a new send attempt. This is a real, chargeable SMS. An employee belonging to the company is required. Supply a new `idempotency_key` (1–128 characters), or the `Idempotency-Key` header. Repeating the same retry key replays the attempt without sending again. `unknown`, `accepted`, `delivered`, and inbound messages cannot start a retry (`409`). The sender must still support sending. A different key represents a new retry, not a replay. A missing/invalid retry key returns `409`. Send and retry attempts share a limit of 30 per business number in a rolling minute; exceeding it returns `429` with `Retry-After: 60`. Success returns `202 Accepted`. API keys and legacy or first-party OAuth tokens receive the message activity object. Partner OAuth tokens require `messages:send`; sending does not require `messages:read`. Without `messages:read`, the retry response contains only `id` and `status`, with no stored text, addresses, author, or other activity metadata. With `messages:read`, partners receive the message activity object, subject to their other field permissions. The MCP `retry_message` tool returns the same response body. For a send-only partner, the response is: ```json { "id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc", "status": "accepted" } ``` ```bash curl -X POST https://app.phone.inc/api/v1/messages/019daef1-085e-73f0-85f6-a71e2d8dd2cc/retries \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"idempotency_key":"retry-appointment-1"}' ``` ```js const response = await fetch('https://app.phone.inc/api/v1/messages/019daef1-085e-73f0-85f6-a71e2d8dd2cc/retries', { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({"idempotency_key":"retry-appointment-1"}), }) const result = await response.json() ``` ```python import os import requests response = requests.post( 'https://app.phone.inc/api/v1/messages/019daef1-085e-73f0-85f6-a71e2d8dd2cc/retries', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, json={"idempotency_key":"retry-appointment-1"}, ) result = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/messages/019daef1-085e-73f0-85f6-a71e2d8dd2cc/retries') request = Net::HTTP::Post.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = "{\"idempotency_key\":\"retry-appointment-1\"}" response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, max_retries: 0) do |http| http.request(request) end result = JSON.parse(response.body) ``` ```json { "id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc", "type": "message", "format": "sms", "status": "accepted", "can_retry": false } ``` --- ## List snippets Returns company-shared snippets ordered by `position`, then creation order. Selecting a snippet only inserts editable text into your local draft. It never sends an SMS. ```bash curl https://app.phone.inc/api/v1/text_snippets \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/text_snippets', { method: 'GET', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, }, }) const result = await response.json() ``` ```python import os import requests response = requests.get( 'https://app.phone.inc/api/v1/text_snippets', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, ) result = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/text_snippets') request = Net::HTTP::Get.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, max_retries: 0) do |http| http.request(request) end result = JSON.parse(response.body) ``` ```json [ { "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "title": "On my way", "text": "I'm on my way, with you in about 15 minutes.", "position": 0, "created_at": "2026-10-06T10:41:00.000000Z", "updated_at": "2026-10-06T10:41:00.000000Z" } ] ``` --- ## Create a snippet Required `title` contains 1–128 characters and `text` contains 1–10,000 characters; whitespace-only values are rejected. Optional `position` is a nonnegative integer, default 0. Returns the saved snippet with `201 Created`. ```bash curl -X POST https://app.phone.inc/api/v1/text_snippets \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"title":"On my way","text":"I'"'"'m on my way, with you in about 15 minutes.","position":0}' ``` ```js const response = await fetch('https://app.phone.inc/api/v1/text_snippets', { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({"title":"On my way","text":"I'm on my way, with you in about 15 minutes.","position":0}), }) const result = await response.json() ``` ```python import os import requests response = requests.post( 'https://app.phone.inc/api/v1/text_snippets', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, json={"title":"On my way","text":"I'm on my way, with you in about 15 minutes.","position":0}, ) result = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/text_snippets') request = Net::HTTP::Post.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = "{\"title\":\"On my way\",\"text\":\"I'm on my way, with you in about 15 minutes.\",\"position\":0}" response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, max_retries: 0) do |http| http.request(request) end result = JSON.parse(response.body) ``` ```json { "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "title": "On my way", "text": "I'm on my way, with you in about 15 minutes.", "position": 0, "created_at": "2026-10-06T10:41:00.000000Z", "updated_at": "2026-10-06T10:41:00.000000Z" } ``` --- ## Retrieve a snippet {{ tag: 'GET', label: '/v1/text_snippets/{id}' }} Returns a company-shared snippet by public `id`. Unknown and foreign-company IDs return `404`. ```bash curl https://app.phone.inc/api/v1/text_snippets/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01 \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/text_snippets/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01', { method: 'GET', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, }, }) const result = await response.json() ``` ```python import os import requests response = requests.get( 'https://app.phone.inc/api/v1/text_snippets/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, ) result = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/text_snippets/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01') request = Net::HTTP::Get.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, max_retries: 0) do |http| http.request(request) end result = JSON.parse(response.body) ``` ```json { "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "title": "On my way", "text": "I'm on my way, with you in about 15 minutes.", "position": 0, "created_at": "2026-10-06T10:41:00.000000Z", "updated_at": "2026-10-06T10:41:00.000000Z" } ``` --- ## Update a snippet {{ tag: 'PATCH', label: '/v1/text_snippets/{id}' }} Accepts any combination of `title`, `text`, and `position`, using the same validation as creation. Other fields are ignored. Changes are shared with the company. ```bash curl -X PATCH https://app.phone.inc/api/v1/text_snippets/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01 \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"text":"I'"'"'ll be there in 10 minutes."}' ``` ```js const response = await fetch('https://app.phone.inc/api/v1/text_snippets/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01', { method: 'PATCH', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({"text":"I'll be there in 10 minutes."}), }) const result = await response.json() ``` ```python import os import requests response = requests.patch( 'https://app.phone.inc/api/v1/text_snippets/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, json={"text":"I'll be there in 10 minutes."}, ) result = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/text_snippets/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01') request = Net::HTTP::Patch.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = "{\"text\":\"I'll be there in 10 minutes.\"}" response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, max_retries: 0) do |http| http.request(request) end result = JSON.parse(response.body) ``` ```json { "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "title": "On my way", "text": "I'll be there in 10 minutes.", "position": 0, "created_at": "2026-10-06T10:41:00.000000Z", "updated_at": "2026-10-06T10:42:00.000000Z" } ``` --- ## Delete a snippet {{ tag: 'DELETE', label: '/v1/text_snippets/{id}' }} Deletes a company-shared snippet. Previously sent texts are unaffected. Returns `204 No Content`. ```bash curl -X DELETE https://app.phone.inc/api/v1/text_snippets/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01 \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/text_snippets/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01', { method: 'DELETE', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, }, }) ``` ```python import os import requests response = requests.delete( 'https://app.phone.inc/api/v1/text_snippets/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, ) ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/text_snippets/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01') request = Net::HTTP::Delete.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, max_retries: 0) do |http| http.request(request) end ``` --- ## Retrieve texting settings {{ tag: 'GET', label: '/v1/business_numbers/{business_number_id}/texting_settings' }} Returns the business number's outside-hours auto-reply settings. A number without saved settings returns these defaults without creating a settings record. Hours and timezone come from the business number's existing configuration. ```bash curl https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/texting_settings \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/texting_settings', { method: 'GET', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, }, }) const result = await response.json() ``` ```python import os import requests response = requests.get( 'https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/texting_settings', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, ) result = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/texting_settings') request = Net::HTTP::Get.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, max_retries: 0) do |http| http.request(request) end result = JSON.parse(response.body) ``` ```json { "auto_reply_enabled": false, "auto_reply_text": null, "auto_reply_cooldown_minutes": 1440 } ``` --- ## Update texting settings {{ tag: 'PATCH', label: '/v1/business_numbers/{business_number_id}/texting_settings' }} Requires a current employee belonging to the company. Accepts `auto_reply_enabled` (boolean), `auto_reply_text` (up to 10,000 characters; required and nonblank when enabled), and `auto_reply_cooldown_minutes` (integer 60–43,200, default 1,440). Enabling this may send real, chargeable texts without an app open, but only while the number supports SMS sending. On an incoming text outside the number's business hours, a background job sends the reply from that same number. The job skips sending if business hours have reopened. The cooldown applies per external number and business number, and also prevents loops on duplicate incoming callbacks. Automated messages use `author.type=automation`; they appear in the normal history. Failed or uncertain automatic sends are not blindly retried. Shared sending limits still apply. ```bash curl -X PATCH https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/texting_settings \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"auto_reply_enabled":true,"auto_reply_text":"We'"'"'re closed now. We'"'"'ll reply when we reopen.","auto_reply_cooldown_minutes":1440}' ``` ```js const response = await fetch('https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/texting_settings', { method: 'PATCH', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({"auto_reply_enabled":true,"auto_reply_text":"We're closed now. We'll reply when we reopen.","auto_reply_cooldown_minutes":1440}), }) const result = await response.json() ``` ```python import os import requests response = requests.patch( 'https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/texting_settings', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, json={"auto_reply_enabled":True,"auto_reply_text":"We're closed now. We'll reply when we reopen.","auto_reply_cooldown_minutes":1440}, ) result = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/business_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/texting_settings') request = Net::HTTP::Patch.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = "{\"auto_reply_enabled\":true,\"auto_reply_text\":\"We're closed now. We'll reply when we reopen.\",\"auto_reply_cooldown_minutes\":1440}" response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, max_retries: 0) do |http| http.request(request) end result = JSON.parse(response.body) ``` ```json { "auto_reply_enabled": true, "auto_reply_text": "We're closed now. We'll reply when we reopen.", "auto_reply_cooldown_minutes": 1440 } ``` --- --- # Voicemails When a caller leaves a voicemail, Phone.inc records the audio and ties it to the [business number](/api/business-numbers) that was dialed. The Voicemails API lists every voicemail on your account, gives you a signed URL for the recording, and lets you flip the listened flag from your own UI. ## The voicemail model A voicemail is a small object: who called, when, where the recording is, and whether someone has listened to it yet. Written messages taken by the receptionist are [Notes](/api/notes), not voicemails. Previously saved written messages move to Notes with their IDs, content, and seen state preserved. Use the Notes endpoints to access them; the voicemail endpoints do not provide a compatibility alias. Partner OAuth requires `voicemails:read` to read voicemails, including their recordings and transcriptions, and `voicemails:write` plus `voicemails:read` to update or delete them. These resource permissions also apply when voicemail content is embedded in other responses. No separate content permission is needed. Reference IDs remain available, but embedded employee, contact, department, and business-number details require their matching resource read scopes. Business-number names, numbers, and formatted-number fields require `business_numbers:read`. API-key responses are unchanged. See [OAuth scopes](/api/oauth#scopes). Recordings are checked for spoken words during transcription. Silence and sound effects, such as a hang-up click, are discarded instead of kept as voicemails. The unanswered call remains a missed call and emits `call.lost`. A recording may appear briefly while this check is pending. Voicemail emails and integration notifications wait for speech to be confirmed. If transcription fails, the recording is kept for retry rather than discarded. ### Properties - **id** (`string`): Unique identifier for the voicemail. - **from** (`string`): The caller's phone number in E.164 format. - **kind** (`string`): Always `voicemail`. Written receptionist messages use the separate [Notes API](/api/notes). - **message_details** (`object | null`): Legacy collected-message details, retained in the response for compatibility. Empty or `null` for recorded voicemails; new receptionist details are stored on Notes instead. - **listened_at** (`timestamp`): ISO 8601 timestamp of when the voicemail was first marked as listened. `null` if it hasn't been listened to yet. - **transcription** (`string`): Plain-text transcription of the voicemail recording. `null` until the recording has been transcribed. - **created_at** (`timestamp`): ISO 8601 timestamp of when the voicemail was recorded. - **recording_url** (`string`): URL where the audio file can be downloaded. May be `null` if the recording is still being processed. The URL is generated per request — don't cache it long-term. - **business_number_id** (`string`): The ID of the [business number](/api/business-numbers) the voicemail was left on. - **business_number_name** (`string`): The label of the business number. - **business_number_number** (`string`): The business number in E.164 format. - **business_number_number_formatted** (`string`): The business number formatted for display. --- ## List voicemails Returns every voicemail on the authenticated employee's company, newest first. There are no query parameters or pagination — voicemail volume is low enough that the full list is returned in one response. The response also includes `unlistened_count` at the top — the number of voicemails on the company that haven't been marked as listened yet. It counts every unlistened voicemail, not just the ones in this response, so you can drive an inbox badge straight from it. ```bash curl https://app.phone.inc/api/v1/voicemails \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch( 'https://app.phone.inc/api/v1/voicemails', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }, ) const { voicemails } = await response.json() ``` ```python import os, requests response = requests.get( "https://app.phone.inc/api/v1/voicemails", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) voicemails = response.json()["voicemails"] ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/voicemails') response = Net::HTTP.get_response( uri, { 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY') }, ) voicemails = JSON.parse(response.body)['voicemails'] ``` ```json { "unlistened_count": 3, "voicemails": [ { "id": "0193f4cb-7777-7c00-9e3d-2b2b8a7f1c33", "from": "+14085550199", "listened_at": null, "transcription": "Hi, this is Dana from Acme. Give me a call back about the invoice when you get a chance. Thanks!", "created_at": "2026-05-11T13:48:02Z", "recording_url": "https://app.phone.inc/rails/active_storage/blobs/redirect/.../voicemail.mp3", "business_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "business_number_name": "Sales", "business_number_number": "+14155551234", "business_number_number_formatted": "+1 415-555-1234" } ] } ``` --- ## Retrieve a voicemail Returns a single voicemail by its ID. The response includes the recording URL and all metadata. ```bash curl https://app.phone.inc/api/v1/voicemails/0193f4cb-7777-7c00-9e3d-2b2b8a7f1c33 \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch( `https://app.phone.inc/api/v1/voicemails/${voicemailId}`, { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }, ) const voicemail = await response.json() ``` ```python import os, requests response = requests.get( f"https://app.phone.inc/api/v1/voicemails/{voicemail_id}", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) voicemail = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI("https://app.phone.inc/api/v1/voicemails/#{voicemail_id}") response = Net::HTTP.get_response( uri, { 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY') }, ) voicemail = JSON.parse(response.body) ``` ```json { "id": "0193f4cb-7777-7c00-9e3d-2b2b8a7f1c33", "from": "+14085550199", "listened_at": null, "transcription": "Hi, this is Dana from Acme. Give me a call back about the invoice when you get a chance. Thanks!", "created_at": "2026-05-11T13:48:02Z", "recording_url": "https://app.phone.inc/rails/active_storage/blobs/redirect/.../voicemail.mp3", "business_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "business_number_name": "Sales", "business_number_number": "+14155551234", "business_number_number_formatted": "+1 415-555-1234" } ``` --- ## Update a voicemail Mark a voicemail as listened or unlistened. This is the only field you can update on a voicemail today. Pass `listened=true` to set `listened_at` to the current time (no-op if it's already listened). Pass `listened=false` to clear it. Returns the full voicemail object. ### Optional attributes - **listened** (`boolean`): Whether the voicemail should be marked as listened. Accepts the usual truthy/falsy values (`true`, `false`, `"1"`, `"0"`). ```bash curl -X PATCH https://app.phone.inc/api/v1/voicemails/0193f4cb-7777-7c00-9e3d-2b2b8a7f1c33 \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -d listened=true ``` ```js const response = await fetch( `https://app.phone.inc/api/v1/voicemails/${voicemailId}`, { method: 'PATCH', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/x-www-form-urlencoded', }, body: new URLSearchParams({ listened: 'true' }), }, ) const voicemail = await response.json() ``` ```python import os, requests response = requests.patch( f"https://app.phone.inc/api/v1/voicemails/{voicemail_id}", data={"listened": "true"}, headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) voicemail = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI("https://app.phone.inc/api/v1/voicemails/#{voicemail_id}") request = Net::HTTP::Patch.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request.set_form_data(listened: 'true') response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http| http.request(request) end voicemail = JSON.parse(response.body) ``` ```json { "id": "0193f4cb-7777-7c00-9e3d-2b2b8a7f1c33", "from": "+14085550199", "listened_at": "2026-05-11T16:42:18Z", "transcription": "Hi, this is Dana from Acme. Give me a call back about the invoice when you get a chance. Thanks!", "created_at": "2026-05-11T13:48:02Z", "recording_url": "https://app.phone.inc/rails/active_storage/blobs/redirect/.../voicemail.mp3", "business_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "business_number_name": "Sales", "business_number_number": "+14155551234", "business_number_number_formatted": "+1 415-555-1234" } ``` --- ## Delete a voicemail Permanently deletes a voicemail and its recording. This cannot be undone. Returns an empty response with a `204 No Content` status. ```bash curl -X DELETE https://app.phone.inc/api/v1/voicemails/0193f4cb-7777-7c00-9e3d-2b2b8a7f1c33 \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js await fetch( `https://app.phone.inc/api/v1/voicemails/${voicemailId}`, { method: 'DELETE', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }, ) ``` ```python import os, requests requests.delete( f"https://app.phone.inc/api/v1/voicemails/{voicemail_id}", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) ``` ```ruby require 'net/http' uri = URI("https://app.phone.inc/api/v1/voicemails/#{voicemail_id}") request = Net::HTTP::Delete.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http| http.request(request) end ``` --- # Webhooks Get notified the instant something happens — a call comes in, a voicemail is left, or a transcription finishes. Register a URL once, pick the events you care about, and Phone.inc will POST a JSON payload to your endpoint in real time. ## Partner OAuth permissions Partner OAuth tokens need `webhooks:read` to list subscriptions, and both `webhooks:write` and `webhooks:read` to create, update, or delete them. Subscriptions are scoped to the installation that created them, not every webhook in the company. Application-owned subscriptions are hidden throughout the customer dashboard, including **Webhooks**, **Integrations**, and direct delivery-history links. Customers stop them by disconnecting the application. Publishers see a [sanitized delivery log across customer installations](/applications#webhook-delivery-log) under **Applications**. API keys and legacy tokens can still list subscriptions belonging to their company and inspect their delivery history, but cannot update, delete, retrieve signing secrets, or send test deliveries for application-owned subscriptions; those operations return `404`. Only the owning installation's OAuth credentials can manage them. The same ownership rules apply through MCP. Customer-managed subscriptions keep their existing controls. Each event also requires its resource read scope: `call.*` needs `calls:read`, `voicemail.*` needs `voicemails:read`, `note.*` needs `notes:read`, `contact.*` needs `contacts:read`, `employee.*` needs `employees:read`, and `number.*` needs `business_numbers:read`. Call transcription and summary events need only `calls:read`; voicemail transcription events need only `voicemails:read`. Webhook management permission alone does not grant event data. Each subscription has a scope ceiling based on the creating installation's granted scopes that can shrink but never expand. Resource reads include that resource's recordings, transcriptions, and summaries where available. Deliveries omit ungranted embedded employee, contact, department, and business-number details. Reference IDs remain available. The same redaction applies inside nested payloads. Adding enabled application scopes does not disconnect installations or delete subscriptions. Neither existing tokens nor subscriptions gain permissions after later consent. When installation or application permissions are removed, subscription scope ceilings and event lists shrink permanently. Readding a scope cannot revive removed access on an old subscription; create a new subscription for expanded access. Unaffected narrower credentials and installations continue. See the [OAuth installation lifecycle](/api/oauth#disconnect-rotate-and-reauthorize). Disconnect removes the installation's subscriptions and stops deliveries, including deliveries already queued or waiting for retry. Removing every installed permission also disconnects that installation. Reconnecting does not revive old subscriptions or queued events; create new subscriptions after reconnecting. --- ## The webhook model A webhook subscription tells Phone.inc where to send event notifications and which events to include. ### Properties - **id** (`string`): Unique public identifier for the webhook. - **name** (`string`): A human-readable label for the webhook (e.g. `Slack notifications`, `CRM sync`). - **url** (`string`): The HTTPS endpoint where events are delivered via POST. - **events** (`array`): List of event types this webhook subscribes to. See [Events](#events) for all available types. - **active** (`boolean`): Whether the webhook is currently receiving events. Set to `false` to pause delivery without deleting the subscription. - **signing_secret** (`string`): Per-subscription HMAC secret. Returned only by successful create and update responses, never by lists or delivery diagnostics. Store it securely and do not log it. It is generated by Phone.inc and cannot be set through request parameters. - **created_at** (`timestamp`): ISO 8601 timestamp of when the webhook was created. - **updated_at** (`timestamp`): ISO 8601 timestamp of the last update. --- ## Events Events cover calls, recorded voicemails, Notes, contacts, employee status, and number registration. - **call.initiated**: A new inbound or outbound call has started. The call exists but hasn't been answered yet. - **call.outside_business_hours**: An inbound call arrived outside the business number's configured business hours. Existing `call.outside_opening_hours` subscriptions are migrated to this name, and payloads now use `call.outside_business_hours`. - **call.queued**: The caller joined the employee wait queue. The payload is the existing call envelope; `state` is `queued` and `answered_at` is still null. Fires once per call. - **call.answered**: The call was answered by an employee. `answered_at` is now set on the call, and `employees` includes the employee who answered. - **call.ended**: The call has ended, regardless of outcome. Fires for every call that reaches the `ended` state — answered, missed, or rejected. - **call.lost**: The call ended without being answered and without a spoken voicemail message. This includes recordings containing only silence or sound effects. Discarding a sound-only recording emits this event unless it was already emitted for the call. - **call.transcription_done**: The call recording has been transcribed. The `transcription` and `transcription_segments` fields are now populated on the call. The summary is generated afterwards, so do not rely on `summary` being populated in this event. Subscribe to `call.summary_done` to receive it. - **call.summary_done**: The AI summary of the call has been saved. The payload includes `summary`, `transcription`, and `transcription_segments`. Dispatched after `call.transcription_done`, but webhook deliveries may arrive out of order. Not sent when the call has too little conversation to summarize, contains no meaningful content, or its transcription was deleted during summary generation. - **call.data_deleted**: Call content or a recording was deleted. `data.deleted` lists `transcription`, `recording`, or both. Deleting transcription data also deletes the summary, stored caller context, and whisper brief, even if no transcript exists. `data.reason` is `retention_policy` for scheduled deletion, `keep_disabled` when temporary audio is removed after transcription, or `manual` when an employee deletes call data. - **voicemail.new**: A new voicemail was recorded and confirmed to contain spoken words. Fires after transcription, not immediately after upload. The payload includes call and voicemail data. Written messages taken by the receptionist emit `note.created` instead. - **voicemail.transcription_done**: The voicemail recording has been transcribed. The payload's `voicemail` object now has its `transcription` field populated. - **voicemail.data_deleted**: Voicemail data was manually deleted. `data.deleted` lists removed `transcription`, `recording`, or both, and `data.reason` is `manual`. - **note.created**: A receptionist saved a Note. `data.note` contains the [Note model](/api/notes#the-note-model), including `text` and collected `details`. No enclosing call details are included. - **note.deleted**: A Note was deleted. `data.note` contains its metadata snapshot with `text: null` and `details: {}`. The deleted content is not delivered, and no enclosing call details are included. - **contact.created**: A new contact was added to your address book. The payload's `data.contact` object includes the full [contact model](/api/contacts#the-contact-model). - **contact.updated**: An existing contact was edited. The payload's `data.contact` object includes the new values. - **contact.deleted**: A contact was removed. The payload's `data.contact` object reflects the contact at the time of deletion. - **employee.status.changed**: An employee's live presence changed (for example from `available` to `on_call`, or when they enable/disable do-not-disturb). The payload's `data.employee` object matches the [employee model](/api/employees#the-employee-model), including `status`, `do_not_disturb`, `do_not_disturb_activated_at`, and `do_not_disturb_expires_at`. It also has a `call_id`: the call the employee is ringing for when `status` is `ringing`, the call they are on when `status` is `on_call`, and `null` otherwise. If an employee rings for several calls at once, `call_id` is the most recent one. The event also fires when `call_id` changes while `status` stays the same. - **number.registration_approved**: A business number's regulatory registration was approved by the carrier. The payload's `business_number` includes `id`, `number`, and `registration_status`. - **number.registration_rejected**: A business number's regulatory registration was rejected. The payload's `business_number` includes `id`, `number`, and `registration_status`. A sibling `reason` string explains the rejection. --- ## Payload structure Call, voicemail, Note, contact, and employee webhook deliveries are JSON POSTs with the following envelope: ```json { "event": "call.answered", "timestamp": "2026-05-15T14:22:33Z", "data": { "id": "01JVWX...", "call_control_id": "v3:...", "from": "+14155551234", "to": "+14155559876", "direction": "inbound", "state": "answered", "started_at": "2026-05-15T14:22:00Z", "answered_at": "2026-05-15T14:22:33Z", "duration": null, "summary": null, "transcription": null, "transcription_segments": null, "business_number_id": "01JVWX...", "business_number_name": "Sales", "business_number_number": "+14155559876", "business_number_number_formatted": "(415) 555-9876", "employees": [{ "id": "01JVWX...", "name": "Jane Smith", "first_name": "Jane", "last_name": "Smith" }], "initiated_by": null } } ``` For `call.*` events, the `data` object contains the full [call model](/api/calls#the-call-model). On `call.data_deleted`, deleted fields are already `null`, `data.deleted` identifies what was removed, and `data.reason` identifies why. For `voicemail.new`, `voicemail.transcription_done`, and `voicemail.data_deleted` events, the payload also includes a `voicemail` object nested inside `data` with the voicemail `id`, `from`, `business_number_name`, `business_number_number`, `transcription`, and `created_at`. The `transcription` is populated on `voicemail.new` and `voicemail.transcription_done`, and `null` after `voicemail.data_deleted`. For `contact.created`, `contact.updated`, and `contact.deleted` events, `data` contains a `contact` object with the full [contact model](/api/contacts#the-contact-model). For `employee.status.changed` events, `data` contains an `employee` object with the full [employee model](/api/employees#the-employee-model) (including `status`) plus `call_id`. For `number.registration_approved` and `number.registration_rejected` events, the top level contains a `business_number` object with `id`, `number`, and `registration_status`; rejected events also include a `reason` string. For `note.created` and `note.deleted`, `data` contains only a `note` object, not the enclosing call model. Both use the Note activity shape. A deletion keeps the Note's metadata but removes its content: ```json { "event": "note.deleted", "timestamp": "2026-05-15T14:22:33Z", "data": { "note": { "id": "0193f4cb-7777-7c00-9e3d-2b2b8a7f1c33", "type": "note", "text": null, "details": {}, "from": "+14085550199", "call_id": null, "seen_at": null, "created_at": "2026-05-15T14:20:00Z", "business_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01", "business_number_name": "Sales" } } } ``` For `note.created`, the same envelope uses `event: "note.created"` and includes the saved `text` and selected `details`. Partner tokens need `notes:read`; Note events do not require `calls:read` just because a Note has a `call_id`. Business-number names still require `business_numbers:read`. After a Shopify customer or store privacy deletion, affected contact deliveries use the contact's current `name` and `email`, or `null` if the contact no longer exists. Queued deliveries and retries cannot restore the deleted Shopify values. Historical delivery payloads and response bodies for affected contacts are cleared; attempt metadata remains. Your endpoint must handle deletion of any copies it already received. Registration events use this payload structure: ```json { "event": "number.registration_rejected", "business_number": { "id": "01JVWX...", "number": "+14155559876", "registration_status": "rejected" }, "reason": "Address does not match identity country" } ``` Your endpoint should return a `2xx` status code to acknowledge receipt. Transport errors and HTTP `408`, `429`, and `5xx` responses are retried with polynomial delays, with at most **5 total attempts** (the initial attempt plus up to 4 retries). Private-address and other URL-validation failures are not retried. Ordinary `4xx` responses other than `408` and `429` are not retried. Delivery resolves and checks every address using the caller-context endpoint's blocked-address policy before connecting to a validated address. This blocks private, loopback, link-local, carrier-grade NAT, benchmark, multicast, IPv4 `0.0.0.0/8` and `240.0.0.0/4`, IPv6 unspecified, and NAT64 `64:ff9b::/96` addresses. IPv4-mapped IPv6 addresses receive the same checks. Any blocked answer rejects the attempt, including hosts with mixed public and blocked DNS answers. Webhook payloads are sent with `Content-Type: application/json` and a `User-Agent: PhoneInc-Webhooks/1.0` header. --- ## Verify delivery signatures Every delivery, including synthetic tests and retries, includes these headers: ```text X-Phone-Inc-Timestamp: 1793016000 X-Phone-Inc-Signature: v1=<64 lowercase hexadecimal characters> ``` Save `signing_secret` from the successful `POST /api/v1/webhooks` response. To retrieve it later, send `PATCH /api/v1/webhooks/:id` with an empty JSON object (`{}`); the response returns the same secret without changing subscription settings. Existing subscriptions acquire a persistent secret on their first delivery or successful API update. Each subscription has its own secret, encrypted at rest. Dashboard pages do not display secrets; retrieve dashboard-created subscriptions' secrets through an authorized API-key update. Partner OAuth retrieval requires both `webhooks:write` and `webhooks:read` and is limited to the token's own installation. Read-only tokens cannot retrieve secrets. API keys and legacy tokens keep their existing company access. Lists and delivery diagnostics never return the secret. There is no rotation endpoint; create a replacement subscription and remove the old one if a secret is compromised. The `v1` value is the lowercase hexadecimal HMAC-SHA256 of the header timestamp, a literal period (`.`), and the **exact raw HTTP request body bytes**, using the subscription's secret as the key. Use the secret string as returned, not hex-decoded bytes. This matches the caller-context header convention, but webhook secrets are separate from caller-context signing secrets. Read the body before JSON parsing or middleware transformations. Reject missing or malformed headers, unsupported versions, and timestamps outside a short tolerance, for example **300 seconds** in either direction. Compute the HMAC over `timestamp + '.' + raw_body` and compare the full `v1=...` value in constant time. Parse and process JSON only after verification succeeds. ```python import hashlib import hmac import re import time def valid_webhook(raw_body: bytes, timestamp: str | None, signature: str | None, signing_secret: str) -> bool: if re.fullmatch(r"[0-9]{1,12}", timestamp or "") is None: return False if re.fullmatch(r"v1=[0-9a-f]{64}", signature or "") is None: return False if abs(time.time() - int(timestamp)) > 300: return False message = timestamp.encode("ascii") + b"." + raw_body digest = hmac.new(signing_secret.encode("ascii"), message, hashlib.sha256).hexdigest() return hmac.compare_digest("v1=" + digest, signature) ``` The header timestamp is the delivery attempt time in Unix seconds, not the event's JSON `timestamp`. Every retry computes a signature using the current attempt time and the exact body being sent; the subscription secret stays the same. A delayed retry can therefore pass the freshness check even when the original event is older than five minutes. Keep your receiver's clock synchronized. A timestamp tolerance limits replay age but does not stop replay within the allowed window. Deliveries are not exactly-once and have no universal event ID. Make domain changes idempotent and retain durable deduplication state suitable for your application. Do not use the signature or header timestamp as an event identifier: they can change between attempts. Acknowledge accepted events promptly with `2xx`; the [retry policy](#payload-structure) also applies to signed tests. --- ## List webhooks Returns all webhook subscriptions for your company, without signing secrets. ```bash curl https://app.phone.inc/api/v1/webhooks \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/webhooks', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }) ``` ```python import os, requests response = requests.get( "https://app.phone.inc/api/v1/webhooks", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) ``` ```ruby require 'net/http' uri = URI('https://app.phone.inc/api/v1/webhooks') response = Net::HTTP.get_response( uri, { 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY') }, ) ``` ```json [ { "id": "01JVWX...", "name": "Slack notifications", "url": "https://example.com/webhooks", "events": ["call.initiated", "call.answered", "voicemail.new"], "active": true, "created_at": "2026-05-15T10:00:00Z", "updated_at": "2026-05-15T10:00:00Z" } ] ``` --- ## Create a webhook Registers a new webhook subscription. The response includes its `signing_secret`; store it securely to [verify deliveries](#verify-delivery-signatures). ### Required attributes - **name** (`string`): A human-readable label for the webhook. - **url** (`string`): The HTTPS endpoint to receive events. - **events** (`array`): One or more event types to subscribe to. See [Events](#events). ```bash curl -X POST https://app.phone.inc/api/v1/webhooks \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Slack notifications", "url": "https://example.com/webhooks", "events": ["call.initiated", "call.answered"] }' ``` ```js const response = await fetch('https://app.phone.inc/api/v1/webhooks', { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Slack notifications', url: 'https://example.com/webhooks', events: ['call.initiated', 'call.answered'], }), }) ``` ```python import os, requests response = requests.post( "https://app.phone.inc/api/v1/webhooks", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, json={ "name": "Slack notifications", "url": "https://example.com/webhooks", "events": ["call.initiated", "call.answered"], }, ) ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/webhooks') http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true request = Net::HTTP::Post.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = { name: 'Slack notifications', url: 'https://example.com/webhooks', events: %w[call.initiated call.answered], }.to_json response = http.request(request) ``` ```json { "id": "01JVWX...", "name": "Slack notifications", "url": "https://example.com/webhooks", "events": ["call.initiated", "call.answered"], "active": true, "signing_secret": "f07b2e7e844d991e7df46ae01d3c5289a5b05aa71817f2f11b490be4457d22ad", "created_at": "2026-05-15T10:00:00Z", "updated_at": "2026-05-15T10:00:00Z" } ``` --- ## Update a webhook Updates an existing webhook. You can change the URL, events, or toggle it on/off. Successful responses include the persistent `signing_secret`. Send `{}` to retrieve it without changing settings; updates do not rotate it. Partner OAuth tokens that change the destination URL, change subscribed events, or resume delivery must cover the resulting subscription's effective delivery scopes: its saved scope ceiling intersected with the installation's current permissions. This includes event resource reads and embedded employee, contact, department, and business-number details, plus call data included with voicemail events. Changing events requires these permissions even if the destination was changed in an earlier request. A token issued before additional consent may lack these permissions even when it has `webhooks:read` and `webhooks:write`. Insufficient scopes return `403` without changing the subscription or its ceiling. Name-only edits and pausing delivery do not require these extra data scopes. The same restriction applies through MCP. API keys and legacy tokens can update only customer-managed subscriptions; application-owned subscriptions return `404`, including empty updates to retrieve signing secrets. ### Optional attributes - **name** (`string`): New label for the webhook. - **url** (`string`): New endpoint URL. - **events** (`array`): Replace the subscribed events list. - **active** (`boolean`): Set to `false` to pause delivery, `true` to resume. ```bash curl -X PATCH https://app.phone.inc/api/v1/webhooks/01JVWX... \ -H "X-Api-Key: $PHONE_INC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"active": false}' ``` ```js const response = await fetch( 'https://app.phone.inc/api/v1/webhooks/01JVWX...', { method: 'PATCH', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ active: false }), }, ) ``` ```python import os, requests response = requests.patch( "https://app.phone.inc/api/v1/webhooks/01JVWX...", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, json={"active": False}, ) ``` ```ruby require 'net/http' require 'json' uri = URI('https://app.phone.inc/api/v1/webhooks/01JVWX...') http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true request = Net::HTTP::Patch.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') request['Content-Type'] = 'application/json' request.body = { active: false }.to_json response = http.request(request) ``` ```json { "id": "01JVWX...", "name": "Slack notifications", "url": "https://example.com/webhooks", "events": ["call.initiated", "call.answered"], "active": false, "signing_secret": "f07b2e7e844d991e7df46ae01d3c5289a5b05aa71817f2f11b490be4457d22ad", "created_at": "2026-05-15T10:00:00Z", "updated_at": "2026-05-15T14:30:00Z" } ``` --- ## Delete a webhook Permanently removes a webhook subscription. Events will stop being delivered immediately. API keys and legacy tokens can delete only customer-managed subscriptions. Deleting an application-owned subscription requires the owning installation's OAuth credentials; other credentials receive `404`. ```bash curl -X DELETE https://app.phone.inc/api/v1/webhooks/01JVWX... \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch( 'https://app.phone.inc/api/v1/webhooks/01JVWX...', { method: 'DELETE', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }, ) ``` ```python import os, requests response = requests.delete( "https://app.phone.inc/api/v1/webhooks/01JVWX...", headers={"X-Api-Key": os.environ["PHONE_INC_API_KEY"]}, ) ``` ```ruby require 'net/http' uri = URI('https://app.phone.inc/api/v1/webhooks/01JVWX...') request = Net::HTTP::Delete.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true response = http.request(request) ``` Returns `204 No Content` on success. --- ## List delivery attempts Returns the latest 50 recorded attempts for one subscription, newest first. Each retry is a separate attempt. There are no pagination parameters. No attempts returns `[]`; queued work does not appear until an attempt is recorded. API keys can inspect webhooks in their company. Partner OAuth requires `webhooks:read` and can inspect only the installation's own subscriptions. Unknown or inaccessible subscriptions return `404`. Diagnostics do not expand the subscription's saved scope ceiling or current installation permissions, and do not include the request payload. Partner OAuth responses also omit `response_body`, including transport and validation error text, because arbitrary receiver text can echo customer data. API keys and legacy tokens retain that field. In the dashboard, open **Webhooks** and the subscription's delivery history to inspect the same latest 50 attempts. Refresh after sending a test to see its result. ### Attempt properties - **event** (`string`):Event name, including `webhook.test` for synthetic tests. - **test** (`boolean`):Whether this is a synthetic test. - **success** (`boolean`):True only for an HTTP `2xx` response. - **response_code** (`integer | null`):Destination HTTP status, or `null` when no response was received. - **response_body** (`string | null`):Response body or transport/validation error text, truncated to 1,000 characters. Omitted for partner OAuth tokens. - **created_at** (`timestamp`):ISO 8601 time the attempt was recorded. - **delivered_at** (`timestamp | null`):ISO 8601 delivery time for a successful attempt; otherwise `null`. ```bash curl https://app.phone.inc/api/v1/webhooks/01JVWX.../deliveries \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/webhooks/01JVWX.../deliveries', { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }) ``` ```python import os, requests response = requests.get( 'https://app.phone.inc/api/v1/webhooks/01JVWX.../deliveries', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, ) ``` ```ruby require 'net/http' uri = URI('https://app.phone.inc/api/v1/webhooks/01JVWX.../deliveries') response = Net::HTTP.get_response(uri, 'X-Api-Key' => ENV.fetch('PHONE_INC_API_KEY')) ``` ```json [ { "event": "webhook.test", "test": true, "success": true, "response_code": 200, "response_body": "OK", "created_at": "2026-10-22T12:00:00Z", "delivered_at": "2026-10-22T12:00:00Z" } ] ``` --- ## Send a test delivery Queues a safe synthetic `webhook.test` event for this subscription only. No request body is needed. It contains `test: true`, a timestamp, and `data.message: "Synthetic Phone.inc connectivity test. No customer data."` It does not replay a real event, fan out to other subscriptions, or mutate customer records. `webhook.test` is not a subscribable production event. API keys and legacy tokens can test only their company's customer-managed subscriptions; application-owned subscriptions return `404`. Partner OAuth requires both `webhooks:write` and `webhooks:read`, and can test only its own installation's subscriptions. The installation must remain connected and webhook management must be allowed by both the subscription's saved scope ceiling and the installation's current scopes. Tests do not bypass those checks. Returns `202 Accepted` when queued, not when delivered. Unknown or inaccessible subscriptions return `404`. A paused subscription returns `422` with `errors.base` asking you to resume it; unavailable installation management permission returns `422` asking you to reconnect. Missing token scopes return `403`. Use **Send test delivery** in dashboard delivery history for customer-managed subscriptions. Application-owned subscriptions are hidden from the customer dashboard; publishers inspect their [application delivery log](/applications#webhook-delivery-log). Tests use the normal delivery job, URL/private-address protections, and retry policy. Inspect [delivery attempts](#list-delivery-attempts) for the destination's response. ```bash curl -X POST https://app.phone.inc/api/v1/webhooks/01JVWX.../test \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch('https://app.phone.inc/api/v1/webhooks/01JVWX.../test', { method: 'POST', headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY }, }) ``` ```python import os, requests response = requests.post( 'https://app.phone.inc/api/v1/webhooks/01JVWX.../test', headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, ) ``` ```ruby require 'net/http' uri = URI('https://app.phone.inc/api/v1/webhooks/01JVWX.../test') request = Net::HTTP::Post.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } ``` ```json { "status": "queued", "event": "webhook.test", "test": true } ``` --- # Applications Connect your SaaS to your customers' Phone.inc accounts. Customers choose which data to share, and your application gets access through OAuth—not their passwords or API keys. If you only need an internal script for your own company, use an [API key](/api/authentication). This guide is for products that other Phone.inc companies install. ## What you can build Use the existing API, provide customer information when the phone rings, or do both: - **Log calls in a CRM.** Read call history, recordings, transcripts, and summaries to attach a conversation to the right customer record. - **Create follow-up workflows.** React to call or voicemail [webhooks](/api/webhooks), create a task in your SaaS, or send a text with the customer's permission through the [texting API](/api/texting). - **Show customer context during a call.** Return open support tickets, recent orders, or account details from your SaaS so the employee knows who's calling. - **Build a shared activity view.** Read [inbox activity](/api/inbox) for the resource types the customer grants, without requesting unrelated company data. Permissions are resource-specific. You do not need API access to provide caller context, and API-only applications do not need a caller-context endpoint. ## Register your application Application management is available to every company. Phone.inc can turn it off for a company; that hides application management, blocks creation, edits, deletion, and secret rotation, and makes the [webhook delivery log API](#list-application-webhook-deliveries) return `403`. Existing customer installations, OAuth, customer API access, and disconnect remain available. Sign in under your ordinary Phone.inc company account. Open [Applications](https://app.phone.inc/applications), alongside API keys, and choose [New application](https://app.phone.inc/applications/new). No separate partner account or marketplace listing is required. Give your app a name and description, register its exact OAuth callback URLs, and enable only the permissions it needs. No scopes are selected by default. For example, `calls:read` is labeled **Read calls, recordings, and transcripts** and includes summaries and search. `voicemails:read` is labeled **Read voicemails, recordings, and transcripts**. See the [25-scope catalog and dependencies](/api/oauth#scopes) before choosing permissions. Save the client ID, client secret, and separate context signing secret securely when shown. Secrets are shown only once on creation or rotation. Keep them on your server, never in browser code or logs. Manage an existing application at `/applications/:id/edit`, including its client ID, secret rotation, and deletion. The [OAuth reference](/api/oauth#company-owned-saas-applications) covers callback restrictions and credential management. ## Let customers connect Add a Connect to Phone.inc action in your SaaS. The installation flow is: 1. Your server creates a fresh OAuth `state` and S256 PKCE challenge, tied to the signed-in SaaS user. 2. Redirect the customer to Phone.inc's `/oauth/authorize` with your client ID, registered callback, and a nonempty subset of your enabled scopes. 3. Any authenticated employee in the customer company can approve consent. They see the publisher, application, and requested permissions. Caller-context permission explicitly discloses that caller phone numbers will be sent to your app. 4. Validate `state` at your callback. Exchange the authorization code on your server at `/oauth/token`, authenticating with your client secret and supplying the PKCE verifier. 5. Store the returned tokens and map `installation_id` and `company_id` to the correct tenant in your SaaS. An installation is the connection between one customer company and your application. Repeated authorization updates that installation rather than creating duplicates. Customers see it on their **Integrations** page. Tokens cannot be redirected to another company by changing an ID in a request. Follow the [confidential-client OAuth flow](/api/oauth#step-1-build-the-authorization-url) for exact parameters, token exchange, refresh, and revocation. [Public MCP dynamic registration](/api/oauth-public#register-an-oauth-client) is a different flow; do not use it to register your SaaS application. ## Call the API Send the installation's access token as `Authorization: Bearer ` to `https://app.phone.inc/api/v1`. Use the existing [API reference](/api), including [calls](/api/calls), [voicemails](/api/voicemails), [contacts](/api/contacts), and [integrations](/api/integrations). Resource-page examples use API keys; your SaaS uses its customer's OAuth bearer token instead. Read scopes include the resource's content: calls include recordings, transcripts, summaries, and search; voicemails include recordings and transcripts; messages include texts. Embedded contact, employee, department, and business-number details still need their own read permissions. Combined inbox reads need at least one supported resource read and show only granted types. See [inbox permissions](/api/inbox) for filtering, search, and seen updates. You can also use existing [MCP tools](/mcp) with partner tokens. They delegate to the same API permissions; they do not bypass consent or add credential-management tools. ## Provide caller context To show information from your SaaS when a customer receives a call, configure your application's HTTPS context endpoint and request `caller_context:provide`. A context-only installation can request just that scope. Phone.inc sends a signed lookup containing the caller's phone number and installation identity to your endpoint. Verify the signature with the context signing secret before looking up data. Resolve the installation to your SaaS tenant, then return structured fields or tables, such as recent orders or open tickets. Never use the caller's phone number alone to choose a tenant. The signing secret is separate from your OAuth client secret. Implement the exact request, signature verification, and response format in [signed partner lookups](/api/caller-context#signed-partner-lookups). To fetch context from Phone.inc instead, use the [caller-context API](/api/caller-context) with `caller_context:read`; that scope does not permit outbound caller-number delivery. ## Operate the connection Access tokens last one hour. Refresh them server-side and store the latest returned tokens. Keep each customer's credentials and data isolated by installation. Any authenticated employee in the customer company can approve installation through OAuth consent or disconnect an application from **Integrations**. Disconnect revokes installation tokens and pending codes, stops caller lookups, deletes its webhook subscriptions, and blocks queued deliveries and retries. Reconnecting cannot revive old deliveries; create new subscriptions. Each subscription belongs to its creating installation and keeps a scope ceiling that can shrink but never expand. See [webhook permissions](/api/webhooks#partner-oauth-permissions). Register subscriptions server-side after OAuth consent using the installation's token. Application-managed webhooks are hidden throughout the customer dashboard. Only your installation's OAuth credentials can change, delete, retrieve signing secrets, or test them; customer API keys and legacy tokens retain listing and per-subscription delivery-history access for their own company. Publishers inspect delivery metadata in the log below. Adding enabled permissions keeps installations, existing tokens, caller context, and webhooks working. Existing tokens and refresh cannot gain scopes. Your SaaS must start fresh S256 PKCE authorization for the full desired scope set, not just the additions. Consent distinguishes additional, already approved, and omitted (removed) permissions. Approval updates the same installation; cancelling changes nothing. Optionally register an HTTPS `connect_url`, labeled **Connection URL**, pointing to your SaaS's OAuth start page, not its callback. That page uses your own user session, state, and fresh PKCE. When additional scopes are enabled, **Integrations** shows **Additional permissions available** and links **Update permissions** to this URL, or instructs customers to open your SaaS if none is configured. Disconnected apps can reconnect through the same URL. The dashboard does not grant permissions or automatically expand tokens. Reducing installation or application permissions revokes only credentials containing removed scopes; unaffected narrower tokens and installations continue. Removing every installed permission disconnects that installation. Webhook scope ceilings and event lists shrink permanently: readding scopes cannot revive removed access on old subscriptions. Expanded webhook access needs a new subscription. Secret rotation, application deletion, installation revocation, and changes to callback URLs or the context endpoint still disconnect access. Changing the name, description, or Connection URL alone does not. Historical call context remains available. Follow the [installation lifecycle reference](/api/oauth#disconnect-rotate-and-reauthorize). ## Webhook delivery log Open **Applications**, select your application, and choose **Webhook delivery log**. It shows attempts across all companies using that application, including retries and synthetic tests. Filter by customer company, event, outcome, or time period, and page through older attempts. The daily chart at the top splits successful and errored attempts into stacked bars, with totals and exact counts on hover or keyboard focus. It follows the company, event, outcome, and time filters, but always counts every matching attempt, not just the current page. Days use UTC, including zero-activity days. The first and current day can be partial because time periods are rolling windows. Each retry counts separately; connection failures count as errors. The table shows the customer company ID, event, outcome, and attempt time. API and MCP entries also include the log ID and subscription ID. Company IDs match those returned during OAuth authorization; company names are never included. HTTP `200`–`299` counts as success; a `null` response code means a connection failure. Payloads, raw receiver responses, endpoint URLs, and secrets are never copied into this log. Metadata is recorded asynchronously, so recent attempts may take a short time to appear. It remains available for 30 days after each attempt, even if a customer disconnects or a subscription is deleted. Expired metadata is hidden immediately and purged hourly. Deleting the application or customer company removes its metadata. Logging starts when this feature is deployed; earlier delivery history is not backfilled. The publishing company can also read this log through the API below or the `list_application_webhook_deliveries` MCP tool. Use the publisher's API key or legacy company credential. Customer installation OAuth tokens cannot access the cross-customer log, even when the publisher installs its own application. The publisher's **Applications** feature must be enabled. ## List application webhook deliveries Returns up to 50 attempts, newest first, for an application owned by the authenticated publishing company. `application_id` is its client ID from **Applications**. Each retry is a separate entry. Unknown applications and applications owned by another publisher return `404`. Installation OAuth tokens and companies without **Applications** access receive `403`. Invalid status, period, or cursor returns `422`. The response also includes `daily_counts`, ordered oldest first. Each entry has `date` (a UTC `YYYY-MM-DD` string), `successful` (HTTP 200–299), and `errored` (other status codes or connection failures). It includes zero-activity days and counts all matching attempts regardless of `before` or the 50-row delivery limit. The same company, event, outcome, and period filters apply to both the rows and counts. ### Optional attributes - **company_id** (`string`):Filter by a customer company's public ID. - **event** (`string`):Filter by an exact event name, including `webhook.test`. - **status** (`string`):`success` for HTTP 200–299, or `failure` for other codes and connection failures. - **period** (`string`):`hour`, `day`, `week`, or `month`. Defaults to `month` (the last 30 days). - **before** (`string`):Use `next_before` from the previous response for older attempts. Keep the same filters. `next_before: null` means there are no more results. Cursors expire with their log entries. ```bash curl "https://app.phone.inc/api/v1/applications/$CLIENT_ID/webhook_deliveries?status=failure&period=day" \ -H "X-Api-Key: $PHONE_INC_API_KEY" ``` ```js const response = await fetch( `https://app.phone.inc/api/v1/applications/${clientId}/webhook_deliveries?status=failure&period=day`, { headers: { 'X-Api-Key': process.env.PHONE_INC_API_KEY } }, ) const log = await response.json() ``` ```python import os import requests response = requests.get( f'https://app.phone.inc/api/v1/applications/{client_id}/webhook_deliveries', params={'status': 'failure', 'period': 'day'}, headers={'X-Api-Key': os.environ['PHONE_INC_API_KEY']}, ) log = response.json() ``` ```ruby require 'net/http' require 'json' uri = URI("https://app.phone.inc/api/v1/applications/#{client_id}/webhook_deliveries?status=failure&period=day") request = Net::HTTP::Get.new(uri) request['X-Api-Key'] = ENV.fetch('PHONE_INC_API_KEY') response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) } log = JSON.parse(response.body) ``` ```json { "deliveries": [ { "id": "019a22d0-1234-7000-8000-111122223333", "company": { "id": "0193f4c0-1234-7000-8000-111122223333" }, "webhook_id": "019a22c0-1234-7000-8000-111122223333", "event": "call.ended", "success": false, "response_code": 503, "created_at": "2026-10-28T10:30:00Z" } ], "next_before": null, "daily_counts": [ { "date": "2026-10-27", "successful": 0, "errored": 0 }, { "date": "2026-10-28", "successful": 0, "errored": 1 } ] } ``` --- # Call quality: no audio or dropped calls No sound on a call, or calls that drop? Most of the time it comes down to the connection, a permission or a Bluetooth device. Go through the checklist below. If it keeps happening, report the call to us, and we'll look at exactly what went wrong. **Short on time? Ask Ping.** Click [Ping](/help/ping) in the bottom-right corner of the app and ask "Find my call with +45 12 34 56 78 this morning and show me the details". Still stuck? Click the headset icon at the top of the panel and tick **Include my assistant conversation**, so we see what you've already found. Using Claude or ChatGPT instead? Connect it with the [MCP guide](/help/mcp-guide) and ask the same thing. Prefer to do it yourself? Here's how. ## Quick checklist - [ ] **Update the app.** Many audio fixes come in new versions. - [ ] **Check your connection.** Calls run over the internet, so a weak signal means choppy or silent audio. Move closer to your router or find a spot with better coverage. - [ ] **Try Wi-Fi vs mobile data.** If one is weak, switch to the other and call again. Poor mobile signal but good Wi-Fi? Make sure Wi-Fi is on and connected. - [ ] **Check Bluetooth.** Headsets, earbuds and car systems can grab the audio without you noticing. Disconnect Bluetooth and try the call on your phone itself. - [ ] **Check the microphone permission.** If the other person can't hear you, make sure the app is allowed to use the microphone. See [Mobile app: install](/help/mobile-app-install). - [ ] **Turn off VPN.** A VPN can block or slow down call audio. Turn it off and try again. - [ ] **Restart the app.** Close it fully, open it again and make a quick test call. Short dropouts don't end your call. If your connection comes back within about 10 seconds, the call carries on. On iPhone, if a call does drop, you'll see a short message saying why. Calling the person back often works fine. Please still report the call that failed, so we can find the cause. ## Travelling abroad You can use the app abroad, as long as you have internet. Mobile signal is often weaker when you travel, so audio can cut out. - Use good Wi-Fi where you can. - If mobile data is weak, switch to Wi-Fi before you call. - Not on Wi-Fi? Check that roaming data is allowed on your phone. ## Report a bad call to us The fastest way to get help is "Report a problem" in our [web app](https://app.phone.inc). You pick the calls that went wrong, so we can see exactly what happened. It's in the web app in your browser, not in the mobile app. 1. Open the [web app](https://app.phone.inc) and click "Report a problem" (the bug icon). 2. Under "Related calls", select the call or calls that went wrong. 3. Under "What went wrong?", write what happened in a sentence or two. For example: "The customer couldn't hear me, and the call dropped after 10 seconds." 4. Add anything that might matter: Wi-Fi or mobile data, Bluetooth headset or car, which country you were in. 5. Click "Send report". Can't send the report from your browser? An ad blocker might be stopping it. Turn it off for our app, or write to us instead. If you write to us, include: - The date and time of the call - The number you called or that called you - Your phone model and app version ## Related - [MCP guide](/help/mcp-guide) - [Ping: the assistant in your app](/help/ping) - [Mobile app: install](/help/mobile-app-install) Need a hand? Call us on +45 35 15 35 25 (Denmark) or +1 (650) 671-6488 (United States), weekdays 9:00 to 16:00 CET, or write to support@phone.inc. Emails get a reply the same business day. --- # Call routing: queues, forwarding, opening hours Every call to your number follows three rules you set: what happens when someone calls, what happens when nobody answers, and what happens when you're closed. You set all three per number under [Settings](https://app.phone.inc/settings). **Short on time? Ask Ping.** Click [Ping](/help/ping) in the bottom-right corner of the app and tell him what you want, like "close our line at 3 pm on Fridays" or "send unanswered calls to voicemail after 30 seconds". Not sure how your calls work today? Ask "Explain my call routing". Using Claude or ChatGPT instead? Connect it with the [MCP guide](/help/mcp-guide) and ask the same thing. Prefer to do it yourself? Here's how. New to us? Start with the [Quick-start guide](/help/quick-start). It covers the basics and how to write a good welcome message. ## Choose what happens when someone calls You pick one call flow for your business hours. Here are your options: | Option | What the caller gets | | --- | --- | | **Play welcome greeting, then transfer to…** | Hears your welcome, then rings the colleagues or department you pick | | **Transfer to…** | Rings the colleagues or department right away | | **Go to phone menu** | Hears your welcome and presses 1 to 9. Each key goes to colleagues, a department, voicemail or a message | | **Go to voicemail** | Hears your greeting and can leave a message | | **Play message and end call** | Hears your message, then the call ends | | **Go to receptionist** | Talks to your AI receptionist (Beta), available on Pro with separate AI usage charges | To set it up: 1. Go to [Settings](https://app.phone.inc/settings) and pick your number under **Numbers**. 2. Open **When you're open**. 3. Under **When someone calls**, pick an option and add your text and who should take the calls. 4. Save. The very next call follows your new setup. Tip: each message can be up to 150 words or 1,500 characters, which is about one minute of speech. ### Colleagues or a department You can send calls to colleagues you pick or to a department, but not both. When you pick colleagues, all of them who are free ring at the same time. If several people call at once, they're answered in the order they called. A department has one shared queue. Callers are answered in the order they called, and any free colleague in the department can take the next call. If several of your numbers send calls to the same department, they share that queue. You create and edit departments under [Departments](https://app.phone.inc/departments). You can't set a main colleague who always gets the call first. But there's a simple way around it: send calls to that colleague, and under **If no one answers** send them on to the others after 15 or 30 seconds. More on that in the next section. ### While callers wait By default, callers hear a ringtone while they wait for someone to answer. Prefer music? Open **While callers wait** on your number and pick **Music** instead of **Ringtone**. You can't upload your own music. ## AI receptionist The AI receptionist is in beta. Use it for incoming calls, when you're closed, or if no one answers. You'll need [Pro](/help/free-vs-pro#ai-receptionist-usage). AI usage is $0.29 USD/min, billed by connected seconds, separate from Pro and phone charges. 1. Open [Receptionists](https://app.phone.inc/receptionists) and click **Create receptionist**. Give it a name and choose one of the 32 [supported languages](/api/receptionists#supported-languages). Each receptionist uses one primary language, without automatic switching during calls. 2. Pick a **Tone**: **Friendly and professional** (the default), **Formal and direct**, or **Fun and light**. Tone changes how it words things, not its voice or your greeting. Whatever you pick, it stays calm and straightforward with upset callers and sensitive topics. 3. Under **Greeting and voice**, write how it should greet callers and choose Mark, Simon, Ellen or Sarah, just like on your business numbers. Simon is the default. Press play to hear your greeting in that voice. Accents vary by language, and real calls can sound different from the preview. Changing the language doesn't translate or change your greeting, so have a native speaker review the text before use. 4. Under **Calls**, tick **Take a note** if you want it to take written messages, and pick the details to ask for. Then pick the departments and colleagues it may transfer to. You'll see who's in each department and who's available right now. For each colleague, add a short line on when calls should go to them, like "handles billing and refunds". Need a new department? Click **Create department** without leaving the page. 5. Under **Business knowledge**, add your public website for it to search, a few lines about your business, and up to 20 questions and answers. Your answers come before what's on your website. Website imports have limits and may not cover every page. 6. Click **Create receptionist**, or **Save receptionist** when you change one later. 7. Under [Settings](https://app.phone.inc/settings), pick a number. In **When you're open**, **When you're closed**, or **If no one answers**, choose **Go to receptionist** and select your receptionist. Save. ### Talk to it before it takes calls The right side of the receptionist page is a live preview. Click **Talk to** followed by your receptionist's name, allow your microphone, and talk to it like a caller would. Ping stands in for your receptionist on screen, and you can read the conversation as it goes. The preview uses what's on the page, even changes you haven't saved yet. Changing a setting ends the preview, so start a new one to hear the change. Nothing in a preview happens for real. Transfers and notes are only simulated, so nobody is called and no note is saved. Every colleague you picked shows as available, and the preview can't check your opening hours, search your website or look up earlier calls. A preview lasts up to five minutes, and your company can start three every five minutes. Previews aren't charged as AI usage. ### What it can do on calls It can answer from your saved knowledge, check the number's current opening hours, and check selected colleagues' availability before trying a warm transfer with a private introduction. Department transfers join the normal shared queue. When a caller mentions their last call, it can look up that number's latest completed call summary and team members. A phone-number match doesn't verify who is calling. Notes land in your inbox as notes, separate from voicemails, and there's no recording. When note taking is on, it asks for every detail you picked. Callers can say no, and the note is still saved. It keeps the number they called from, and fills in a contact's name, email or company only where those are blank. After saving, it asks if there's anything else before it ends the call. It can collect a preferred callback time, but it doesn't schedule a callback or promise when someone will respond. Note taking is optional and starts turned off. Choose how you hear about new notes under [Notifications](https://app.phone.inc/account/notifications). You can also ask [Ping](/help/ping), "Use Ellen's voice for our receptionist", or make the same request through the [MCP guide](/help/mcp-guide). Changing the voice doesn't rewrite your greeting or change your number's voice. Save the receptionist to apply your choice to its next calls; calls already in progress keep their current voice. Receptionists don't get caller context from integrations and can't look up live orders or bookings, act through external MCP servers, or guarantee that sales calls are blocked. Each AI session has a ten-minute limit. Set your number's **If no one answers** fallback for when it can't continue. Recording and transcription follow the number's settings. A call's transcript starts with who answered and how long the call took, then shows who said what and when. Short lines show what the receptionist did and how that went, like "Checked opening hours · Closed" or "Milo transferred to Kat · Connected", including attempts that didn't work. ## When nobody answers **If no one answers** decides what happens if no one picks up in time. You choose how long it rings and where the call goes next. 1. Go to [Settings](https://app.phone.inc/settings), pick your number and open **If no one answers**. 2. Under **Ring for**, pick how long it rings: 15 or 30 seconds, 1 minute, 5, 10, 20, 30 or 45 minutes, or 1 hour. Pick **Off** to let calls ring until the caller hangs up. 3. Under **When time runs out**, pick what happens next: transfer to other colleagues or a department, voicemail, a phone menu, or a message before hanging up. 4. Save. This rule only kicks in when a call is sent to colleagues or a department and nobody picks up. That includes transfers from a phone menu key or outside business hours. It doesn't run when the call goes to voicemail or a message. For voicemail greetings, see [Voicemail setup](/help/voicemail-setup). ## Outside business hours Set your opening hours for each day, and choose what callers get when you're closed. 1. Go to [Settings](https://app.phone.inc/settings) and pick your number. 2. Open **Business hours**, turn each day on or off and set the opening and closing time. Your hours follow the **Timezone** set on the same page. 3. Closed on public holidays? Tick **Treat public holidays as Sundays**. Taking your own days off? Add them as [custom holidays](#custom-holidays). Save. 4. Open **When you're closed** and, under **When someone calls**, pick voicemail, a message before hanging up, a transfer, or a phone menu. 5. Save. ### Public holidays With **Treat public holidays as Sundays** ticked, we use your Sunday hours on national public holidays in your number's country. So if you're closed on Sundays, holiday callers get your **When you're closed** setup. When a holiday falls on a weekend and the day off moves to a weekday, that weekday counts too. It's off until you tick it, and you can untick it any time. Your AI receptionist follows the same setting when it checks whether you're open. [Ping](/help/ping) can switch the setting on or off for you too. ### Custom holidays Closed for a day of your own, or away on vacation? Add it as a custom holiday, and we use your Sunday hours on those days too. This works whether or not **Treat public holidays as Sundays** is ticked. 1. Go to [Settings](https://app.phone.inc/settings), pick your number and open **Business hours**. 2. Under **Holidays**, click **+** next to **Custom holidays**. 3. Give it a name, like "Summer vacation", and pick a start date and an end date. For a single day, use the same date for both. 4. Click **Add holiday**, then **Save**. To remove one, click the bin icon next to it, then **Save**. Your AI receptionist follows your custom holidays too, and [Ping](/help/ping) can add or remove them for you. ## Several languages on one number You don't need a separate number for each language. A phone menu does the job: 1. Open **When you're open** on your number and pick **Go to phone menu**. 2. Write a welcome in both languages, for example "For English, press 1. For Danish, press 2." 3. Point each key to the right colleagues, department, voicemail or message. 4. Open **Voice** on your number and pick the one you like. Number greetings support the same 32 [languages as receptionists](/api/receptionists#supported-languages). Listen to your text before saving, because pronunciation and accents vary. The voice you pick reads every greeting on that number. Under **Recordings and transcripts**, **Number language** sets the language for your number's greetings and messages. Private employee introductions use your receptionist's language instead. Changing the number language doesn't translate saved greeting text. Transcripts detect the spoken language automatically, and call summaries are written in the language spoken on the call. The menu has one level, so each key takes callers straight to where they need to go. ## Forwarding to an external number Right now, calls can go to your colleagues and departments in the app. You can't forward calls to a phone number outside your account. ## Related - [MCP guide](/help/mcp-guide) - [Ping: the assistant in your app](/help/ping) - [Quick-start guide](/help/quick-start) - [Voicemail setup](/help/voicemail-setup) Need a hand? Call us on +45 35 15 35 25 (Denmark) or +1 (650) 671-6488 (United States), weekdays 9:00 to 16:00 CET, or write to support@phone.inc. Emails get a reply the same business day. --- # Cancel or change your subscription You can change or cancel your plan whenever you like. There's no binding period. **Want a quick overview first?** Click [Ping](/help/ping) in the bottom-right corner of the app and ask "Which business numbers do we have?" to see what you're paying for. Ping can't change your plan for you, but the headset icon at the top of his panel gets you straight to us. Using Claude or ChatGPT? Connect it with the [MCP guide](/help/mcp-guide) and ask the same question. You upgrade to Pro, go back to Free and remove employees yourself in the app. On any plan, you can also close a number yourself, unless it's your last number or it's still being moved to us. To close your whole account, write to us. Here's how. Not sure which plan fits? See [Free vs Pro: what's included](/help/free-vs-pro). ## Upgrade to Pro 1. Go to [Upgrade to Pro](https://app.phone.inc/billing/new) in the app. 2. Check the monthly breakdown. It's based on the employees you have right now. 3. Add your card details and confirm. Tip: if you've never had Pro, you start with a 14-day free trial. ## Add or remove employees Pro is billed per employee, at $14 per month each. You add employees under [Employees](https://app.phone.inc/employees) in the app. To stop paying for someone, delete them there. Their seat stays active until the end of the current billing period. ## Go back to Free Want to go back to Free? Free covers 1 employee and 1 business number, so first bring your account down to that: delete the employees you don't need and close your extra numbers, as described on this page. Then: 1. Go to [Billing](https://app.phone.inc/billing) and click **Manage billing**. It opens Stripe, our payment provider. 2. Cancel your Pro plan there. Pro keeps running until the end of the current billing period, and then you're on Free. There's no refund for that period. ## Cancel your subscription Only want to stop paying for Pro? Cancel it under **Manage billing**, as described above, and you keep your account on Free. Want to close your whole account? Write to support@phone.inc and let us know. Your account stays active until the end of the current billing period, and then it closes. There's no refund for that period. When your account closes, we close your numbers too. Want to keep a number? Move it to your new provider before you cancel. See how below. Only need fewer people or numbers? You don't have to cancel: delete the employees you don't need, or close the numbers you don't use, as described on this page. ## Delete a number Don't need a number anymore? You can close it yourself, as long as it isn't your last number: 1. Go to [Settings](https://app.phone.inc/settings) and pick the number under **Numbers**. 2. Under **General**, click **Terminate**, then **Confirm termination**. Here's what happens next on Pro: - The number stays active until the end of the current billing period. There's no refund for that period. - After that, it closes for good, and we can't get it back. - Your call history is kept. - Your subscription and your other numbers keep running as usual. - Your first number is always included. If you close it, that discount moves to one of your other numbers. Changed your mind? Click **Cancel termination** before the period ends, and we'll keep the number. On Free, the number closes right away, and we can't get it back. Your call history is kept. Still moving the number to us, or want to close your last number? Write to support@phone.inc with the number, and we'll help you close it. ## Take your number to another provider Your number is yours, and you can take it with you. Moving it away from us is free. Here's how it works: 1. Ask your new provider to move (port) the number from us. 2. Keep your subscription with us until the move is done. 3. Cancel with us once your new provider confirms the number has moved. Important: your account has to be active while the number moves. If you cancel your account or delete the number first, it closes and can't be moved. Moving a number to us instead? Read [Move your number to us](/help/move-your-number-to-us). ## Invoices Each time you pay, we email you a receipt and an invoice. You'll find all your invoices in Stripe too: go to [Billing](https://app.phone.inc/billing) and click **Manage billing**. That's also where you change your card. Prices are in USD, and VAT is added where it applies. ## Related - [MCP guide](/help/mcp-guide) - [Ping: the assistant in your app](/help/ping) - [Free vs Pro: what's included](/help/free-vs-pro) Need a hand? Call us on +45 35 15 35 25 (Denmark) or +1 (650) 671-6488 (United States), weekdays 9:00 to 16:00 CET, or write to support@phone.inc. Emails get a reply the same business day. --- # Countries we offer numbers in Right now you can get a number in Denmark, the Netherlands, the UK, the US and Canada. You can also bring your existing number from any of them. Just start the move in the app. **Short on time? Let Ping start the move.** Click [Ping](/help/ping) in the bottom-right corner of the app and say "Move my number +45 12 34 56 78 to us". Using Claude or ChatGPT instead? Connect it with the [MCP guide](/help/mcp-guide) and ask the same thing. Here's where we offer numbers today. | Country | Get a new number | Move your number to us | | --- | --- | --- | | Denmark | Yes | Yes | | Netherlands | Yes | Yes | | United Kingdom | Yes | Yes | | United States | Yes | Yes | | Canada | Yes | Yes | You choose the country when you [get your number in the app](https://app.phone.inc/business_numbers/new). See [Getting started with Phone.inc](/help/getting-started) or the [Quick-start guide](/help/quick-start). ## Good to know - **More countries are coming.** We're working on them now. We don't have dates yet, but we'll let you know as soon as a new country is ready. - **Moving a number takes a bit longer.** See [Move your number to us](/help/move-your-number-to-us). - **Need a country that isn't listed?** Write to support@phone.inc. Many of you have asked for Germany and Spain, and every request helps us decide what comes next. - **Price is the same for every country.** Your first number is included, and every extra number is $9 per month. See [Free vs Pro](/help/free-vs-pro). ## Related - [MCP guide](/help/mcp-guide) - [Ping: the assistant in your app](/help/ping) - [Getting started with Phone.inc](/help/getting-started) - [Quick-start guide](/help/quick-start) Need a hand? Call us on +45 35 15 35 25 (Denmark) or +1 (650) 671-6488 (United States), weekdays 9:00 to 16:00 CET, or write to support@phone.inc. Emails get a reply the same business day. --- # Desktop notifications for calls Working in another tab or app? Turn on desktop notifications, and your computer tells you when a call comes in. Click the notification to jump straight back to Phone.inc. Desktop notifications live in your browser, so you switch them on yourself. [Ping](/help/ping) can't do it for you, and neither can Claude or ChatGPT through the [MCP guide](/help/mcp-guide). One thing they can help with: Do Not Disturb hides desktop notifications, so if they've gone quiet, ask Ping to "Turn off do not disturb". Here's how to set them up. ## Turn on desktop notifications 1. Open the [web app](https://app.phone.inc) in your browser and go to [Notifications](https://app.phone.inc/account/notifications). 2. Under **Desktop notifications**, switch on **Incoming calls**. 3. Your browser asks if Phone.inc may show notifications. Click **Allow**. When a call comes in and you're in another tab or app, you'll see **Incoming call** with the caller's number. It stays on screen while the call rings. If you're already looking at Phone.inc, you won't get a notification, because the call shows right there in the app. A few things to know: - **Keep Phone.inc open in a tab.** The tab can be in the background, but if you close it, notifications stop. - **It's only for you, in this browser.** Use more than one computer or browser? Switch it on in each of them. - **Do Not Disturb pauses them.** While you're on Do Not Disturb, you won't get desktop notifications. ## Send a test Once notifications are on, you'll see **Test notification** on the same page. Click **Send test**, and a notification should pop up on your screen. The app then asks **Did you see it?**: - **Yes:** you're all set. - **No:** your computer is probably hiding it. See below. ## Not seeing them? - **The switch is greyed out and says notifications are blocked.** You clicked **Block** when your browser asked, or blocked them earlier. Allow notifications for app.phone.inc in your browser's site settings. In most browsers, you'll find them by clicking the icon to the left of the web address. - **It says "Not supported in this browser".** Try an up-to-date version of another browser. - **Mac:** go to System Settings > Notifications and allow your browser. Chrome can show up twice in that list, so check both. - **Windows:** go to Settings > System > Notifications and allow your browser and its notification banners. - **Focus or Do Not Disturb on your computer**, and screen sharing, can hide notifications too. - **Our Do Not Disturb** pauses them. Check the switch in the app, or ask [Ping](/help/ping). - **The Phone.inc tab is closed.** Open the web app again and leave the tab open. After you change a setting, send another test. Want calls to reach you away from your desk? Install the [mobile app](/help/mobile-app-install), and calls ring on your phone too. ## Related - [MCP guide](/help/mcp-guide) - [Ping: the assistant in your app](/help/ping) - [Mobile app: install](/help/mobile-app-install) - [Call routing](/help/call-routing) Need a hand? Call us on +45 35 15 35 25 (Denmark) or +1 (650) 671-6488 (United States), weekdays 9:00 to 16:00 CET, or write to support@phone.inc. Emails get a reply the same business day. --- # Free vs Pro: what's included Free gets you one employee and one business number, so you can take calls. Pro is for when you need more people, more numbers, outbound calls or an AI receptionist. Receptionist usage is charged separately. **Not sure what you use today?** Ask [Ping](/help/ping), the assistant in the bottom-right corner of the app, "Which business numbers do we have?" or "Who are our employees?". Ping and your own AI assistant work on both plans. See the [MCP guide](/help/mcp-guide). Here's what each plan includes. ## Free and Pro side by side | | Free | Pro | | --- | --- | --- | | Price | $0 | $14 per employee per month | | Employees | 1 | As many as you need | | Business numbers | 1 | More than 1 | | Take calls on your business number | Yes | Yes | | Outbound calls | No | Yes, 10 hours of local calls included | | AI receptionist (Beta) | No | Available, plus $0.29/min AI usage | | Binding period | None | None | Prices are in USD, excluding VAT. A few features are Pro only. You'll find the full list on our [pricing page](https://www.phone.inc/pricing). Just need a number to get your business going? Free is made for that. See [how the free business phone number works](https://www.phone.inc/free-business-phone-number). ## AI receptionist usage The AI receptionist is in beta and available on Pro. Open [Receptionists](https://app.phone.inc/receptionists) to set one up. On Free, that page shows what a receptionist can do, with an **Upgrade to Pro** button. AI usage is $0.29 USD per minute, billed by connected seconds rather than rounded up to whole minutes. This is on top of your Pro subscription and any phone charges. The included local calling hours don't include AI usage. There's nothing extra to sign up for: we add AI usage to your Pro subscription automatically once you create a receptionist. Test conversations in the receptionist's live preview aren't charged. You can set up notes (written messages from callers), business knowledge and transfers to selected colleagues or department queues. Receptionists don't receive caller context from integrations, look up live orders or bookings, or schedule callbacks. Read [how to use a receptionist](/help/call-routing#ai-receptionist). ## Try Pro free for 14 days Not sure Pro is for you yet? Try it free for 14 days before you pay. Here's how: 1. Go to [Upgrade to Pro](https://app.phone.inc/billing/new) in the app. 2. Check the monthly breakdown. It's based on the employees you have right now. 3. Add your card details and click **Start 14-day free trial**. You need a card to start the trial, and each company can try Pro once. The trial covers the price per employee. Outbound calls beyond your 10 included hours are still charged during the trial. AI receptionist usage during the trial isn't charged. New to us? Start with the [Quick-start guide](/help/quick-start). ## How seats work Pro is billed per employee, so each employee who has joined is one seat at $14 per month. Invites are free until your colleague accepts. Add or remove employees under [Employees](https://app.phone.inc/employees) in the app. When you delete an employee, their seat stays active until the end of the current billing period. ## Extra numbers Your first business number is included. Every extra number is $9 per month, whichever country it's in. See [Countries we offer numbers in](/help/countries). Already have a number you'd like to keep? Read [Move your number to us](/help/move-your-number-to-us). If you remove an extra number, it stays active until the end of the period you've paid for. After that, it closes for good. Read more in [Cancel or change your subscription](/help/cancel-or-change-your-subscription). ## Related - [MCP guide](/help/mcp-guide) - [Ping: the assistant in your app](/help/ping) - [Quick-start guide](/help/quick-start) - [Cancel or change your subscription](/help/cancel-or-change-your-subscription) Need a hand? Call us on +45 35 15 35 25 (Denmark) or +1 (650) 671-6488 (United States), weekdays 9:00 to 16:00 CET, or write to support@phone.inc. Emails get a reply the same business day. --- # Getting started with Phone.inc Getting set up only takes a few steps: create your account, pick a number, invite your colleagues and install the app. **Short on time? Ask Ping.** Once you're signed in, click [Ping](/help/ping) in the bottom-right corner of the app and tell him what you want, like "Add my colleagues Anna and Jonas" or "Send calls to voicemail outside our opening hours". Using Claude or ChatGPT instead? Connect it with the [MCP guide](/help/mcp-guide) and ask the same thing. Prefer to do it yourself? Here's how. ## Before you start It helps to have these ready: - Your company name and full company address. Our number supplier needs them to register your number. - Your colleagues' email addresses. - Your smartphone (iPhone or Android). ## Set up your phone system 1. **Get your invite.** You can't sign up on your own yet. Join the [waitlist](https://app.phone.inc/waitlist), and when it's your turn, we send you an invite email ourselves. Open it and click **Claim your invite**. The link works once, and only for you. Then fill in your details and click **Create account**. Told you're already on the waitlist? You've joined before, so look for our invite email, also in your spam folder. Can't find it? Write to support@phone.inc. 2. **Get your number.** Choose **Get a new number**, or **Port existing number** to bring the one you already have with you. See [Move your number to us](/help/move-your-number-to-us) and [Countries we offer numbers in](/help/countries). 3. **Choose your plan.** Start on Free, or try Pro free for 14 days. See [Free vs Pro](/help/free-vs-pro). 4. **Register your company name.** Use your real company name and full address, then click **Create my account**. A new number can't go live without them. You can update your address later in [Company details](https://app.phone.inc/company). 5. **Invite your colleagues.** Go to [Employees](https://app.phone.inc/employees) and add your colleagues by email. If some of them share calls, group them in [Departments](https://app.phone.inc/departments). 6. **Set up your main number.** Go to [Settings](https://app.phone.inc/settings) and pick your number under **Numbers**. Then decide what happens to your calls: - **When you're open**: your welcome message, phone menu and who the call goes to during business hours. - **When you're closed**: what callers hear outside business hours. - **If no one answers**: where the call goes if nobody picks up, like voicemail. 7. **Install the mobile app.** [Download the app](https://www.phone.inc/get-app) on your iPhone or Android phone and log in with the same account. Calls to your business number now ring in the app. ## Good to know - The Free plan includes 1 employee and 1 number. Want more colleagues, more numbers or outgoing calls? Upgrade to Pro in [Billing](https://app.phone.inc/billing/new). See [Free vs Pro](/help/free-vs-pro). - Until our supplier approves your registration, a new number can play "not in use". That usually takes up to 48 hours. - Moving an existing number takes a bit longer. Keep your current provider until we give you a moving date. ## Next steps - [MCP guide](/help/mcp-guide) - [Ping: the assistant in your app](/help/ping) - [Quick-start guide](/help/quick-start) - [Move your number to us](/help/move-your-number-to-us) - [Countries we offer numbers in](/help/countries) - [Free vs Pro](/help/free-vs-pro) Need a hand? Call us on +45 35 15 35 25 (Denmark) or +1 (650) 671-6488 (United States), weekdays 9:00 to 16:00 CET, or write to support@phone.inc. Emails get a reply the same business day. --- # MCP guide: connect Phone.inc to your AI assistant Busy day? Connect your phone system to your AI assistant, and you can check calls, read voicemails and change your setup just by asking. It takes about two minutes to set up, and from then on you can skip the clicking around. **Already in our app?** Then there's nothing to connect. [Ping](/help/ping), the assistant in the bottom-right corner, can do everything on this page. He can also get a call ready for you, draw charts and put you in touch with us. ## Why it helps You already use your AI assistant for email and planning. Once your phone system is connected too, it can answer questions about your calls and change your setup for you. A few things you can ask: - "Who called while I was in a meeting from 10 to 12?" - "Summarise yesterday's calls and tell me who I need to call back." - "Did anyone leave a voicemail about an order today?" - "We close at 3 pm on Fridays from now on. Update our opening hours." - "Who is +45 12 34 56 78?" You get the answer in a few seconds, in plain language, and you don't have to open the app. Read more on our [MCP page](https://www.phone.inc/product/mcp). ## What MCP is MCP (Model Context Protocol) is an open standard that lets an AI assistant connect to other tools. Here, that tool is your phone system. ## What you need - An account with us and at least one business number. New here? Start with the [Quick-start guide](/help/quick-start). - An AI assistant that supports custom MCP connectors, for example Claude or ChatGPT. - Our MCP server address: `https://app.phone.inc/mcp` It works on every plan, Free and Pro. ## How to connect ### In Claude 1. Open Claude and go to **Settings**, then **Connectors**. 2. Choose **Add custom connector**. 3. Give it a name, for example "Phone.inc", and paste `https://app.phone.inc/mcp` as the URL. 4. Leave **Authentication** on **Sign in now** and **OAuth client** on **Register automatically**. Don't choose **Use Claude's published identity**, because it doesn't work with us. 5. Click **Add**, then **Connect** if Claude asks. A browser window opens. 6. Log in with the user you use in our app, and approve access. 7. Start a new chat, check the connector is switched on, and ask something like "Who called me today?" Didn't connect the first time? Click **Connect** again. If you get the same error, remove the connector and add it again. Using Cursor or an API key? See [MCP for developers](/mcp). ### In ChatGPT and other assistants The steps are pretty much the same in any assistant that supports custom MCP connectors: 1. Find the place to add a connector or app in your assistant's settings. The name and location vary between assistants. 2. Add a new custom connector with `https://app.phone.inc/mcp` as the server URL. 3. Log in with the user you use in our app when asked. 4. Make sure the connector is switched on in your chat, then ask your first question. Custom connectors work on every ChatGPT plan. Can't find the option? Check your assistant's own help pages for "custom connector" or "MCP". ## What your assistant can do Your assistant can help with your calls, voicemails, contacts, team and call routing. Here's what you can ask for: | Area | What you can ask for | | --- | --- | | Calls | Find and search calls by number, date or topic. Read the transcription and summary of a call. See who answered and if it came in outside opening hours. | | Voicemails | List new voicemails, read them as text, and clean them up. | | Inbox | See unseen calls and voicemails in your [Inbox](https://app.phone.inc/inbox), and the full history with one number. | | Callers and contacts | Look up who a number is, including info from connected tools such as Shopify, Dinero, Attio or your own [Custom Endpoint](/api/custom-caller-context). Find someone by name or a few digits of their number. Add, edit or remove [contacts](https://app.phone.inc/contacts). | | Call routing | Change who gets calls during and outside opening hours, what happens when no one answers, your phone menu and your greetings. See [Call routing](/help/call-routing). | | Opening hours | Change your weekly opening hours, choose whether national public holidays follow your Sunday hours, and add your own holidays. | | AI receptionist (Beta) | On Pro, set up and change your AI receptionist, and read the messages it takes. See [AI receptionist](/help/call-routing#ai-receptionist). | | Team | Invite, edit or remove [employees](https://app.phone.inc/employees), manage [departments](https://app.phone.inc/departments), and turn do not disturb on or off, also for a set time. | | Other settings | Manage [webhooks](https://app.phone.inc/webhooks), start moving an existing number to us, and get the setup link for an [integration](https://app.phone.inc/integrations). | | Live calls | Help with a warm transfer to a colleague while you're on a call. | | Feedback to us | When our tools or docs get in its way, your assistant can send us a short report, and check later whether we've fixed it. It's told to leave out personal details like phone numbers. | ## What it can't do - Make a phone call for you. - Record your voice. Greetings set through your assistant are read aloud by one of our voices. If you have a recorded greeting, a new text greeting replaces it. - Finish an integration setup for you. It gives you a link, and you finish the login in your browser. - Set special opening times for one date, like 10 to 2 on Christmas Eve. Your own holidays follow your Sunday hours, and so do national public holidays when **Treat public holidays as Sundays** is ticked. See [Custom holidays](/help/call-routing#custom-holidays). - Change your plan or billing. Do that on the [billing page](https://app.phone.inc/billing/new). See [Free vs Pro](/help/free-vs-pro). - Use features your plan doesn't include. For example, the AI receptionist needs Pro. ## Safety and control You stay in charge: - **It checks with you first.** Your assistant is told to confirm with you before it changes call routing. It also needs your clear OK before it closes a number or moves a number to us. For other changes, like editing a contact or deleting a voicemail, your assistant's own approval prompts are your check, so keep them switched on. - **Changes are live right away.** A new routing setup applies from the next call. Read the summary your assistant shows you before you say yes. - **It only sees your company.** The connection is tied to the user you log in with, so your assistant only sees your company's data. - **You can disconnect at any time.** Just remove or switch off our connector in your assistant's settings, in the same place you added it. ## Related - [Ping: the assistant in your app](/help/ping) - [Quick-start guide](/help/quick-start) - [Webhooks and API reference](/help/webhooks-and-api) Need a hand? Call us on +45 35 15 35 25 (Denmark) or +1 (650) 671-6488 (United States), weekdays 9:00 to 16:00 CET, or write to support@phone.inc. Emails get a reply the same business day. --- # Mobile app: install Install our app on your iPhone or Android phone, allow microphone and notifications, and keep it updated. That helps prevent missed or silent calls. New here? Start with the [Quick-start guide](/help/quick-start). **Short on time? Ask Ping.** In the web app, click [Ping](/help/ping) in the bottom-right corner and ask "Which calls did I miss today?" or "Who needs a call back?". He isn't in the mobile app. Using Claude or ChatGPT instead? Connect it with the [MCP guide](/help/mcp-guide) and ask the same thing. Prefer to check things yourself? Here's how. ## Install the app **iPhone** 1. Open the [download page](https://www.phone.inc/get-app) on your iPhone, or search for us in the App Store. 2. Install the app. 3. Log in with the same email you use on the web. **Android** 1. Open the [download page](https://www.phone.inc/get-app) on your Android phone, or search for us in Google Play. 2. Install the app. 3. Log in with the same email you use on the web. **Keep it updated.** Many call problems are already fixed in a newer version. If something feels off, update the app first. ## Permissions and phone settings The app needs a few permissions to ring and to carry your voice, so allow them when it asks. Said no by mistake? You can change it in your phone's settings. - **Microphone:** without it, the other person can't hear you. - iPhone: Settings > Phone.inc > Microphone. - Android: Settings > Apps > Phone.inc > Permissions > Microphone. - **Notifications:** without them, incoming calls may not show on your screen. - iPhone: Settings > Notifications > Phone.inc. - Android: Settings > Apps > Phone.inc > Notifications. - **Battery and background (Android):** some phones pause apps in the background to save battery. Set the app's battery usage to "Unrestricted" (the wording varies by phone maker), so calls can reach you even when the app is closed. - **Do Not Disturb:** your phone's Do Not Disturb or Focus mode can silence incoming calls. Add Phone.inc as an allowed app, or turn the mode off when you need to take calls. We also have our own Do Not Disturb, so you can pause business calls without changing your phone's settings. ## Staying logged in You only get calls in the app while you're logged in. After an update, open the app once and check you're still logged in. If you've been logged out, just log in again with the same email you use on the web. ## Related - [MCP guide](/help/mcp-guide) - [Ping: the assistant in your app](/help/ping) - [Quick-start guide](/help/quick-start) - [Call quality: no audio or dropped calls](/help/call-quality) Need a hand? Call us on +45 35 15 35 25 (Denmark) or +1 (650) 671-6488 (United States), weekdays 9:00 to 16:00 CET, or write to support@phone.inc. Emails get a reply the same business day. --- # Move your number to us Good news: you can bring your number with you. We call this porting, and we handle most of it for you. **Short on time? Ask Ping.** Click [Ping](/help/ping) in the bottom-right corner of the app and say "Move my number +45 12 34 56 78 to us". Using Claude or ChatGPT instead? Connect it with the [MCP guide](/help/mcp-guide) and ask the same thing. Prefer to do it yourself? Here's how. Here's how it works: - You start the move in the app. We ask you for a couple of documents, check them and send the request to your current provider. - Once your current provider says yes, we get a porting date and let you know. - Until then, your number works just like it does today. After the switch, your calls come to us. Once we have your documents, it usually takes 1 to 3 weeks. Some providers are quicker than others. ## How to get started You can move a number on both Free and Pro. See [Free vs Pro](/help/free-vs-pro). We can move numbers from the countries listed in [Countries we offer numbers in](/help/countries). 1. Start the move in the app: go to [Get a new number](https://app.phone.inc/business_numbers/new), choose **Port existing number**, enter your number under **Number to port** and click **Continue with porting**. For a Danish number, also enter your CVR number. You get a temporary number right away, so you can get started while we move your number. 2. Set up the temporary number the way you want it, like opening hours and who answers. Your own number gets the same setup when it moves. The [Quick-start guide](/help/quick-start) shows you how. 3. We reach out and ask for the documents on the checklist below: a signed authorization form (LOA) and your latest invoice. 4. We check them, send the request to your current provider and keep you posted by email. Already have a number with us? You can move your old number onto it instead. Go to [Settings](https://app.phone.inc/settings), pick the number and use **Bring your number to Phone.inc**. Your setup stays the same, and the number you have with us now closes once your old number takes over. **What we need from you** - [ ] The number you want to move, with country code - [ ] Your CVR number, for a Danish number. You enter it when you start the move. - [ ] A signed authorization form (also called LOA or power of attorney). We send it to you, so you just sign it. - [ ] Your latest invoice from your current provider for that number (not needed for Danish numbers) Tip: use the exact name, company and address your current provider has on file, even if you've moved since. A mismatch is the most common reason a request gets rejected. Moving a US number? We handle those by hand, and we email you exactly what we need. **Numbers in a series** Some numbers, like 70 numbers, are part of a series, and your provider may not be able to move just one. If so, ask them to release it from the series, or send us the full series and we'll find a way together. **Moving a Danish mobile number** You can move a Danish mobile number too, and use it in our app. We need one of these: - [ ] The SIM card number (ICC number) for the number, or - [ ] A signed power of attorney, if you don't have a SIM card number. This is common if the number is only used as a main number. The contact person on the power of attorney must be the person registered with your current provider, so double-check before you sign. **Important:** When a mobile number moves to us, it becomes a business number for good. The SIM card stops working, and you lose all private settings and services tied to that number with your mobile provider. From then on, calls to the number come in through our app. ## Don't cancel your old subscription yet Keep your subscription with your current provider until the move is complete. If you cancel too early, you can lose the number. Once your number has moved to us, you cancel the rest of your old agreement yourself. ## What happens on porting day 1. **The switch.** It happens on the confirmed date, at any time of day. Keep your phone and the app close. 2. **Your setup comes along.** Your number takes over the settings from your temporary number, so calls follow your setup right away. 3. **Your old provider lets go.** They stop handling calls to the number once the move is done. 4. **Your temporary number closes.** You don't need it anymore, so it closes once your own number has moved. 5. **You get an email.** We email you on the day to tell you your number is being moved. 6. **Give it a quick call.** Check that your number rings the right people. ## Check the status You get an email from us when the porting date is confirmed, and again on porting day. Want an update in between? Write to support@phone.inc. ## Related - [MCP guide](/help/mcp-guide) - [Ping: the assistant in your app](/help/ping) - [Quick-start guide](/help/quick-start) - [Free vs Pro](/help/free-vs-pro) - [Countries we offer numbers in](/help/countries) Need a hand? Call us on +45 35 15 35 25 (Denmark) or +1 (650) 671-6488 (United States), weekdays 9:00 to 16:00 CET, or write to support@phone.inc. Emails get a reply the same business day. --- # Ping: the assistant in your app Ping is the AI assistant built into our app. Ask him about your calls, change your setup, get a chart or reach us, all in plain words. There's nothing to connect, and he's there on every plan, Free and Pro. A few things you can ask: - "Who called while we were closed?" - "Read me today's voicemails." - "We close at 3 pm on Fridays from now on." - "Show a graph of last week's calls." - "How did my call with Lars go, and what could I do better?" - "Call Sofia back." - "I'd rather talk to a person." ## Open Ping 1. Sign in to the [app](https://app.phone.inc) in your browser. 2. Click Ping in the bottom-right corner. You can also go straight to him with [app.phone.inc/?assistant=open](https://app.phone.inc/?assistant=open). 3. Type your question and press Enter. Or pick one of the suggestions, like **Summarize recent calls** or **Explain my call routing**. Ping keeps your conversations. Use **Conversation history** at the top of the panel to go back to one, and **New conversation** to start fresh. Ping lives in the web app. He isn't in the mobile app yet, but he's on his way. If Ping can't load, you'll see a small circular arrow where he usually sits. Click it to try again. The rest of the app keeps working in the meantime. ## What Ping can do Ping can do everything Claude or ChatGPT can do once you connect them with the [MCP guide](/help/mcp-guide), and a few things more. | Area | What you can ask for | | --- | --- | | Calls and voicemails | Find calls by number, date or topic. Read the transcription and summary of a call, or get a summary of your recent calls, worked out from their full transcripts. Read voicemails as text, and mark them as listened. | | Inbox | See unseen calls and voicemails in your [Inbox](https://app.phone.inc/inbox), and the full history with one number. | | Callers and contacts | Look up who a number is, including info from connected tools such as Shopify, Dinero or Attio. Find someone by name or a few digits of their number. Add, edit or remove [contacts](https://app.phone.inc/contacts). | | Call routing and opening hours | Explain how your numbers handle calls today. Change who gets calls, what happens when you're closed or no one answers, your phone menu, your greetings and your weekly opening hours. Choose whether national public holidays follow your Sunday hours, and add your own holidays. See [Call routing](/help/call-routing). | | AI receptionist (Beta) | On Pro, set up and change your AI receptionist, and read the messages it takes. See [AI receptionist](/help/call-routing#ai-receptionist). To hear it before your callers do, open it under [Receptionists](https://app.phone.inc/receptionists) and click **Talk to**, followed by its name. You can try changes before you save them. Ping shows up as your receptionist's face, and nothing in the test is real: no one gets transferred and no message is saved. | | Team | Invite, edit or remove [employees](https://app.phone.inc/employees), manage [departments](https://app.phone.inc/departments), and turn do not disturb on or off, also for a set time. | | Numbers | Start moving an existing number to us. See [Move your number to us](/help/move-your-number-to-us). | | Charts | Get an area, bar, line or pie chart in the chat, like calls per day last week. The numbers are counted from your real data. | | Calling | Ask Ping to call someone. He finds the number in your contacts and shows a call card. Click **Call**, and the call starts from your browser with your microphone. Calling out is part of Pro. See [Free vs Pro](/help/free-vs-pro). | | Integrations and webhooks | Get a card with a button to connect an [integration](https://app.phone.inc/integrations). You finish the login in a new tab, and the card tells you when it's connected. Manage [webhooks](https://app.phone.inc/webhooks) too. | | How-to questions | Ask how something works, from your setup to our API. Ping looks it up in our docs and links to the pages he used. | | Support | Ask for a person, or click the headset icon at the top of the panel. See [Talk to a person](#talk-to-a-person). | | Feedback to us | When Ping hits an error he can't get past, or you need something he can't do yet, he can write us a short report. Nothing is sent until you click **Confirm changes**, and he can check later whether we've fixed it. Want an answer from a person? Use [Talk to a person](#talk-to-a-person) instead. | Ping also knows which page you have open. With a number open in the app, you can just say "send this number to voicemail after 30 seconds". ### Talk to a person Click the headset icon, or ask Ping for a human. He shows our phone numbers, phone hours and email, and a short form. Write your question and click **Send to support**, and it comes straight to us with your name and email. Tick **Include my assistant conversation**, so you don't have to explain it all again. We reply by email. Nothing is sent until you submit the form. ## What Ping can't do - Call someone without you. He gets the call ready, and you click **Call**. - Record your voice. Greetings set through Ping are read aloud by one of our voices. If you have a recorded greeting, a new text greeting replaces it. - Finish an integration setup for you. You finish the login in your browser. - Set special opening times for one date, like 10 to 2 on Christmas Eve. Your own holidays follow your Sunday hours, and so do national public holidays when **Treat public holidays as Sundays** is ticked. See [Custom holidays](/help/call-routing#custom-holidays). - Change your plan or billing. Do that on the [billing page](https://app.phone.inc/billing/new). See [Free vs Pro](/help/free-vs-pro). - Turn on two-factor authentication or change your password. See [Two-factor authentication](/help/two-factor-authentication). - Use features your plan doesn't include. For example, the AI receptionist needs Pro. ## Safety and control You stay in charge: - **You confirm changes.** When you ask for a change, Ping shows a card with what he's about to do. Nothing happens until you click **Confirm changes**. Click **Cancel**, and nothing changes. - **Small things happen right away.** When you clearly ask for it, Ping turns do not disturb on or off, marks calls and voicemails as seen or listened, and adds or edits a contact without a card. - **Changes are live right away.** A new routing setup applies from the next call. Read the card before you click **Confirm changes**. - **It only sees your company.** Ping uses your login, so he only sees your company's data. ## Ping or your own AI assistant? Use Ping when you're already in the app. There's nothing to set up, and he can draw charts, get a call ready and put you in touch with us. Prefer to stay in Claude or ChatGPT? Connect it to us with the [MCP guide](/help/mcp-guide). It handles your calls and setup the same way, without opening our app. ## Related - [MCP guide](/help/mcp-guide) - [Getting started with Phone.inc](/help/getting-started) - [Call routing](/help/call-routing) - [Voicemail setup](/help/voicemail-setup) Need a hand? Call us on +45 35 15 35 25 (Denmark) or +1 (650) 671-6488 (United States), weekdays 9:00 to 16:00 CET, or write to support@phone.inc. Emails get a reply the same business day. --- # Quick-start: Set up your main number Give it 10 minutes to set up your main number: a short welcome, calls straight through to the right people, and a voicemail when you're closed or busy. Your main number is the one your customers call. You set things up per number, so a sales line or a second country can get its own setup later. **Short on time? Ask Ping.** Click [Ping](/help/ping) in the bottom-right corner of the app and tell him what you want, like "Set our opening hours to 9 to 16 on weekdays" or "Send calls to Anna and Mads". Using Claude or ChatGPT instead? Connect it with the [MCP guide](/help/mcp-guide) and ask the same thing. Prefer to do it yourself? Here's how. ## Set up your main number in 5 steps Go to [Settings](https://app.phone.inc/settings) and pick your number under **Numbers**. You'll decide what callers get when you're open, when nobody answers and when you're closed. 1. **Set your business hours and time zone.** Under **Business hours**, pick your days and times. Any day you switch off counts as closed. Closed on public holidays? Tick **Treat public holidays as Sundays** to use your Sunday hours on those days. See [Public holidays](/help/call-routing#public-holidays). 2. **Choose what happens when you're open.** Open **When you're open** and pick **Play welcome message and transfer to…**. Write a short welcome and choose who picks up: one or more colleagues, or a department. 3. **Check what callers hear while they wait.** Under **While callers wait**, choose **Ringtone** (the default) or **Music**. 4. **Set up "If no one answers".** Under **Ring for**, choose how long it rings. Then under **When time runs out**, pick **Go to voicemail** and write a short greeting. Keep the wait short, so callers aren't left on hold. 5. **Set up "When you're closed".** Write a greeting that says you're closed, when you open again, and invites a message. Hit save, and the very next call follows your new setup. **Tip:** Every message has a **Write** tab and a **Record** tab. Type your message and we'll read it aloud, or record your own. Typed text is easy to update when your hours change. ## What makes a good welcome message A good welcome message is short, tells callers they're in the right place, and gets them to a person fast. - **Say your name first.** "Hi, you've reached Hansen Plumbing." Callers want to know they dialled right. - **Keep it under 10 seconds.** About 20 to 25 words. Every extra second is someone waiting. - **Tell them what happens next.** "We'll put you through to a colleague." - **Sound like you.** Write it the way you'd say it on the phone. - **Several languages? Use a phone menu.** Callers press a key for their language. See [Call routing](/help/call-routing#several-languages-on-one-number). ## Welcome messages you can copy Swap in your own name and hours. | Situation | Example | | --- | --- | | Open | Hi, you've reached Hansen Plumbing. We'll put you through to a colleague right away. | | Open, with recording | Hi, you've reached Hansen Plumbing. We record calls so we can follow up. Putting you through now. | | No answer | We're busy right now. Leave your name and number, and we'll call you back today. | | Closed | Thanks for calling Hansen Plumbing. We're closed and open again at 8 tomorrow. Leave a message and we'll get back to you. | | Closed for holidays | We're closed for the holidays and back on 2 January. Leave a message and we'll call you when we're back. | Only promise a callback time you can keep. ## Test it 1. Call your main number from another phone during opening hours. You should hear your welcome message, and the right colleagues' phones should ring. 2. Let it ring without answering. Your voicemail greeting should play. 3. Set your hours so you're closed right now, then call again to hear your closed greeting. Don't forget to set your hours back. ## Next steps - [MCP guide](/help/mcp-guide): let your AI assistant check missed calls, summarise calls and change your setup for you. - [Ping: the assistant in your app](/help/ping): ask about your calls and change your setup without leaving the app. - [Call routing: queues, forwarding, opening hours](/help/call-routing) - [Voicemail setup](/help/voicemail-setup) - [Mobile app: install](/help/mobile-app-install) Need a hand? Call us on +45 35 15 35 25 (Denmark) or +1 (650) 671-6488 (United States), weekdays 9:00 to 16:00 CET, or write to support@phone.inc. Emails get a reply the same business day. --- # Two-factor authentication Two-factor authentication (2FA) adds an extra step when you log in: a code from an authenticator app on your phone. So even if someone gets hold of your password, they can't get into your account without that code. ## Turn on 2FA for your account You'll need an authenticator app on your phone, like Google Authenticator or Microsoft Authenticator. We don't send codes by text message. 1. If you don't have an authenticator app yet, install one. 2. In our app, go to your [account settings](https://app.phone.inc/account), choose to turn on two-factor authentication and enter your password. 3. Scan the code on your screen with the authenticator app. 4. Enter the 6-digit code from the app to confirm. Tip: have your authenticator app ready before you start. Once you begin, you need to finish the setup before you can use the rest of the app. ## Require 2FA for everyone in your company You can make 2FA mandatory for your whole team with the company setting "Require two-factor authentication" in your [company settings](https://app.phone.inc/company). When it's on: - Everyone in your company has to set up 2FA before they can keep using the app. - Anyone who hasn't set it up yet is asked to do so the next time they use the app. - If someone turns 2FA off on their own account, the app asks them to set it up again right away. We recommend it if several people share access to your business numbers, calls and voicemails. ## Turning 2FA off (and why it keeps asking) Turned off 2FA, and the app asks you to set it up again right away? That means your company requires 2FA for everyone. Your own setting can't override the company requirement. To make 2FA optional: 1. Someone turns off "Require two-factor authentication" in the [company settings](https://app.phone.inc/company). 2. Then you turn off 2FA in your [account settings](https://app.phone.inc/account). You'll need your password. The order matters. If you turn off your own 2FA first, the company requirement sends you straight back into setup. ## Save your backup codes When you turn on 2FA, you get a list of backup codes. Save them somewhere safe, like a password manager. Each code works once, and you can use one instead of the 6-digit code when you log in. ## Lost or new phone Lost the phone with your authenticator app, or got a new one without moving the app over? Log in with one of your backup codes instead of the code from the app. No backup codes left? A colleague can reset your 2FA under [Employees](https://app.phone.inc/employees): they open your details, choose "Reset 2FA" and confirm with their own password. You're then logged out everywhere and can set up 2FA again on your new phone. Work on your own, with no colleague who can help? Write to support@phone.inc, and we'll help you get back in. To avoid this next time, move your authenticator app to your new phone before you reset or hand in the old one. Many authenticator apps also have a backup option. ## Related - [MCP guide](/help/mcp-guide) - [Ping: the assistant in your app](/help/ping) - [Getting started with Phone.inc](/help/getting-started) Need a hand? Call us on +45 35 15 35 25 (Denmark) or +1 (650) 671-6488 (United States), weekdays 9:00 to 16:00 CET, or write to support@phone.inc. Emails get a reply the same business day. --- # Voicemail setup Voicemail lets callers leave a message when nobody picks up or when you're closed. You set it up per number, with a greeting for each situation. **Short on time? Ask Ping.** Click [Ping](/help/ping) in the bottom-right corner of the app and tell him what you want, like "Set a voicemail greeting for when we're closed" or "Summarize today's voicemails". Using Claude or ChatGPT instead? Connect it with the [MCP guide](/help/mcp-guide) and ask the same thing. Prefer to do it yourself? Here's how. Haven't set up your number yet? Start with the [Quick-start guide](/help/quick-start). ## Set up your greetings You can use a voicemail greeting in three places. Just set the ones you need. New numbers already send callers to voicemail when you're closed, with a ready-made greeting you can change. | When | Where to set it | | --- | --- | | Nobody answers in time | **If no one answers** | | You're closed | **When you're closed** | | Every call goes straight to voicemail | **When you're open** | 1. Go to [Settings](https://app.phone.inc/settings) and pick your number under **Numbers**. 2. Open **If no one answers**, **When you're closed** or **When you're open**. 3. Choose **Go to voicemail**. 4. Write your greeting. We'll read it aloud to callers, and you can listen to it before you save. 5. Save. Your next call gets the new greeting. For **If no one answers**, you also pick how long the call rings before it goes to voicemail, under **Ring for**: anywhere from 15 seconds up to 1 hour. Callers can leave a message of up to 5 minutes. ### Typed text or your own recording Type your greeting on the **Write** tab, and we'll turn it into speech. Prefer your own voice? Open the **Record** tab, click **Record greeting**, allow microphone access in your browser, and record it right there. A recording can be up to one minute. To replace it later, click **Record new**. Callers hear your text or your recording, never both. Save on the **Record** tab and they hear your recording. Save on the **Write** tab and they hear your text. A greeting can be up to 150 words or 1,500 characters, which is about a minute of speech. Shorter usually works better. For example: > Thanks for calling. We can't take your call right now. Leave your name and number, and we'll call you back. ## Where your voicemails show up New voicemails land in your [Inbox](https://app.phone.inc/inbox) with the recording and a written transcript, so you can read the message without playing it. Voicemails are always transcribed, even if transcripts are off for your calls. They're in the **Inbox** of our mobile app too. Looking for an old message? Search the Inbox, on the web or in the app, for a name, a number or a word the caller said. If a recording is only silence or noise, with no spoken words, we remove it and show the call as a missed call. ## Email notifications We email each new voicemail to everyone on your team, with the transcript, a link to open it and a link to call back. The email goes to the address on each person's account. Emails are on by default. Each person can turn them off for each business number: 1. Go to [Notifications](https://app.phone.inc/account/notifications) in your account settings. 2. In the **Voicemails** row under each number you don't need, untick **Email**. 3. Save. Do Not Disturb doesn't stop these emails. Untick **Email** if you don't want them. Written messages from your AI receptionist aren't voicemails. They're notes, with their own **Notes** row on the same page. ## Turn voicemail off Voicemail is only on where **Go to voicemail** is chosen. To turn it off, just pick something else there: 1. Go to [Settings](https://app.phone.inc/settings) and pick your number under **Numbers**. 2. Open **If no one answers**, **When you're closed** or **When you're open**. 3. Choose another option, like a message before hanging up or a transfer to your colleagues. 4. Save. ## Related - [MCP guide](/help/mcp-guide) - [Ping: the assistant in your app](/help/ping) - [Quick-start guide](/help/quick-start) - [Call routing: queues, forwarding, opening hours](/help/call-routing) Need a hand? Call us on +45 35 15 35 25 (Denmark) or +1 (650) 671-6488 (United States), weekdays 9:00 to 16:00 CET, or write to support@phone.inc. Emails get a reply the same business day. --- # Webhooks and API reference Want your phone system to talk to your own tools? Webhooks and our API make that possible. This page gives you the short version. The full reference lives in our [developer docs](/api). **Don't want to code? Ask Ping.** Click [Ping](/help/ping) in the bottom-right corner of the app and ask, like "Show me today's missed calls" or "Add a webhook that sends ended calls to our CRM". Using Claude or ChatGPT instead? Connect it with the [MCP guide](/help/mcp-guide) and ask the same thing. Prefer to build it yourself? Here's how. ## What you can do - **Webhooks:** get a message sent to your system the moment something happens, like a call ending or a transcription being ready. Good for filling your CRM, logging calls or alerting your team. - **API:** read and change your data from your own code, for example calls, voicemails, contacts, employees and call routing. - **Custom caller context:** show your own customer info to your team when a call comes in. - **Feedback:** when the API, an MCP tool or our docs get in the way, your code or AI agent can tell us, and check later whether we've fixed it. See [Feedback](/api/feedback). ## Webhook events You choose which events each webhook gets. Here are the ones people use most: | Event | Sent when | | --- | --- | | `call.answered` | A call is answered. `employees` shows who took it. | | `call.ended` | A call ends. | | `call.lost` | A call ends without being answered and without a spoken voicemail. A voicemail with only silence or noise counts as lost. | | `call.transcription_done` | The transcription of a call is ready. | | `call.summary_done` | The AI summary of a call is ready, with `summary` filled in. It's sent after the transcription, but deliveries can arrive out of order. Not sent when there's nothing meaningful to summarise. | | `voicemail.new` | A new voicemail arrives. | | `voicemail.transcription_done` | A voicemail has been turned into text. | | `employee.status.changed` | An employee's status changes, for example to ringing or on a call. Includes `call_id` while ringing or on a call. | | `contact.created`, `contact.updated`, `contact.deleted` | A contact is added, changed or removed. | There are more, like `call.initiated`, `call.queued`, `call.outside_business_hours`, and `note.created` when your AI receptionist takes a written message. You'll find the full list and payloads in the [webhooks docs](/api/webhooks). ## How to add a webhook 1. Set up a URL on your side that can receive POST requests. 2. Go to [Webhooks](https://app.phone.inc/webhooks) in the app and add a new webhook. 3. Give it a name, paste your URL and pick the events you want. 4. Save, then make a quick test call to check that events arrive. Your URL should answer with a 2xx status. If it can't be reached or answers with a server error, a timeout (408) or a rate limit (429), we try again with a longer wait each time, up to 5 tries in total. Every delivery is signed, so you can check that it really came from us. See [Verify delivery signatures](/api/webhooks#verify-delivery-signatures). You can also create and manage webhooks through the API, or ask [Ping](/help/ping) or your AI assistant to do it for you. ## Custom caller context (Custom Endpoint) With a Custom Endpoint, your team sees your own customer info when a call comes in. You give us a JSON endpoint, and we call it with the caller's number on every incoming call. 1. Build an endpoint that looks up a phone number in your system and returns JSON. Follow the [endpoint contract](/api/custom-caller-context#endpoint-contract). 2. Make sure it accepts numbers in international format (E.164), like `+4512345678`. The `+` arrives URL-encoded as `%2B`. 3. In the app, go to [Integrations](https://app.phone.inc/integrations) and add **Custom Endpoint**. 4. Use the built-in test to check that your endpoint answers as expected, then save. Tip: if nothing shows on incoming calls, the most common cause is an endpoint that doesn't handle the `+` or `%2B`. Prefer a ready-made integration? We also connect to Shopify, Dinero and Attio. ## Authentication How you get access depends on what you're building: - **Your own scripts and integrations:** use an API key. Create one under [API keys](https://app.phone.inc/api_keys) in the app and send it with every request. See [Authentication](/api/authentication). - **A product other customers connect to (multi-tenant):** register it as an application under [Applications](https://app.phone.inc/applications) in the app, and your customers connect their accounts with OAuth. See [Applications](/applications) and the [OAuth docs](/api/oauth). ## Related - [MCP guide](/help/mcp-guide) - [Ping: the assistant in your app](/help/ping) - [Developer docs](/api) - [Authentication](/api/authentication) - [Webhooks](/api/webhooks) - [Applications](/applications) - [OAuth](/api/oauth) - [Custom caller context](/api/custom-caller-context) - [Feedback](/api/feedback) - [API overview](https://www.phone.inc/product/api) on our website Need a hand? Call us on +45 35 15 35 25 (Denmark) or +1 (650) 671-6488 (United States), weekdays 9:00 to 16:00 CET, or write to support@phone.inc. Emails get a reply the same business day. --- # MCP Phone.inc exposes a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server so AI assistants can read your account data and take actions on your behalf. The MCP endpoint sits on the same host as the REST API and uses the same credentials. MCP is built for AI clients — Claude Desktop, Cursor, and similar tools. If you're writing your own integration, the [REST API](/api/quickstart) is usually simpler. ## Setup The MCP server URL is `https://app.phone.inc/mcp`. Nothing to install — it's a remote HTTP endpoint. Pick your client below and connect once. You'll authenticate with Phone.inc the same way as the REST API: an [API key](/api/authentication) you paste into a config file, or **OAuth** where the client opens a browser sign-in for you. Claude uses OAuth automatically; Cursor uses an API key in `mcp.json`. ### Claude Desktop 1. Open **Claude** → **Settings** → **Connectors**. 2. Click **Add custom connector**. 3. Enter the server URL: `https://app.phone.inc/mcp` 4. Keep **Sign in now** under Authentication and **Register automatically** under OAuth client. Leave request headers empty and Advanced settings unchanged. 5. Click **Add**, then **Connect** if prompted. Claude opens a browser window — sign in to Phone.inc and approve access. 6. Start a new chat, make sure the Phone.inc connector is enabled, and try: *"List my business phone numbers."* Claude registers itself via [dynamic client registration](/api/oauth-public#register-an-oauth-client) and stores a refresh token. You don't need to create an API key or OAuth app by hand. Don't choose **Use Claude's published identity**: Phone.inc does not currently support Client ID Metadata Documents (CIMD). **No sign-in** and **Sign in when needed** are not the recommended settings because every Phone.inc MCP request requires authentication. ### Cursor Add the server to your MCP config — either `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` in a project root: ```json { "mcpServers": { "phone-inc": { "url": "https://app.phone.inc/mcp", "headers": { "Authorization": "Bearer phk_YOUR_API_KEY" } } } } ``` Create an API key at [app.phone.inc/api_keys](https://app.phone.inc/api_keys) and replace `phk_YOUR_API_KEY`. Restart Cursor after saving — Phone.inc tools should appear in the agent tool list. --- ## Endpoint The MCP server uses **Streamable HTTP** in stateless mode: - **URL:** `https://app.phone.inc/mcp` - **Methods:** `POST` for JSON-RPC requests (`tools/list`, `tools/call`, `initialize`, and so on) - **Accept header:** `application/json, text/event-stream` - **Content-Type:** `application/json` Responses are returned as `application/json` (not SSE) because the server runs in stateless mode — each request is self-contained and no session is required. `GET` and `DELETE` on `/mcp` are not used in stateless mode (`GET` returns `405 Method Not Allowed`). ## Authentication Every MCP request must be authenticated. Use the same credentials as the [public REST API](/api/authentication): - **API key** — send `X-Api-Key: phk_...` or `Authorization: Bearer phk_...` - **OAuth bearer token** — send `Authorization: Bearer `. [Public MCP clients](/api/oauth-public) use the `api` scope; [company-owned applications](/api/oauth) use their granted resource scopes. Public MCP clients keep their existing `api` access. Company-owned partner applications instead use [resource-specific OAuth scopes](/api/oauth#scopes); tool calls follow the same API action permissions and response-field redaction. `integration_setups` actions are unavailable to partner OAuth tokens even with `integrations:read`, while installed-integration reads remain allowed. App credential management stays dashboard-only and is excluded from MCP. Resource-specific permissions apply to the existing tools rather than adding a second catalog. Partner tokens use the same 25 scopes as the API. Call reads include recordings, transcripts, summaries, and search; voicemail reads include recordings and transcripts; message reads include texts; Note reads include text and collected details. Combined inbox tools filter results and seen updates to readable and writable resource types respectively, with contact metadata and text search requiring `contacts:read`. See [inbox permissions](/api/inbox) and [Applications](/applications). Unauthenticated requests receive `401 Unauthorized` with a `WWW-Authenticate` header pointing at our protected-resource metadata: ```http WWW-Authenticate: Bearer realm="Phone.inc MCP", resource_metadata="https://app.phone.inc/.well-known/oauth-protected-resource/mcp", scope="api" ``` MCP clients use that URL to discover the authorization server and start the OAuth flow. The metadata document at `/.well-known/oauth-protected-resource/mcp` advertises `resource: https://app.phone.inc/mcp`. --- ## Tools Call `tools/list` to see what's available. The server has 83 account API tools, two read-only documentation tools, and one read-only support-contact tool, for 86 tools when AI receptionist features are enabled. Account tools mirror the public REST API, with request and response shapes matching the corresponding endpoint documented below. ### Documentation Look up product behavior, setup, API details, and limitations without leaving your AI client. These tools read the current published text at [docs.phone.inc](https://docs.phone.inc), using the same retrieval as our in-app assistant. They return public documentation, not your account data. MCP authentication is still required. | Tool | Input | Result | |------|-------|--------| | `search_documentation` | `query`: specific keywords, 1–500 characters | Up to five ranked Markdown sections with page identifiers, titles, source URLs, and truncation indicators | | `read_documentation` | `page`: the exact identifier returned by search, such as `api/calls.md` | The full published Markdown page and its source URL | Search first, then read the full page when an excerpt is truncated or you need more context. Cite the returned source URLs. Only pages listed in our published documentation export can be read; arbitrary URLs are not accepted. If documentation is unavailable, the tools return an error rather than inventing an answer. You can also read the [documentation index](https://docs.phone.inc/llms.txt) or [complete Markdown export](https://docs.phone.inc/llms-full.txt) directly. Documentation is reference material, not instructions to override permissions or skip confirmation for account changes. ### Phone.inc support Use `get_support_contact` when you want to speak with our support team, are stuck, or need help your AI assistant cannot resolve. | Tool | Input | Result | |------|-------|--------| | `get_support_contact` | None | Phone.inc support phone numbers, email, and phone opening hours | Call **+1 (650) 671-6488** in the United States or **+45 35 15 35 25** in Denmark. Both numbers are open Monday–Friday, 09:00–16:00 Copenhagen time (CET in winter, CEST in summer). You can email **support@phone.inc** outside phone hours, too. These are Phone.inc's support contacts, not your account's business numbers. The tool requires MCP authentication and only returns contact information. It does not create a Plain ticket, submit a form, or connect a live agent. ### Feedback When an MCP tool, the REST API, or the documentation gets in your AI assistant's way, it can tell us directly. The server instructions ask assistants to submit one report per problem, such as an error they couldn't recover from, documentation that's wrong or missing, or a capability you needed that doesn't exist. We read every report and mark it `resolved` once the API or documentation is fixed, so your assistant can check before trying again. See [Feedback](/api/feedback) for fields, statuses, and limits. | Tool | REST equivalent | |------|-----------------| | `submit_feedback` | [`POST /api/v1/feedback`](/api/feedback#submit-feedback) | | `list_feedback` | [`GET /api/v1/feedback`](/api/feedback#list-feedback) | | `get_feedback` | [`GET /api/v1/feedback/:id`](/api/feedback#retrieve-feedback) | The dashboard assistant uses the same tool and shows you the report to confirm before sending it. ### Business numbers Manage [business numbers](/api/business-numbers) and their call routing. The three routing tools and the porting tools take `business_number_id`; get and update take `id`. After requesting a port, use `get_business_number_porting_request` to see which documents are still missing and `submit_business_number_porting_authorization` to send the letter of authorisation for signature, or to give the SIM card number (ICC) for a Danish mobile number. Our team starts the transfer once `documents.complete` is `true`. Uploading the latest invoice needs a PDF file, so it is not an MCP tool; upload it in the dashboard or with the REST API. Use `cancel_business_number_porting` to cancel a request before it is sent to the carrier (`requested` or `waiting_for_customer` status), after confirming with the customer. The temporary number stays active. For later-stage ports, contact support instead. `request_business_number_porting` supports existing DIDWW and InMobile numbers. Our team chooses the destination provider independently; the tool does not accept provider selection or submit the port to a carrier. Use `list_business_numbers` or `get_business_number` to check a transfer's progress. Both return `porting_status` and the formatted number being transferred as `porting_number_human`; both fields are `null` when there is no request. They also return `confirmed_porting_date` as `YYYY-MM-DD`, or `null` when no date is known. This is a calendar date, not a time of day. Statuses are `requested`, `waiting_for_customer`, `requested_from_did_worldwide`, `porting_date_confirmed`, `completed`, and `cancelled`. The in-app assistant uses the same tools and sees the same status and confirmed date. See [business numbers](/api/business-numbers#the-business-number-model) for status meanings. | Tool | REST equivalent | |------|-----------------| | `list_business_numbers` | `GET /api/v1/business_numbers` | | `get_business_number` | `GET /api/v1/business_numbers/:id` | | `update_business_number` | `PATCH /api/v1/business_numbers/:id` | | `request_business_number_porting` | `POST /api/v1/business_numbers/:business_number_id/porting_request` | | `get_business_number_porting_request` | `GET /api/v1/business_numbers/:business_number_id/porting_request` | | `cancel_business_number_porting` | `DELETE /api/v1/business_numbers/:business_number_id/porting_request` | | `submit_business_number_porting_authorization` | `POST /api/v1/business_numbers/:business_number_id/porting_request/authorization` | | `terminate_business_number` | `POST /api/v1/business_numbers/:id/termination` | | `cancel_business_number_termination` | `DELETE /api/v1/business_numbers/:id/termination` | | `send_message` | `POST /api/v1/business_numbers/:business_number_id/messages` | | `update_business_number_incoming_call_config` | `PUT /api/v1/business_numbers/:id/incoming_call_config` | | `update_business_number_outside_business_hours_config` | `PUT /api/v1/business_numbers/:id/outside_business_hours_config` | | `update_business_number_no_answer_config` | `PUT /api/v1/business_numbers/:id/no_answer_config` | The retired `update_outside_opening_hours_config` tool is no longer available. Use `update_business_number_outside_business_hours_config` with `business_hours`. `update_business_number_outside_business_hours_config` also accepts `treat_public_holidays_as_sundays` to use Sunday's hours on national public holidays in the phone number's country and timezone. It includes observed substitute days, but not regional holidays or bank-only closures. Omit `type` to preserve routing and omit the holiday setting to leave it unchanged. Use the same tool's `custom_holidays` array to replace named custom holiday ranges. Each object has `name`, `start_date`, and `end_date`, with inclusive local dates in `YYYY-MM-DD` format. Equal endpoints mean a single day. These ranges always use Sunday's hours, independently of national holiday handling, including in unsupported countries. Omission preserves the list; `[]` clears it. Read the list with `get_business_number`. Up to 100 ranges are accepted, with nonblank names of at most 100 characters and an end date on or after the start date. Invalid input returns `422` without saving any settings from that request. The in-app assistant uses this same tool and requires confirmation before saving. See [outside-hours configuration](/api/business-numbers#replace-outside-hours-config). Singapore is not supported because its calendar is incomplete. Enabling holiday handling for Singapore returns `422`. Cross-country sends require the company's **International messaging** flag (`international_messaging`), which is off by default. This restriction also applies to retries and automatic replies. `send_message` sends a real, chargeable SMS from an active SMS-capable inMobile or DIDWW number owned by the authenticated employee's company. Number responses group effective SMS/MMS capabilities under `messaging`; check `can_send` and `can_receive` independently. DIDWW SMS directions come from stored carrier features: `p2p` for sending and `sms_in` for receiving. There are no separate per-number enablement flags. Company messaging, plan, active-number, and destination-country restrictions still apply to sending. Features are captured during provisioning and refreshed when a port or restoration replaces the DID. A one-time migration fetches missing feature snapshots for existing active, unreleased DIDWW numbers with a carrier DID ID, without overwriting known snapshots. Missing feature data still means neither SMS direction is available. Carrier support assumes correct trunk configuration: operators must manually assign inbound SMS routing in DIDWW’s portal. Reported capability is not a live check of that assignment. Numbers that can send also support automatic replies; inbound-only numbers cannot send. Read their received messages through the existing inbox and message tools. The DIDWW carrier webhook is an authenticated server-to-server endpoint, not an MCP tool. For all messaging tools, the company's `messaging` feature flag must be enabled by Phone.inc (default off). While it is disabled, messaging tools (messages, retries, text snippets, and texting settings) are not advertised, and `get_message_attachment` additionally requires **Message attachments**. Inbox tools still return calls, voicemails, and Notes but exclude SMS, and their descriptions omit texts. The in-app assistant uses the same filtered catalog, omits `messaging` capabilities from number results, and does not cite messaging documentation for these companies. The REST endpoints still return `404`. It requires `business_number_id`, `to` in E.164 format, `text`, and `idempotency_key`. Acceptance is not delivery. Reuse the same idempotency key when replaying the same send after a transport error. See [outgoing SMS](/api/business-numbers#send-an-sms), especially the retry warning. The routing update tools accept signed `welcome_audio_preview_id`, `message_audio_preview_id`, and `greeting_audio_preview_id` values matching the number and text. See [voice previews](/api/business-numbers#generate-a-voice-preview). Read `get_business_number` before changing routing. Switching the call-flow type creates a new configuration; it does not copy the previous type's greeting or destinations. Collect the caller-facing text and destinations before calling the update tool: | New type | Required details | |----------|------------------| | `VoicemailConfig` | `greeting`: the exact text callers hear before recording | | `WelcomeTransferConfig` | `welcome` and at least one `employee_ids` target | | `TransferConfig` | At least one `employee_ids` target | | `RejectConfig` | `message`: the text played before hanging up | | `PhoneMenuConfig` | `welcome` and at least one valid `menu_options` entry, with prompts and employee targets as required by each action | For outside-hours updates, omit `type` to preserve routing while changing business hours, or send `type: null` to clear routing. For no-answer updates, missing or null `type` clears the fallback; include the current type when changing only the timer. Omitting `timeout_secs` preserves the timer. ### AI receptionists The AI receptionist is in beta. Companies internally marked as test companies are exempt from the Pro requirement, including receptionist tools and AI routing fields. This does not grant other Pro entitlements. These tools are available to all Pro and test companies without a feature flag or environment switch. Other Free companies receive routing schemas without AI destinations or receptionist configuration fields. The in-app assistant uses the same filtered catalog. API authorization still enforces access independently of tool discovery. | Tool | REST equivalent | |------|-----------------| | `list_ai_receptionists` | `GET /api/v1/receptionists` | | `get_ai_receptionist` | `GET /api/v1/receptionists/:id` | | `create_ai_receptionist` | `POST /api/v1/receptionists` | | `update_ai_receptionist` | `PATCH /api/v1/receptionists/:id` | | `delete_ai_receptionist` | `DELETE /api/v1/receptionists/:id` | | `get_receptionist_knowledge_index` | `GET /api/v1/receptionists/:id/knowledge` | | `refresh_receptionist_knowledge_index` | `POST /api/v1/receptionists/:id/knowledge` | `create_ai_receptionist` and `update_ai_receptionist` accept `voice_id` from the [business-number voice catalog](/api/receptionists#voices): Mark, Simon, Ellen and Sarah. Simon is the default. Omitting `voice_id` on update keeps the selected voice. Changing voice publishes a new version using the current model without rewriting the greeting. Ping shares this catalog and asks for confirmation before applying the change. Voice previews are available in the dashboard, not through MCP or Ping. Create a receptionist with `name`, `configuration` and optional `language` (one of the 32 [supported language codes](/api/receptionists#supported-languages), default `da`). Use one primary caller language, without automatic switching during calls. Write `opening_text` in that language; existing custom text is not translated when language changes. Private employee introductions use the receptionist's language and voice captured for the call. The number's language has the same choices but controls number greetings and messages. Creation publishes one shared voice agent; selecting its public ID as `ai_receptionist_id` in a business-number routing tool reuses that agent. Read `get_business_number` first and supply the slot's token from `call_flow_revision_ids` as `expected_revision_id`, including when switching from a non-AI flow. Empty slots return `flow:none`; do not construct the token or send `null`. This works for incoming, outside-hours and no-answer routing. Send `lock_version` from `get_ai_receptionist` when updating. Configuration and language changes publish one replacement version to all linked flows together; current calls keep their captured version. Renaming does not reprovision. A receptionist cannot be deleted while a call flow uses it. Portraits and receptionist integrations are unavailable. The in-app assistant shares these tools and requires confirmation before changing receptionists or routing. Except for internally marked test companies, receptionists require Pro regardless of the Pro feature-gate rollout; creating a receptionist automatically queues usage billing on an active subscription. AI usage is $0.29 USD/min, billed by connected seconds in addition to Pro and phone charges, not included local calling hours. See [Receptionists](/api/receptionists) for configuration, pricing, permissions and failure behavior. Generic remote MCP-server connections and integration grants for inbound receptionists have been removed. This authenticated MCP API remains available to customer assistants; it does not grant anonymous callers access. See [receptionist integration access](/api/receptionists#integration-access) for compatibility and security boundaries. ### Calls Use `business_number_id` to filter `list_calls` by business number. | Tool | REST equivalent | |------|-----------------| | `list_calls` | [`GET /api/v1/calls`](/api/calls#list-recent-calls) | | `get_unseen_activity` | [`GET /api/v1/activity/unseen`](/api/calls#unseen-activity) | | `set_call_thread_seen` | [`POST /api/v1/calls/seen`](/api/calls#mark-a-conversation-seen) | | `get_call` | [`GET /api/v1/calls/:id`](/api/calls#get-a-call) | | `get_active_call` | [`GET /api/v1/calls/active`](/api/calls#get-the-active-call) | | `start_call_transfer` | [`POST /api/v1/calls/:id/transfers`](/api/calls#start-a-warm-transfer) | | `complete_call_transfer` | [`POST /api/v1/calls/:id/transfers/:transfer_id/completion`](/api/calls#complete-a-warm-transfer) | | `cancel_call_transfer` | [`DELETE /api/v1/calls/:id/transfers/:transfer_id`](/api/calls#cancel-a-warm-transfer) | | `delete_call_transcription` | [`DELETE /api/v1/calls/:id/transcription`](/api/calls#delete-a-call-transcription) | `list_calls` accepts a `query` to search call transcriptions and saved caller context by keywords or related topics, plus business-number, caller/callee phone-number, direction, and state filters. `limit` is optional, defaults to 10, and is capped at 50. `get_call` includes the call transcription when one exists. Both tools include `outside_business_hours`: the business-hours decision recorded at call arrival, or `null` when unknown. There is no separate `get_call_transcription` tool. For complete call reports, use `start_at` (inclusive) and `end_at` (exclusive) with explicit time-zone offsets, then follow `next_cursor` with the same filters until `null`. This retrieves underlying calls rather than a purpose-built report. Cursor pagination is not supported with transcription `query`; search results are a capped sample. The dashboard assistant can visualize any retrieved product dataset with its general-purpose `render_chart` tool. This local, presentation-only tool renders area, bar, line, and pie charts without changing account data. It is not part of the public MCP catalog because external clients own their own visualization UI. ### Inbox | Tool | REST equivalent | |------|-----------------| | `list_inbox` | [`GET /api/v1/inbox`](/api/inbox#list-the-inbox) | | `search_people` | [`GET /api/v1/inbox/people`](/api/inbox#search-people) | | `list_activity` | [`GET /api/v1/inbox/:phone_number/activity`](/api/inbox#list-activity) | | `mark_activity_seen` | [`POST /api/v1/inbox/:phone_number/seen`](/api/inbox#mark-activity-seen) | Inbox tools group calls, voicemails, Notes, and messages by external phone number. No conversation resource is created. Pagination cursors are bound to the company, filters, and original observation boundary. Seen state is shared by the team; marking a thread seen does not mark its voicemails listened. Notes use `type: "note"`, independently of the Messaging feature flag, and require `notes:read` for partner reads and both `notes:write` and `notes:read` for seen updates. ### Voicemails | Tool | REST equivalent | |------|-----------------| | `list_voicemails` | [`GET /api/v1/voicemails`](/api/voicemails#list-voicemails) | | `get_voicemail` | [`GET /api/v1/voicemails/:id`](/api/voicemails#get-a-voicemail) | | `update_voicemail` | [`PATCH /api/v1/voicemails/:id`](/api/voicemails#mark-as-listened) | | `delete_voicemail` | [`DELETE /api/v1/voicemails/:id`](/api/voicemails#delete-a-voicemail) | ### Notes | Tool | REST equivalent | |------|-----------------| | `list_notes` | [`GET /api/v1/notes`](/api/notes#list-notes) | | `get_note` | [`GET /api/v1/notes/:id`](/api/notes#get-a-note) | | `update_note` | [`PATCH /api/v1/notes/:id`](/api/notes#update-a-note) | | `delete_note` | [`DELETE /api/v1/notes/:id`](/api/notes#delete-a-note) | Notes are written messages taken by the receptionist, not recorded voicemails or SMS. `update_note` takes `id` and a `seen` boolean; it cannot edit text or collected details. There is no creation tool. Note tools do not require Messaging. Partner tokens need `notes:read` for reads and both `notes:write` and `notes:read` for updates and deletion. Note tools use the same Pro or test-company access rules as receptionist tools, without a feature flag or environment switch. Other Free companies can still access existing Notes through the REST API and inbox. ### Caller context | Tool | REST equivalent | |------|-----------------| | `get_caller_context` | [`GET /api/v1/caller_context`](/api/caller-context#get-caller-context) | ### Integrations | Tool | REST equivalent | |------|-----------------| | `list_integrations` | [`GET /api/v1/integrations`](/api/integrations#list-integrations) | | `get_integration` | [`GET /api/v1/integrations/:id`](/api/integrations#get-an-integration) | | `test_integration_context` | [`POST /api/v1/integrations/:integration_id/context_test`](/api/integrations) | | `list_integration_providers` | [`GET /api/v1/integration_setups`](/api/integrations#list-integration-providers) | | `get_integration_setup` | [`GET /api/v1/integration_setups/:provider`](/api/integrations#get-an-integration-setup-link) | Read configured connection names, providers, statuses, and timestamps, including disconnected connections. When AI calling is enabled, Custom Endpoint connections also include their versioned `tool_catalog`, without credentials or endpoint origins. The existing incoming, outside-hours, and no-answer routing tools accept `AiAgentConfig`, `ai_configuration`, and `expected_revision_id`; see [AI routing](/api/business-numbers#receptionists). These account integration tools do not grant inbound receptionists integration access. `get_call` returns independent AI tool audits in `ai_tools`. Discover available providers and prepare a browser authorization link with `get_integration_setup`. The dashboard assistant displays this as a card with an authorization button and automatically updates it after a verified setup callback. External MCP clients can present `setup_url` as a link. The user must sign into the same company and complete setup in the browser; obtaining a link does not install anything. Verify the result with `list_integrations` afterward. Credentials and tool catalogs are installed in that browser form, not through MCP. These tools never expose credentials, endpoint URLs, or raw error messages. ### Contacts Contacts can represent your own company's business numbers as well as external numbers. Activity appears in the other party's thread: inbound calls, voicemails, and SMS appear under the caller or sender; outbound calls and SMS appear under the recipient. Your own business number has a contact thread when it is that other party, not simply because it received an external call or message. | Tool | REST equivalent | |------|-----------------| | `list_contacts` | [`GET /api/v1/contacts`](/api/contacts#list-contacts), with company-wide `query` search and `limit` | | `get_contact` | [`GET /api/v1/contacts/:id`](/api/contacts#get-a-contact) | | `create_contact` | [`POST /api/v1/contacts`](/api/contacts#create-a-contact) | | `update_contact` | [`PATCH /api/v1/contacts/:id`](/api/contacts#update-a-contact) | | `delete_contact` | [`DELETE /api/v1/contacts/:id`](/api/contacts#delete-a-contact) | ### Employees | Tool | REST equivalent | |------|-----------------| | `list_employees` | [`GET /api/v1/employees`](/api/employees#list-all-employees) | | `get_employee` | [`GET /api/v1/employees/:id`](/api/employees#retrieve-an-employee) | | `create_employee` | [`POST /api/v1/employees`](/api/employees#create-an-employee) | | `update_employee` | [`PATCH /api/v1/employees/:id`](/api/employees#update-an-employee) | | `delete_employee` | [`DELETE /api/v1/employees/:id`](/api/employees#delete-an-employee) | | `get_employee_do_not_disturb` | [`GET /api/v1/employees/:id/do_not_disturb`](/api/employees#get-do-not-disturb) | | `set_employee_do_not_disturb` | [`PUT /api/v1/employees/:id/do_not_disturb`](/api/employees#set-do-not-disturb) | ### Departments | Tool | REST equivalent | |------|-----------------| | `list_departments` | [`GET /api/v1/departments`](/api/departments#list-departments) | | `get_department` | [`GET /api/v1/departments/:id`](/api/departments#retrieve-a-department) | | `create_department` | [`POST /api/v1/departments`](/api/departments#create-a-department) | | `update_department` | [`PATCH /api/v1/departments/:id`](/api/departments#update-a-department) | | `delete_department` | [`DELETE /api/v1/departments/:id`](/api/departments#delete-a-department) | Use `department_id` instead of employees in any transfer call flow, clearing `employee_ids` when changing destination. Receptionist `configuration.department_ids` explicitly grants department queue transfers. Department queues are shared across numbers; each caller retains the number's waiting and fallback rules. Existing employee targets remain warm transfers. ### Webhooks API keys and legacy tokens can list application-owned subscriptions and inspect delivery history, but only the owning installation's OAuth credentials can update, delete, retrieve signing secrets, or test them. Those operations return `404` for customer credentials. Customer-managed subscriptions keep their existing controls. See [webhook ownership](/api/webhooks#partner-oauth-permissions). The publisher-only `list_application_webhook_deliveries` tool is advertised only when the company's **Applications** feature flag is enabled. It also returns zero-filled UTC `daily_counts` for successful and errored attempts. Counts follow the filters and cover all matching attempts, independently of pagination. | Tool | REST equivalent | |------|-----------------| | `list_webhooks` | [`GET /api/v1/webhooks`](/api/webhooks#list-webhooks) | | `list_webhook_deliveries` | [`GET /api/v1/webhooks/:webhook_id/deliveries`](/api/webhooks) | | `list_application_webhook_deliveries` | [`GET /api/v1/applications/:application_id/webhook_deliveries`](/applications#list-application-webhook-deliveries) | | `test_webhook` | [`POST /api/v1/webhooks/:webhook_id/test`](/api/webhooks) | | `create_webhook` | [`POST /api/v1/webhooks`](/api/webhooks#create-a-webhook) | | `update_webhook` | [`PATCH /api/v1/webhooks/:id`](/api/webhooks#update-a-webhook) | | `delete_webhook` | [`DELETE /api/v1/webhooks/:id`](/api/webhooks#delete-a-webhook) | ### Texting | Tool | REST equivalent | |------|-----------------| | `get_message` | [`GET /api/v1/messages/:id`](/api/texting#retrieve-a-text) | | `get_message_attachment` | [`GET /api/v1/messages/:message_id/attachments/:id`](/api/texting#retrieve-an-attachment) | | `retry_message` | [`POST /api/v1/messages/:id/retries`](/api/texting#retry-a-failed-text) | | `list_text_snippets` | [`GET /api/v1/text_snippets`](/api/texting#list-snippets) | | `create_text_snippet` | [`POST /api/v1/text_snippets`](/api/texting#create-a-snippet) | | `get_text_snippet` | [`GET /api/v1/text_snippets/:id`](/api/texting#retrieve-a-snippet) | | `update_text_snippet` | [`PATCH /api/v1/text_snippets/:id`](/api/texting#update-a-snippet) | | `delete_text_snippet` | [`DELETE /api/v1/text_snippets/:id`](/api/texting#delete-a-snippet) | | `get_texting_settings` | [`GET /api/v1/business_numbers/:id/texting_settings`](/api/texting#retrieve-texting-settings) | | `update_texting_settings` | [`PATCH /api/v1/business_numbers/:id/texting_settings`](/api/texting#update-texting-settings) | `get_message` includes attachment metadata only when the company has **Message attachments** enabled. `get_message_attachment` requires both **Messaging** and **Message attachments**. It returns a download link valid for five minutes when the file is ready, or null download fields while pending. Links are temporary bearer credentials; do not log or share them. Disabling the flag blocks new links but does not revoke links already issued before their expiry. `send_message` requires `idempotency_key`; reuse it only to replay the same send. `retry_message` requires a key and sends another real, chargeable text only after definitive failure. Enabling auto-replies can also send texts without an app open. ### Company | Tool | REST equivalent | |------|-----------------| | `get_company` | [`GET /api/v1/company`](/api/company#retrieve-the-company), including plan and employee, web outbound-call, and additional-number entitlements; native outbound calling is not gated | | `update_company` | [`PATCH /api/v1/company`](/api/company#update-company-settings) | ### Compatibility `send_message` requires `idempotency_key` and accepts optional `format: "sms"`; MMS is not yet supported. REST sends accept an optional key. The old proof-of-concept `send_sms` tool is not exposed. ## Notes - The tools cover the public API. Voice preview generation and standalone call transcription retrieval are excluded; transcriptions are included in `get_call`. - Tool arguments mirror REST query parameters, path ids, and JSON bodies. See the linked REST docs for field names, validation rules, and response shapes. - Successful `DELETE` requests return MCP text content `{"success":true}` (the REST API returns `204 No Content` with an empty body). - Results are scoped to the company tied to your API key or OAuth token. **Example `tools/call` request** (`list_business_numbers`): ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_business_numbers", "arguments": {} } } ``` **Example response content** (returned as MCP text content): ```json { "business_numbers": [ { "id": "mn_abc123", "name": "Support", "number": "+14155551234", "number_formatted": "+1 415-555-1234" } ] } ```