> ## Documentation Index > Fetch the complete documentation index at: https://help.withallo.com/llms.txt > Use this file to discover all available pages before exploring further. # List inboxes > 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. > [!NOTE] > > **Required scope:** `INBOXES_READ` ## Behavior Returns the caller's inboxes. Pass the `user_id` query parameter to list a teammate's inboxes instead. Only admins and managers of the teammate's workspace can do that. The list then shows only the teammate's inboxes with at least one source in a workspace the caller manages, and only those sources. `filters` is always returned with every key. Sources on a line the inbox owner can no longer access are left out of `sources`. ## Errors | Status | Code | When | | - | - | - | | `403` | `FORBIDDEN` | `user_id` is set and the caller is not an admin or manager of that teammate's workspace | ## OpenAPI ````yaml GET /v2/api/inboxes openapi: 3.0.3 info: title: Allo API description: >- Allo API provides programmatic access to your Allo account, allowing you to manage webhooks, retrieve calls and contacts, and send SMS messages. All requests to `/v1/api/**` endpoints automatically go through quota checking and scope validation. version: 1.0.0 contact: name: Allo Support servers: - url: https://api.withallo.com description: Production server security: [] tags: - name: Summary Templates description: >- Manage call summary templates that control how AI-generated call summaries are structured for your team. - name: Webhooks description: >- Manage webhook endpoints to receive real-time notifications about events in your Allo account. Each endpoint subscribes to one or more event topics and is verified with a signing secret. - name: Calls description: >- Retrieve and search call records with filtering and pagination. Filter calls by your Allo phone number. - name: Contacts description: >- Search and retrieve contact information with sorting and pagination. Includes engagement level tracking. - name: SMS description: Send SMS messages to phone numbers using your Allo numbers. - name: Phone Numbers description: Retrieve information about your Allo phone numbers. - name: Analytics description: Pre-computed call metrics, team performance, and outbound dial funnel - name: CRM description: Manage people, companies, and deals in your CRM. - name: Notes description: >- Internal team notes on conversations and CRM people, with @mention support. Notes are never visible to the contact. - name: Threads description: >- Team discussion threads attached to a conversation item (call, SMS, or conversation note). One thread per item. - name: AI Receptionist description: >- Read and write the AI receptionist configuration of a phone line: business details, voice, prompt, capabilities, business hours, transfer rules, scheduling calendars and knowledge sources. - name: Inboxes description: >- Personal inboxes: saved views of one or more lines, optionally narrowed to phone-menu options, with their own filters and notification setting. paths: /v2/api/inboxes: get: tags: - Inboxes summary: List inboxes description: >- 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. operationId: listInboxes parameters: - name: user_id in: query description: >- Act on a teammate's inbox (`usr-*`). The caller must be an admin or manager of that teammate's workspace, and only reaches inboxes and sources in workspaces they manage. Omit to act on your own inboxes. schema: type: string example: usr-abc123 responses: '200': description: The inboxes content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Inbox' example: data: - id: inb-abc123 name: Sales emoji: 💼 sources: - allo_number: '+33612345678' conditions: - type: MENU_BRANCH branches: - - node_id: node-1 digit: '1' - node_id: node-3 digit: '2' include_no_choice: false filters: types: - INBOUND_CALL user_ids: [] contact_ids: [] contact_list_ids: [] notifications_muted: false '401': $ref: '#/components/responses/ApiUnauthorized' '403': $ref: '#/components/responses/ApiForbidden' '429': $ref: '#/components/responses/ApiRateLimited' security: - ApiKeyAuth: [] components: schemas: Inbox: type: object properties: id: type: string example: inb-abc123 name: type: string example: Sales emoji: type: string nullable: true example: 💼 sources: type: array items: $ref: '#/components/schemas/InboxSource' filters: $ref: '#/components/schemas/InboxFiltersResponse' notifications_muted: type: boolean example: false required: - id - name - emoji - sources - filters - notifications_muted InboxSource: type: object properties: allo_number: type: string description: Allo line (E.164). example: '+33612345678' conditions: type: array items: $ref: '#/components/schemas/InboxCondition' description: Empty means every conversation on the line. maxItems: 10 required: - allo_number - conditions InboxFiltersResponse: allOf: - $ref: '#/components/schemas/InboxFilters' required: - types - user_ids - contact_ids - contact_list_ids description: The saved filters, always returned with every key. ApiError: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean request_id: type: string retry_after_seconds: type: integer nullable: true InboxCondition: description: >- 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. oneOf: - $ref: '#/components/schemas/InboxMenuOptionCondition' - $ref: '#/components/schemas/InboxMenuBranchCondition' discriminator: propertyName: type mapping: MENU_OPTION: '#/components/schemas/InboxMenuOptionCondition' MENU_BRANCH: '#/components/schemas/InboxMenuBranchCondition' InboxFilters: type: object description: >- 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. properties: types: type: array items: type: string enum: - INBOUND_CALL - OUTBOUND_CALL - TRANSFERRED - INBOUND_TEXT_MESSAGE - OUTBOUND_TEXT_MESSAGE - VOICEMAIL - AI_ASSISTANT example: - INBOUND_CALL user_ids: type: array items: type: string description: Teammates (`usr-*`), up to 50. example: [] maxItems: 50 contact_ids: type: array items: type: string example: [] maxItems: 50 description: Contacts, up to 50. contact_list_ids: type: array items: type: string example: [] maxItems: 10 description: Contact lists, up to 10. InboxMenuOptionCondition: type: object description: Matches keys of one phone menu. properties: type: type: string enum: - MENU_OPTION node_id: type: string description: The menu node. example: node-3 digits: type: array items: type: string pattern: ^[0-9]$ description: >- Keys that match, distinct. May be `[]` only when `include_no_choice` is `true`, to match calls that reached the menu without pressing a key. example: - '1' include_no_choice: type: boolean description: Also match calls that reached the menu without pressing a key. example: false required: - type - node_id - digits - include_no_choice InboxMenuBranchCondition: type: object description: >- Matches any of several paths through the line's phone menus. To combine several options of one line, put all their paths in `branches`. properties: type: type: string enum: - MENU_BRANCH branches: type: array minItems: 1 maxItems: 20 description: >- Each branch lists the menu choices from the first menu down to the option picked. items: type: array minItems: 1 maxItems: 6 items: $ref: '#/components/schemas/InboxMenuBranchStep' include_no_choice: type: boolean description: Also match calls that reached the menu without pressing a key. example: false required: - type - branches - include_no_choice InboxMenuBranchStep: type: object properties: node_id: type: string description: ID of the phone-menu node in the line's published call flow. example: node-3 digit: type: string pattern: ^[0-9*#]$ description: Key pressed at that menu. example: '2' required: - node_id - digit responses: ApiUnauthorized: description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiForbidden: description: API key lacks the required scope or access to the resource content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiRateLimited: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.