Retrieve Phone Numbers

Retrieve Phone Numbers that a business has registered for their WhatsApp Business Account using the WhatsApp Business Management API.

Before You Start

You will need:

• The WhatsApp Business Account ID for the business' phone numbers you want to retrieve
• A System User access token linked to your WhatsApp Business Account
• The whatsapp_business_management permission

Limitations

• This API can only retrieve phone numbers that have been registered. Adding, updating, or deleting phone numbers is not permitted using the API.

Get All Phone Numbers

To get a list of all phone numbers associated with a WhatsApp Business Account, send a GET request to the WhatsApp Business Account > Phone Numbers endpoint.

In addition, phone numbers can be sorted in either ascending or descending order by last_onboarded_time, which is based on when the user completed onboarding for Embedded Signup. If not specified, the default order is descending.

Sample Request

curl -X GET "https://graph.facebook.com/v21.0/{whatsapp-business-account-id}/phone_numbers
      ?access_token={system-user-access-token}"

On success, a JSON object is returned with a list of all the business names, phone numbers, phone number IDs, and quality ratings associated with a business. Results are sorted by embedded signup completion date in descending order, with the most recently onboarded listed first.

{
  "data": [
    {
      "verified_name": "Jasper's Market",
      "display_phone_number": "+1 631-555-5555",
      "id": "1906385232743451",
      "quality_rating": "GREEN"
      
    },
    {
      "verified_name": "Jasper's Ice Cream",
      "display_phone_number": "+1 631-555-5556",
      "id": "1913623884432103",
      "quality_rating": "NA"
    }
  ]
}

Sample Request

curl -X GET "https://graph.facebook.com/v21.0/{whatsapp-business-account-id}/phone_numbers
      ?access_token={system-user-access-token}]&sort=['last_onboarded_time_ascending']"

On success, a JSON object is returned with a list of all the business names, phone numbers, phone number IDs, and quality ratings associated with a business. It is sorted based on when the user has completed embedded signup in ascending order, with the most recently onboarded listed last.

{
  "data": [
   {
      "verified_name": "Jasper's Ice Cream",
      "display_phone_number": "+1 631-555-5556",
      "id": "1913623884432103",
      "quality_rating": "NA"
    },
    {
      "verified_name": "Jasper's Market",
      "display_phone_number": "+1 631-555-5555",
      "id": "1906385232743451",
      "quality_rating": "GREEN"     
    }   
  ]
}

Filter Phone Numbers

You can query phone numbers and filter them based on their account_mode. This filtering option is currently being tested in beta mode. Not all developers have access to it.

Parameters

Sample Request

curl -i -X GET "https://graph.facebook.com/v21.0/{whatsapp-business-account-ID}/phone_numbers?filtering=[{"field":"account_mode","operator":"EQUAL","value":"SANDBOX"}]&access_token=access-token"

Sample Response

{
  "data": [
    {
      "id": "1972385232742141",    
      "display_phone_number": "+1 631-555-1111",
      "verified_name": "John’s Cake Shop",
      "quality_rating": "UNKNOWN",
    }
  ],
  "paging": {
	"cursors": {
		"before": "abcdefghij",
		"after": "klmnopqr"
	}
   }
}

Get a Single Phone Number

To get information about a phone number, send a GET request to the WhatsApp Business Phone Number endpoint:

Request Syntax

GET https://graph.facebook.com/<API_VERSION>/<PHONE_NUMBER_ID>

Sample Request

curl \
'https://graph.facebook.com/v15.0/105954558954427/' \
-H 'Authorization: Bearer EAAFl...'

On success, a JSON object is returned with the business name, phone number, phone number ID, and quality rating for the phone number queried.

{
  "code_verification_status" : "VERIFIED",
  "display_phone_number" : "15555555555",
  "id" : "105954558954427",
  "quality_rating" : "GREEN",
  "verified_name" : "Support Number"
}

Get Display Name Status (Beta)

Include fields=name_status as a query string parameter to get the status of a display name associated with a specific phone number. This field is currently in beta and not available to all developers.

Sample Request

curl \
'https://graph.facebook.com/v15.0/105954558954427?fields=name_status' \
-H 'Authorization: Bearer EAAFl...'

Sample Response

{
  "id" : "105954558954427",
  "name_status" : "AVAILABLE_WITHOUT_REVIEW"
}

The name_status value can be one of the following:

• APPROVED: The name has been approved. You can download your certificate now.
• AVAILABLE_WITHOUT_REVIEW: The certificate for the phone is available and display name is ready to use without review.
• DECLINED: The name has not been approved. You cannot download your certificate.
• EXPIRED: Your certificate has expired and can no longer be downloaded.
• PENDING_REVIEW: Your name request is under review. You cannot download your certificate.
• NONE: No certificate is available.

Note that certificates are valid for 7 days.

Learn More

For a list of all possible values for each field, refer to the Graph API reference of the Phone Number field.