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 inbound for 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, 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.
  • 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 null when 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.


GET/v1/notes

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

GET
/v1/notes
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/v1/notes/:id

Get a Note

Retrieve one Note by its public ID. The response is the Note object itself, without a note wrapper.

Request

GET
/v1/notes/:id
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"
}

PATCH/v1/notes/:id

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 true to mark seen or false to mark unseen.

Request

PATCH
/v1/notes/:id
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/v1/notes/:id

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

DELETE
/v1/notes/:id
curl -X DELETE https://app.phone.inc/api/v1/notes/0193f4cb-7777-7c00-9e3d-2b2b8a7f1c33 \
  -H "X-Api-Key: $PHONE_INC_API_KEY"