MEmeta
Phone Number Management

Get WhatsApp Business Account Phone Numbers

Retrieve all phone numbers associated with a WhatsApp Business Account, including their status, verification details, and configuration information.

Use Cases:

  • List all phone numbers in a WhatsApp Business Account
  • Monitor phone number status and verification progress
  • Check phone number quality ratings and messaging limits
  • Retrieve phone number configuration details

Filtering: You can filter results using the filtering parameter with JSON-encoded filter conditions. Supported filters include account_mode, messaging_limit_tier, and is_official_business_account.

Sorting: Results can be sorted by creation_time or last_onboarded_time in ascending or descending order.

Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff.

Caching: Phone number data can be cached for short periods, but status information may change frequently. Implement appropriate cache invalidation strategies.

get/{Version}/{WABA-ID}/phone_numbers

Request

  • Base URL
    https://graph.facebook.com
  • URL
    https://graph.facebook.com/{Version}/{WABA-ID}/phone_numbers
  • Auth
    HTTP bearer

Path parameters

Versionstring required

Graph API version to use for this request. Determines the API behavior and available features.

WABA-IDstring required

WhatsApp Business Account ID. This ID can be found in your WhatsApp Manager or through the business management APIs.

Query parameters

fieldsstring

Comma-separated list of fields to include in the response. If not specified, default fields will be returned. Available fields include: id, display_phone_number, verified_name, status, quality_rating, country_code, country_dial_code, code_verification_status, unified_cert_status, account_mode, host_platform, messaging_limit_tier, is_official_business_account, username

filteringstring

JSON-encoded array of filter conditions. Each filter should specify field, operator, and value. Supported fields: account_mode, messaging_limit_tier, is_official_business_account

sort'creation_time.asc' | 'creation_time.desc' | 'last_onboarded_time.asc' | 'last_onboarded_time.desc'

Sort field and direction. Format: field_name.asc or field_name.desc Supported fields: creation_time, last_onboarded_time

limitinteger

Maximum number of phone numbers to return per page

afterstring

Cursor for pagination - retrieve records after this cursor

beforestring

Cursor for pagination - retrieve records before this cursor

Headers

User-Agentstring
Example:Meta-Business-Messaging-OpenAPI/1.0.0;spec=2025-10-21

The user agent string identifying the client software making the request.

Authorizationstring required
Example:Bearer EAABwzLixnjYBOzYmNMJJGfHq9DgNh...

Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.

Response

Successfully retrieved WhatsApp Business Account phone numbers

Example response

{
  "data": [
    {
      "id": "1906385232743451",
      "display_phone_number": "+1 631-555-5555",
      "verified_name": "Jasper's Market",
      "status": "PENDING",
      "quality_rating": "GREEN",
      "country_code": "US",
      "country_dial_code": "1",
      "code_verification_status": "VERIFIED",
      "unified_cert_status": "APPROVED",
      "account_mode": "LIVE",
      "host_platform": "CLOUD_API",
      "messaging_limit_tier": "TIER_1K",
      "is_official_business_account": true,
      "username": "business_username"
    }
  ],
  "paging": {
    "cursors": {
      "before": "QVFIUjNpUWpVWmRBd0dn",
      "after": "QVFIUjNpUWpVWmRBd0Rn"
    },
    "previous": "https://graph.facebook.com/v23.0/1234567890/connected_client_businesses?before=QVFIUjNpUWpVWmRBd0Dn",
    "next": "https://graph.facebook.com/v23.0/1234567890/connected_client_businesses?after=QVFIUjNpUWpVWmRBd0Rn"
  }
}

Changes

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