--- title: "Create inbox" method: POST path: "/v2/api/inboxes" tags: ["Inboxes"] --- # Create inbox `POST /v2/api/inboxes` ## Request - Base URL: `https://api.withallo.com` - URL: `https://api.withallo.com/v2/api/inboxes` - Auth: API key in header `Authorization` 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. ## Request body - object - `name` string, required: Required and non-blank. - `emoji` string, nullable - `sources` InboxSourceInput[], required - `allo_number` string, required: Allo line (E.164). Each line appears once in `sources`. - `conditions` InboxCondition[]: Empty or absent 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. - InboxMenuBranchStep[] - … - `include_no_choice` boolean, required: Also match calls that reached the menu without pressing a key. - `filters` InboxFilters: 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 - `user_id` string: Create the inbox for this teammate (`usr-*`). The caller must be an admin or manager of that teammate's workspace. ## Response `201` Inbox created - 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 - `400`: Invalid request parameters - `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/post.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)