> For the complete documentation index, see [llms.txt](https://docs.limecall.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limecall.com/developers/voicemails.md).

# Voicemails API

List voicemails and mark them read.

| Method  | Path               | Scope         |
| ------- | ------------------ | ------------- |
| `GET`   | `/voicemails`      | `calls:read`  |
| `PATCH` | `/voicemails/{id}` | `calls:write` |

## List voicemails

```bash
curl "https://app.limecall.com/api/v1/voicemails?unreadOnly=true" \
  -H "Authorization: Bearer sk_live_..."
```

### Query parameters

| Parameter        | Notes                                 |
| ---------------- | ------------------------------------- |
| `page` / `limit` | Standard paging.                      |
| `unreadOnly`     | Only voicemails nobody has picked up. |
| `status`         | Filter by state.                      |
| `phoneNumber`    | Which of your lines took it.          |
| `userId`         | Whose voicemail.                      |
| `since`          | ISO 8601 timestamp.                   |

`unreadOnly=true` is the one to build on: poll it, or better, subscribe to the event and let the webhook tell you.

## Mark one handled

```bash
curl -X PATCH https://app.limecall.com/api/v1/voicemails/551 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"status":"read"}'
```

Update status once your own system has dealt with it, so the unread queue means something.

## Worth knowing

Voicemails are transcribed, so you can route on the text rather than making someone listen first — send the transcript to a triage step and only escalate what matters.

If you are building a voicemail workflow at all, consider whether the AI receptionist removes the need for one: most callers do not leave voicemails, and an AI that answers converts the ones who would have hung up. See [Voicemail](/virtual-numbers/voicemail.md).