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. 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, and Note webhooks. 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.
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 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
- Name
id- Type
- string
- Description
- The Note's unique public ID.
- Name
type- Type
- string
- Description
- Always
note.
- Name
direction- Type
- string
- Description
- Always
inboundfor notes taken during incoming calls.
- Name
text- Type
- string
- Description
- The caller's written message.
- Name
details- Type
- object
- Description
- Selected caller details:
name,email,company_name,reference, andcallback_time. Selected fields the caller declined or could not provide arenull; unselected fields are omitted.referenceis an order, booking, or customer reference.callback_timeis the caller's preference as stated, not a scheduled callback or promise.
- Name
from- Type
- string
- Description
- The caller's phone number in E.164 format.
- Name
call_id- Type
- string | null
- Description
- The linked call's public ID, or
null.
- Name
seen_at- Type
- string | null
- Description
- ISO 8601 timestamp when the team marked the Note seen, or
nullwhen unseen. Seen state is shared by the team.
- Name
created_at- Type
- string
- Description
- ISO 8601 timestamp when the Note was saved.
- Name
business_number_id- Type
- string
- Description
- The owning business number's public ID.
- Name
business_number_name- Type
- string
- Description
- 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.
Request
curl https://app.phone.inc/api/v1/notes \
-H "X-Api-Key: $PHONE_INC_API_KEY"
Response
{
"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.
Request
curl https://app.phone.inc/api/v1/notes/0193f4cb-7777-7c00-9e3d-2b2b8a7f1c33 \
-H "X-Api-Key: $PHONE_INC_API_KEY"
Response
{
"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
- Name
seen- Type
- boolean
- Description
- Send
trueto mark seen orfalseto mark unseen.
Request
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}'
Response
{
"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.
Request
curl -X DELETE https://app.phone.inc/api/v1/notes/0193f4cb-7777-7c00-9e3d-2b2b8a7f1c33 \
-H "X-Api-Key: $PHONE_INC_API_KEY"