Phone.inc

Voicemails

When a caller leaves a voicemail, Phone.inc records the audio and ties it to the main number that was dialed. The Voicemails API lists every voicemail on your account, gives you a signed URL for the recording, and lets you flip the listened flag from your own UI.

The voicemail model

A voicemail is a small object: who called, when, where the recording is, and whether someone has listened to it yet.

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the voicemail.

  • Name
    from
    Type
    string
    Description

    The caller's phone number in E.164 format.

  • Name
    listened_at
    Type
    timestamp
    Description

    ISO 8601 timestamp of when the voicemail was first marked as listened. null if it hasn't been listened to yet.

  • Name
    transcription
    Type
    string
    Description

    Plain-text transcription of the voicemail recording. null until the recording has been transcribed.

  • Name
    created_at
    Type
    timestamp
    Description

    ISO 8601 timestamp of when the voicemail was recorded.

  • Name
    recording_url
    Type
    string
    Description

    URL where the audio file can be downloaded. May be null if the recording is still being processed. The URL is generated per request — don't cache it long-term.

  • Name
    main_number_id
    Type
    string
    Description

    The ID of the main number the voicemail was left on.

  • Name
    main_number_name
    Type
    string
    Description

    The label of the main number.

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

GET/v1/voicemails

List voicemails

Returns every voicemail on the authenticated employee's company, newest first. There are no query parameters or pagination — voicemail volume is low enough that the full list is returned in one response.

The response also includes unlistened_count at the top — the number of voicemails on the company that haven't been marked as listened yet. It counts every unlistened voicemail, not just the ones in this response, so you can drive an inbox badge straight from it.

Request

GET
/v1/voicemails
curl https://app.phone.inc/api/v1/voicemails \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Response

{
  "unlistened_count": 3,
  "voicemails": [
    {
      "id": "0193f4cb-7777-7c00-9e3d-2b2b8a7f1c33",
      "from": "+14085550199",
      "listened_at": null,
      "transcription": "Hi, this is Dana from Acme. Give me a call back about the invoice when you get a chance. Thanks!",
      "created_at": "2026-05-11T13:48:02Z",
      "recording_url": "https://app.phone.inc/rails/active_storage/blobs/redirect/.../voicemail.mp3",
      "main_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
      "main_number_name": "Sales",
      "main_number": "+14155551234",
      "main_number_formatted": "+1 415-555-1234"
    }
  ]
}
GET/v1/voicemails/:id

Retrieve a voicemail

Returns a single voicemail by its ID. The response includes the recording URL and all metadata.

Request

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

Response

{
  "id": "0193f4cb-7777-7c00-9e3d-2b2b8a7f1c33",
  "from": "+14085550199",
  "listened_at": null,
  "transcription": "Hi, this is Dana from Acme. Give me a call back about the invoice when you get a chance. Thanks!",
  "created_at": "2026-05-11T13:48:02Z",
  "recording_url": "https://app.phone.inc/rails/active_storage/blobs/redirect/.../voicemail.mp3",
  "main_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
  "main_number_name": "Sales",
  "main_number_number": "+14155551234",
  "main_number_number_formatted": "+1 415-555-1234"
}
PATCH/v1/voicemails/:id

Update a voicemail

Mark a voicemail as listened or unlistened. This is the only field you can update on a voicemail today.

Pass listened=true to set listened_at to the current time (no-op if it's already listened). Pass listened=false to clear it.

Returns the full voicemail object.

Optional attributes

  • Name
    listened
    Type
    boolean
    Description

    Whether the voicemail should be marked as listened. Accepts the usual truthy/falsy values (true, false, "1", "0").

Request

PATCH
/v1/voicemails/:id
curl -X PATCH https://app.phone.inc/api/v1/voicemails/0193f4cb-7777-7c00-9e3d-2b2b8a7f1c33 \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  -d listened=true

Response

{
  "id": "0193f4cb-7777-7c00-9e3d-2b2b8a7f1c33",
  "from": "+14085550199",
  "listened_at": "2026-05-11T16:42:18Z",
  "transcription": "Hi, this is Dana from Acme. Give me a call back about the invoice when you get a chance. Thanks!",
  "created_at": "2026-05-11T13:48:02Z",
  "recording_url": "https://app.phone.inc/rails/active_storage/blobs/redirect/.../voicemail.mp3",
  "main_number_id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
  "main_number_name": "Sales",
  "main_number_number": "+14155551234",
  "main_number_number_formatted": "+1 415-555-1234"
}
DELETE/v1/voicemails/:id

Delete a voicemail

Permanently deletes a voicemail and its recording. This cannot be undone.

Returns an empty response with a 204 No Content status.

Request

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