--- title: "List WhatsApp Business Accounts" method: GET path: "/v1/whatsapp/business-accounts" tags: ["whatsapp-business-accounts"] --- # List WhatsApp Business Accounts `GET /v1/whatsapp/business-accounts` ## Request - Base URL: `https://us1.platform.bird.com` - URL: `https://us1.platform.bird.com/v1/whatsapp/business-accounts` - Auth: one of: - HTTP bearer - API key in cookie `bird_session` Returns a paginated list of the WhatsApp Business Accounts your workspace has connected, so you can choose which one a template belongs to. Only accounts whose setup finished are listed: an account appears once WhatsApp has reported its name and at least one of its phone numbers has finished connecting. Page through the full set with the cursors the response returns. Each account also carries the state WhatsApp last reported for it. That covers its own status, how far WhatsApp's review of it has got, whether Meta has verified the business behind it, the Meta business portfolio that owns it, and `ban` on an account WhatsApp has banned. These are the same fields [Get a WhatsApp Business Account](/docs/api/reference/get-whatsapp-business-account) returns, and that operation documents them. ## Query parameters - `sort` 'created_at': Sortable fields for a WhatsApp Business Account list. - `order` 'asc' | 'desc': Sort direction, ascending or descending. - `limit` integer - `starting_after` string - `ending_before` string ## Headers - `X-Workspace-Id` string - `X-Organization-Id` string ## Response `200` A page of the WhatsApp Business Accounts your workspace has connected. - WhatsAppBusinessAccountList - `data` WhatsAppBusinessAccount[], required: The WhatsApp Business Accounts your workspace has connected. - `id` string, required - `waba` string, required: Meta's own identifier for this WhatsApp Business Account. This is the value to send when creating a template on the account. - `name` string, required: The account's name, as WhatsApp reports it. - `status` string, required: WhatsApp's own state for a WhatsApp Business Account. Values are WhatsApp's own tokens, lower-cased. This enum is open because WhatsApp documents the field in neither its API reference nor its machine-readable schema. The `active` value is the only value in WhatsApp's example response, so it is the only one Bird can name. Treat anything else as a state WhatsApp reports and this list has not caught up with. - `account_review_status` string: How far WhatsApp's own review of this WhatsApp Business Account has got. `deferred` is WhatsApp postponing the review rather than refusing it. Values are WhatsApp's own tokens, lower-cased. Open enum: treat an unrecognized value as a review state WhatsApp added rather than as an error. - `business_verification_status` string: Whether Meta has verified the business behind this WhatsApp Business Account. Verification is one of the paths to a higher messaging limit, so a value other than `verified` is often the reason a limit has not moved. Values are Meta's own tokens, lower-cased. Open enum: treat an unrecognized value as a state Meta added rather than as an error. - `marketing_messages_onboarding_status` string: Whether this account can use WhatsApp's Marketing Messages API. `eligible` means WhatsApp would accept an onboarding request for it; `onboarded` means it has already been onboarded. Values are WhatsApp's own tokens, lower-cased. Open enum out of necessity. WhatsApp's onboarding guide names these two values and defers the rest to an API reference that does not document the field. Treat anything else as a state WhatsApp reports that this list has not caught up with. - `portfolio` WhatsAppBusinessPortfolio: The Meta business portfolio that owns a WhatsApp Business Account. Bird holds no resource of its own for a portfolio, which is why the identifier is named `meta_id`: it is meaningful only against Meta's own tools, and it is not a Bird identifier. - `meta_id` string, required: Meta's identifier for the portfolio. Treat it as an opaque string. - `name` string: The portfolio's name, as Meta reports it. Absent when Meta returned none. - `marketing_messages_onboarding_status` string: How far the business portfolio has got through Meta's Marketing Messages terms of service. - `not_started`: the portfolio has not begun the process. - `request_sent`: a request is in. - `term_of_service_signed`: the terms are accepted. A portfolio property, so every account the portfolio owns reports the same value. Distinct from the account's own marketing-messages status, which Meta confusingly gives the same name. Values are Meta's own tokens, lower-cased. Open enum: treat an unrecognized value as a state Meta added rather than as an error. - `ban` WhatsAppBusinessAccountBan: WhatsApp's ban on this account, as WhatsApp announced it. Absent when there is no ban, and also when there is one WhatsApp announced before Bird began recording bans, or whose notification never reached Bird, since WhatsApp does not replay them. This is what WhatsApp announced rather than the account's current state, so it is never the field to read to decide whether an account can send. - `state` 'disabled' | 'scheduled_for_disable', required: Whether WhatsApp has disabled a WhatsApp Business Account or scheduled it to be disabled: - `disabled`: WhatsApp has disabled the account, and it cannot send. - `scheduled_for_disable`: WhatsApp has set a date to disable the account, which can still send until then. An account WhatsApp has reinstated reports no `ban` at all rather than a third value here. - `occurred_at` string, date-time, required: When WhatsApp reported the ban, by WhatsApp's own clock. Bird can learn of a ban later than this, so it is not when Bird recorded it. - `appeal_url` string, uri: Where to appeal WhatsApp's decision with Meta Business Support, because neither Bird nor this API can lift one. Absent when Bird does not know the account's Meta business portfolio, since there is no support-home path to build without one. - `meta_health_status` WhatsAppMetaHealthStatus: Meta's own messaging health for this account. `can_send_message` is Meta's aggregate: `blocked` if any entity is blocked, else `limited` if any is limited, else `available`. Read `entities` to see which node carries the verdict and why. - `can_send_message` 'available' | 'limited' | 'blocked', required: Meta's health verdict for one entity, or for the whole chain when read at the top level. Values are Meta's own tokens, lower-cased: - `available`: the entity meets every messaging or calling requirement. - `limited`: it can be used, but with a limitation Meta describes in `additional_info` when it gave one. - `blocked`: it cannot be used. `errors` says why when Meta named a reason, and each error carries `possible_solution` when Meta suggested one. - `entities` WhatsAppMetaHealthEntity[], required: One entry per node Meta evaluated. Order is Meta's. - `entity_type` string, required: Which node in Meta's messaging chain an entry describes. Values are Meta's own tokens, lower-cased. - `waba`: the WhatsApp Business Account. - `business`: the Meta business portfolio that owns the account. - `app`: the app the account messages through. - `phone_number`: a business phone number. An account read never carries one: Meta reports it only when a phone number is the node asked about. - `message_template`: a message template. An account read never carries one: Meta reports it only when a template is the node asked about. - `meta_id` string, required: Meta's identifier for the node. Treat it as an opaque string. - `can_send_message` 'available' | 'limited' | 'blocked', required: Meta's health verdict for one entity, or for the whole chain when read at the top level. Values are Meta's own tokens, lower-cased: - `available`: the entity meets every messaging or calling requirement. - `limited`: it can be used, but with a limitation Meta describes in `additional_info` when it gave one. - `blocked`: it cannot be used. `errors` says why when Meta named a reason, and each error carries `possible_solution` when Meta suggested one. - `can_receive_call_sip` 'available' | 'limited' | 'blocked': Meta's health verdict for one entity, or for the whole chain when read at the top level. Values are Meta's own tokens, lower-cased: - `available`: the entity meets every messaging or calling requirement. - `limited`: it can be used, but with a limitation Meta describes in `additional_info` when it gave one. - `blocked`: it cannot be used. `errors` says why when Meta named a reason, and each error carries `possible_solution` when Meta suggested one. - `additional_info` string[]: Meta's own notes on a `limited` verdict. Absent on an account read: Meta reports it only when a phone number or template is the node asked about. - `errors` WhatsAppMetaHealthError[]: Why this node is not `available`. Absent when Meta gave no reason. - `error_code` integer, required: Meta's numeric health error code, for example `141006` (payment method error), `141010` (business not verified), `141014` (account banned). - `error_description` string, required: Meta's own sentence describing the block. - `possible_solution` string: Meta's own suggested remedy. Absent when Meta gave none. - `meta_synced_at` string, date-time: When Bird last read this account's state from WhatsApp. `status`, `account_review_status`, `business_verification_status`, `marketing_messages_onboarding_status`, `portfolio` and `meta_health_status` are all that reading rather than live values; Bird re-reads roughly hourly. Absent for an account Bird has never read back. - `created_at` string, date-time, required: When this account was connected. - `updated_at` string, date-time, required: When this account was last changed. - `next_cursor` string, nullable, required: Cursor for the next page. Pass back as `starting_after` to advance forward. `null` when no next page exists. - `prev_cursor` string, nullable, required: Cursor for the previous page. Pass back as `ending_before` to step backward. `null` when no previous page exists. - `refresh_cursor` string, nullable, required: Refresh anchor, the first row of this response. Pass back as `ending_before` to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-`null` whenever `data` is non-empty; `null` only on an empty page. Distinct from `prev_cursor`. ## Other responses - `400`: Bad request - `401`: Authentication required - `403`: Insufficient permissions - `404`: Resource not found - `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`. - `429`: Rate limit exceeded - `500`: Internal server error --- [API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/3e2a50466454?raw)