whatsapp-business-accounts

Get a WhatsApp Business Account

Returns one WhatsApp Business Account your workspace has connected, addressed by either the id the account list reports (waa_ prefix) or the waba value WhatsApp reports for it. Both forms resolve to the same account.

Only accounts whose setup finished can be read: an account is readable once WhatsApp has reported its name and at least one of its phone numbers has finished connecting. An account the list hides is 404 here too, in either form.

The account carries the state WhatsApp last reported for it: its own status, how far WhatsApp's review of it has got, whether Meta has verified the business behind it, and the Meta business portfolio that owns it.

An account WhatsApp has banned carries ban, with an appeal_url to Meta Business Support once Bird knows the account's portfolio. ban is what WhatsApp announced on its own notification, not part of the reading meta_synced_at dates, because WhatsApp reports a ban's state and timing nowhere else. It is absent on an account in good standing and on one whose ban Bird was never told about, so status is what says whether an account can send.

get/v1/whatsapp/business-accounts/{business_account_ref}

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/whatsapp/business-accounts/{business_account_ref}
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Headers

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

The WhatsApp Business Account.

idstring required
wabastring required

Meta's own identifier for this WhatsApp Business Account. This is the value to send when creating a template on the account.

namestring required

The account's name, as WhatsApp reports it.

statusstring 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_statusstring

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_statusstring

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_statusstring

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.

meta_synced_atstring 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_atstring date-time required

When this account was connected.

updated_atstring date-time required

When this account was last changed.

Example response

{
  "id": "waa_01krdgeqcxet5s7t44vh8rt9mg",
  "waba": "102290129340398",
  "name": "Acme Inc",
  "status": "active",
  "account_review_status": "approved",
  "business_verification_status": "verified",
  "marketing_messages_onboarding_status": "onboarded",
  "portfolio": {
    "meta_id": "178563218361309",
    "name": "Acme Holdings",
    "marketing_messages_onboarding_status": "not_started"
  },
  "ban": {
    "state": "disabled",
    "occurred_at": "2026-04-10T09:12:00Z",
    "appeal_url": "https://business.facebook.com/business-support-home/178563218361309/102290129340398"
  },
  "meta_health_status": {
    "can_send_message": "blocked",
    "entities": [
      {
        "entity_type": "waba",
        "meta_id": "1028574859896003",
        "can_send_message": "blocked",
        "errors": [
          {
            "error_code": 141006,
            "error_description": "There is an error with the payment method. This will block business initiated conversations.",
            "possible_solution": "There was an error with your payment method. Please add a new payment method to the account."
          }
        ]
      },
      {
        "entity_type": "business",
        "meta_id": "4392746181043198",
        "can_send_message": "limited",
        "errors": [
          {
            "error_code": 141010,
            "error_description": "The Business has not passed business verification.",
            "possible_solution": "Visit business settings and start or resolve the business verification request."
          }
        ]
      },
      {
        "entity_type": "app",
        "meta_id": "497937228432800",
        "can_send_message": "available"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 3 revisions of this API.