---
title: "List inboxes"
method: GET
path: "/v2/api/inboxes"
tags: ["Inboxes"]
---

# List inboxes

`GET /v2/api/inboxes`

## Request

- Base URL: `https://api.withallo.com`
- URL: `https://api.withallo.com/v2/api/inboxes`
- Auth: API key in header `Authorization`

Returns the caller's inboxes. With `user_id`, returns a teammate's inboxes that have at least one source in a workspace the caller manages, showing only those sources.

## Query parameters

- `user_id` string

## Response `200`

The inboxes

- object
  - `data` Inbox[]
    - `id` string, required
    - `name` string, required
    - `emoji` string, nullable, required
    - `sources` InboxSource[], required
      - `allo_number` string, required: Allo line (E.164).
      - `conditions` InboxCondition[], required: Empty means every conversation on the line.
        - union: Narrows a source to calls that went through part of the line's phone menu. A source holds at most 10 conditions, and an inbox at most 60 menu steps in all.
          - InboxMenuOptionCondition: Matches keys of one phone menu.
            - `type` 'MENU_OPTION', required
            - `node_id` string, required: The menu node.
            - `digits` string[], required: Keys that match, distinct. May be `[]` only when `include_no_choice` is `true`, to match calls that reached the menu without pressing a key.
            - `include_no_choice` boolean, required: Also match calls that reached the menu without pressing a key.
          - InboxMenuBranchCondition: Matches any of several paths through the line's phone menus. To combine several options of one line, put all their paths in `branches`.
            - `type` 'MENU_BRANCH', required
            - `branches` array[], required: Each branch lists the menu choices from the first menu down to the option picked.
              - …
            - `include_no_choice` boolean, required: Also match calls that reached the menu without pressing a key.
    - `filters` InboxFiltersResponse, required: Saved filters, with the same meaning as the conversation list filters in the app. "Unread only" is not saved on an inbox: use the `unread` query parameter of List conversations.
      - `types` string[]
      - `user_ids` string[]: Teammates (`usr-*`), up to 50.
      - `contact_ids` string[]: Contacts, up to 50.
      - `contact_list_ids` string[]: Contact lists, up to 10.
      - `tag_keys` string[]: Call tag keys (AI or manual tags, from `GET /v2/api/tags`), up to 20. A conversation matches when any of its calls on the inbox's lines has one of these tags, not only the last call. Each key must be a tag of your workspace.
    - `notifications_muted` boolean, required
    - `favorited_at` string, date-time, nullable, required: When the owner starred the inbox, `null` when it is not a favorite. Favorites show first in the app's inbox switcher, oldest star first.

## Other responses

- `401`: Invalid or missing API key
- `403`: API key lacks the required scope or access to the resource
- `429`: Rate limit exceeded

## Changes

- **2026-11-03** `46c77103dd14`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/withallo/apis/allo-api/changes/v2/api/inboxes/get.md)

---

[API](https://skmtc.dev/withallo/apis/allo-api.md) - [All operations](https://skmtc.dev/withallo/apis/allo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/withallo/apis/allo-api/revisions/46c77103dd14?raw)