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, and pull a single call by its public ID.

The call model

A call links a main 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.

Properties

Name
id
Type
string
Description
Unique public identifier for the call. Use this when calling the retrieve endpoint.
Name
from
Type
string
Description
The originating phone number in E.164 format.
Name
to
Type
string
Description
The destination phone number in E.164 format.
Name
direction
Type
string
Description
Either inbound (someone called you) or outbound (an employee called out).
Name
state
Type
string
Description
The current lifecycle state. See the state values section below for the full list.
Name
started_at
Type
timestamp
Description
ISO 8601 timestamp of when the call was initiated. May be null for calls that haven't started yet.
Name
answered_at
Type
timestamp
Description
ISO 8601 timestamp of when the call was answered. null for missed or rejected calls.
Name
duration
Type
integer
Description
Total length of the call in seconds, measured from answered_at. null while the call is in progress.
Name
summary
Type
string
Description
Auto-generated summary of the call once it ends. null while the call is in progress or if a summary hasn't been produced.
Name
transcription
Type
string
Description
Full text transcription of the call recording. null until the recording has been transcribed.
Name
transcription_segments
Type
array
Description
Speaker-diarized transcription segments. Each entry has speaker, text, and an optional employee_id (the employee's public ID). null until transcribed.
Name
main_number_id
Type
string
Description
The ID of the main number the call was placed to or from.
Name
main_number_name
Type
string
Description
The label of the main number (e.g. Sales).
Name
main_number
Type
string
Description
The main number in E.164 format.
Name
main_number_formatted
Type
string
Description
The main number formatted for display.
Name
recording_url
Type
string
Description
URL where the call recording can be downloaded. null if recording is disabled or the call hasn't ended yet. The URL is generated per request — don't cache it long-term.
Name
employees
Type
array
Description
Employees who participated in the call. Each entry has id and name.
Name
initiated_by
Type
object
Description
For outbound calls only — the employee who placed the call. Has id and name. Omitted on inbound calls.

Call states

The state field walks through the call's lifecycle. The values are:

Name
initiated
Description
The call has been created but not yet answered.
Name
answered
Description
The call was answered. answered_at is now set.
Name
playing_audio
Description
A pre-recorded greeting or message is being played to the caller.
Name
transferring
Description
The call is being transferred to an employee or another destination.
Name
recording
Description
The call is being recorded (e.g. taking a voicemail).
Name
bridged
Description
Two parties are connected and talking. This is the typical state for an active conversation.
Name
ended
Description
The call has hung up. duration is now set, and a summary may follow shortly.

GET/v1/calls

List recent calls

Returns recent calls for the authenticated employee's company, newest first. By default you get the 10 most recent calls; raise that with limit (capped at 50). All filters can be combined.

Optional query parameters

Name
phone_number
Type
string
Description
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.
Name
direction
Type
string
Description
Limit results to inbound or outbound. Defaults to both.
Name
state
Type
string
Description
Filter by call state, e.g. ended for completed calls only. Unknown values are silently ignored.
Name
limit
Type
integer
Description
Maximum number of calls to return. Defaults to 10, capped at 50.

Request

GET

/v1/calls

curl -G https://app.phone.inc/api/v1/calls \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  -d direction=inbound \
  -d state=ended \
  -d limit=25

Response

{
  "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",
      "main_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
      "main_number_name": "Sales",
      "main_number": "+14155551234",
      "main_number_formatted": "+1 415-555-1234",
      "employees": [
        {
          "id": "0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20",
          "name": "Alex Wong"
        }
      ]
    }
  ]
}

GET/v1/calls/:id

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.

Request

GET

/v1/calls/0193f4ba-1234-7c00-9e3d-2b2b8a7f1c11

curl https://app.phone.inc/api/v1/calls/0193f4ba-1234-7c00-9e3d-2b2b8a7f1c11 \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Response

{
  "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,
  "main_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
  "main_number_name": "Sales",
  "main_number": "+14155551234",
  "main_number_formatted": "+1 415-555-1234",
  "employees": [
    {
      "id": "0193f4b0-aaaa-7c00-9e3d-2b2b8a7f1c20",
      "name": "Alex Wong"
    }
  ]
}