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 samemessageactivity 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.
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
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
}
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
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
}
]
}
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
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"
}
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
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"}'