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

# Create inbox

> Creates an inbox for the caller, or for a teammate with `user_id` in the body. Every source line must be accessible to the inbox owner. Up to 50 inboxes per user. Size limits (`name` over 80 characters, `emoji` over 16, more than 100 sources or 10 conditions per source) return `400` `INVALID_REQUEST_BODY` with `field_errors`. A menu path not listed by the line's `menu_options`, or a null source, condition or digit, returns `400` `INVALID_INBOX_SOURCE`. Menu conditions are only accepted on a line whose `menu_options` list is not empty, with paths from that list; on other lines use a whole-line source (empty `conditions`). For a teammate, the inbox must hold at least one line of the caller's workspace.

> [!NOTE]
>
> **Required scope:** `INBOXES_WRITE`

## Behavior

Creates an inbox owned by the caller and returns it with `201`. Send `user_id` in the JSON body to create it for a teammate instead: the inbox is owned by the teammate and shows in the teammate's inbox switcher. Only admins and managers of the teammate's workspace can do that.

Every source line must be accessible to the inbox owner, with the same line access rules as the app. A source with an empty `conditions` list covers the whole line. Build sources from the `source` of [inbox suggestions](https://help.withallo.com/en/v2/api-reference/inboxes/get-inbox-suggestions.md), or from the `condition` of [menu options](https://help.withallo.com/en/v2/api-reference/inboxes/list-menu-options.md).

Menu conditions are only accepted on a line whose menu options list is not empty. On any other line, use a whole-line source.

Each line appears once in `sources`. To cover several menu options of one line, put all their paths in the `branches` of a single `MENU_BRANCH` condition.

## Errors

| Status | Code | When |
| - | - | - |
| `400` | `INBOX_NAME_REQUIRED` | `name` is missing or blank |
| `400` | `INVALID_INBOX_SOURCE` | A source, condition or digit is null or invalid, a menu path is not in that line's [menu options](https://help.withallo.com/en/v2/api-reference/inboxes/list-menu-options.md), two sources share an `allo_number`, or a teammate inbox would have no line in the caller's workspace |
| `400` | `INVALID_REQUEST_BODY` | `name` over 80 characters, `emoji` over 16, more than 100 sources, or more than 10 conditions in a source. `field_errors` names each field |
| `400` | `INVALID_INBOX_FILTERS` | `filters` has an unknown key or an invalid value |
| `400` | `INBOX_LIMIT_REACHED` | The inbox owner already has 50 inboxes |
| `403` | `FORBIDDEN` | `user_id` is set and the caller is not an admin or manager of that teammate's workspace |
| `403` | `ALLO_NUMBER_FORBIDDEN` | A source line is not accessible to the inbox owner, or, with `user_id`, is not in a workspace the caller manages |


## OpenAPI

````yaml POST /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:
    post:
      tags:
        - Inboxes
      summary: Create inbox
      description: >-
        Creates an inbox for the caller, or for a teammate with `user_id` in the
        body. Every source line must be accessible to the inbox owner. Up to 50
        inboxes per user. Size limits (`name` over 80 characters, `emoji` over
        16, more than 100 sources or 10 conditions per source) return `400`
        `INVALID_REQUEST_BODY` with `field_errors`. A menu path not listed by
        the line's `menu_options`, or a null source, condition or digit, returns
        `400` `INVALID_INBOX_SOURCE`. Menu conditions are only accepted on a
        line whose `menu_options` list is not empty, with paths from that list;
        on other lines use a whole-line source (empty `conditions`). For a
        teammate, the inbox must hold at least one line of the caller's
        workspace.
      operationId: createInbox
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 80
                  example: Sales
                  description: Required and non-blank.
                emoji:
                  type: string
                  nullable: true
                  maxLength: 16
                  example: 💼
                sources:
                  type: array
                  maxItems: 100
                  items:
                    $ref: '#/components/schemas/InboxSourceInput'
                filters:
                  allOf:
                    - $ref: '#/components/schemas/InboxFilters'
                  nullable: true
                notifications_muted:
                  type: boolean
                  example: false
                user_id:
                  type: string
                  description: >-
                    Create the inbox for this teammate (`usr-*`). The caller
                    must be an admin or manager of that teammate's workspace.
                  example: usr-abc123
              required:
                - name
                - sources
            example:
              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
      responses:
        '201':
          description: Inbox created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $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
        '400':
          $ref: '#/components/responses/ApiValidationError'
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '403':
          $ref: '#/components/responses/ApiForbidden'
        '429':
          $ref: '#/components/responses/ApiRateLimited'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    InboxSourceInput:
      type: object
      properties:
        allo_number:
          type: string
          description: Allo line (E.164). Each line appears once in `sources`.
          example: '+33612345678'
        conditions:
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/InboxCondition'
          description: Empty or absent means every conversation on the line.
      required:
        - allo_number
    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.
    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
    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'
    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
    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:
    ApiValidationError:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    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.