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.

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 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 for SMS-specific fields, sending, delivery state, and automatic replies.

Written messages taken by the receptionist are 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

  • Name
    phone_number
    Type
    string
    Description
    Normalized E.164 external phone number. This is the thread address.
  • Name
    contact
    Type
    object | null
    Description
    Existing contact reference, including ID, display name, phone, and saved contact fields; null when no contact exists.
  • Name
    last_activity_at
    Type
    string
    Description
    ISO 8601 creation timestamp of the latest activity.
  • Name
    unseen_count
    Type
    integer
    Description
    Number of unseen inbound activity items, including received messages, after call/voicemail folding. Outbound calls do not count as unseen.
  • Name
    business_number_ids
    Type
    array
    Description
    Public IDs of business numbers represented in this thread at the observation boundary.
  • Name
    preview
    Type
    string
    Description
    Call summary, voicemail transcription, Note text, or SMS message text, with a fallback label; truncated to 160 characters.
  • Name
    latest_item
    Type
    object
    Description
    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

  • Name
    id
    Type
    string
    Description
    Stable call, voicemail, Note, or message public ID.
  • Name
    type
    Type
    string
    Description
    call, voicemail, note, or message. MMS is not implemented.
  • Name
    format
    Type
    string
    Description
    Message format, currently sms. Present only on message items; future formats use the same message activity type.
  • Name
    created_at
    Type
    string
    Description
    ISO 8601 storage timestamp, used for ordering and seen boundaries.
  • Name
    business_number_id
    Type
    string
    Description
    Owning business number public ID.
  • Name
    business_number_name
    Type
    string
    Description
    Owning business number name.
  • Name
    seen_at
    Type
    string | null
    Description
    ISO 8601 timestamp when the team marked this activity seen.
  • Name
    direction
    Type
    string
    Description
    inbound or outbound; voicemails are inbound.
  • Name
    from
    Type
    string
    Description
    Originating E.164 phone number.
  • Name
    to
    Type
    string
    Description
    Destination phone number; present on calls and SMS.
  • Name
    duration
    Type
    integer | null
    Description
    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: 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.


GET/v1/inbox

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.

Request

GET
/v1/inbox
curl 'https://app.phone.inc/api/v1/inbox?limit=50' \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Response

{
  "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
}

GET/v1/inbox/people

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. 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.

Request

GET
/v1/inbox/people
curl 'https://app.phone.inc/api/v1/inbox/people?query=2390&limit=5' \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Response

{
  "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
    }
  ]
}

GET/v1/inbox/:phone_number/activity

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.

Request

GET
/v1/inbox/:phone_number/activity
curl 'https://app.phone.inc/api/v1/inbox/+4523909778/activity?limit=50' \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Response

{
  "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"
}

POST/v1/inbox/:phone_number/seen

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.

Request

POST
/v1/inbox/:phone_number/seen
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"}'