Skip to main content

​
Business customer phone numbers

Updated: Nov 4, 2025 This document describes business customer phone numbers, their requirements, and endpoints commonly used to manage business phone numbers.

​
Basics

Your business customers need a dedicated number to use WhatsApp. Phone numbers already in use with the WhatsApp app are not supported, but numbers in use with the WhatsApp Business app can be registered. Business customers can have multiple phone numbers associated with their Meta Business Account, so they can add another number for API use if they wish. When completing the Embedded Signup flow, your business customers should use a phone number and display name that they want to have appear in the WhatsApp app. We strongly discourage signing up with a test or personal number, or test display name, as are difficult to change. For more detailed information relating to phone numbers and WhatsApp for Business Platform, see Phone Numbers. For information on how to migrate an existing registered WhatsApp phone number, see Migrate Phone Number.

​
Instructions for business customers

This section is directed towards customers of Embedded Signup and provides guidance about actions they may perform relating to phone numbers.

​
Add Phone Numbers to a WhatsApp Business Account

There are two methods to add additional numbers to a WhatsApp Business Account (WABA): [Recommended] Go through the embedded signup flow again, select the existing Business Manager & WABA, add the number, and verify it. In the Business Manager, go to the Phone Numbers tab of WhatsApp Manager, and select Add Phone Number. When using this option, the Solution Partner has to manually verify the phone number as phone verification is not available in the Business Manager. For this reason, it is recommended that businesses follow the embedded signup flow to add additional numbers.

​
Instructions for Solution Partners

This section is directed towards Solution Partners and provides instructions for managing customer phone numbers and certificates.

​
Getting phone numbers

Use the GET /<WABA_ID>/phone_numbers endpoint to get a list of business phone numbers on a business customer’s WABA.

​
Request

curl 'https://graph.facebook.com/&lt;API_VERSION&gt;/&lt;CUSTOMER_WABA_ID&gt;/phone_numbers' \
-H 'Authorization: Bearer &lt;CUSTOMER_BUSINESS_TOKEN&gt;'

​
Response

Upon success: 
\{
  "data": [\
    {\
      "verified_name": "&lt;VERIFIED_DISPLAY_NAME&gt;",\
      "code_verification_status": "&lt;VERIFICATION_STATUS&gt;",\
      "display_phone_number": "&lt;DISPLAY_PHONE_NUMBER&gt;",\
      "quality_rating": "&lt;QUALITY_RATING&gt;",\
      "platform_type": "CLOUD_API",\
      "throughput": {\
        "level": "&lt;THROUGHPUT_LEVEL&gt;"\
      },\
      "webhook_configuration": {\
        "application": "&lt;WEBHOOK_CALLBACK_URL&gt;"\
      },\
      "id": "&lt;BUSINESS_PHONE_NUMBER_ID&gt;"\
    }\
  ],
  "paging": {
    "cursors": {
      "before": "&lt;BEFORE_CURSOR&gt;",
      "after": "&lt;AFTER_CURSOR&gt;"
    }
  }
}

​
Register phone numbers

After a successful phone verification from the Embedded Signup flow, registration should succeed with an API call to the register endpoint. For this, provide any code_method (smsvoice). Since the phone number is already verified, you do not need to worry about the registration code.
Alternatively, you can pre-verify phone numbers and offer them to your customers in the new Embedded Signup flow. This prevents customers from having to contact you for a one-time password during the onboarding process. See Pre-Verified Phone Numbers. A phone number must be registered up to 14 days after going through the Embedded Signup flow. If a number is not registered during that window, the phone must go through to the Embedded Signup flow again prior to registration.

​
Get phone metadata

The phone_numbers endpoint allows you to see the status of a phone number’s display name and other metadata.

​
Example request

In the following example, use the ID for the assigned WABA. 
curl -i -X GET "https://graph.facebook.com/&lt;API_VERSION&gt;/&lt;WABA_ID&gt;/phone_numbers
  ?fields=
    display_phone_number,
    certificate,
    name_status,
    new_certificate,
    new_name_status
  &access_token=&lt;SYSTEM_USER_ACCESS_TOKEN&gt;"
To find the ID of a WhatsApp Business Account, go to Business Manager > Business Settings > Accounts > WhatsApp Business Accounts. Find the account you want to use and click on it. A panel opens, with information about the account, including the ID.

​
Example response

\{
  "data": [\
    {\
      "id": "1972385232742141",\
      "display_phone_number": "+1 631-555-1111",\
      "last_onboarded_time": "2023-08-22T19:05:53+0000",\
      "certificate": "AbCdEfGhIjKlMnOpQrStUvWxYz",\
      "new_certificate": "123AbCdEfGhIjKlMnOpQrStUvWxYz",\
      "name_status": "APPROVED",\
      "new_name_status": "APPROVED",\
    }\
  ]
}

​
Response parameters

NameDescription
name_statusThe review status of the current display name request. Available Options:
APPROVED: The name has been approved. You can download your certificate now.
DECLINED: The name has not been approved. You cannot download your certificate.
EXPIRED: Your certificate has expire and can no longer be downloaded.
PENDING_REVIEW: Your name request is under review. You cannot download your certificate.
NONE: No certificate is available.
new_name_statusThe review status of a display name change request. This field returns data only if a display name change was requested.
certificateReturns the current certificate for that phone number.
new_certificateThe certificate of a new display name, after a display name change has been approved. This field returns data only if a display name change request was approved and is available until the phone number has been registered with the new certificate.

​
Get phone’s OTP status

To see if a phone number has been verified via OTP (one-time password), check that number’s code_verification_status field. First, make a GET call to the /<whatsapp-business-account-id}/phone_numbers endpoint: 
curl -i -X GET \
"https://graph.facebook.com/&lt;API_VERSION&gt;/&lt;WABA_ID&gt;/phone_numbers
  ?access_token=&lt;ACCESS_TOKEN&gt;"
The response includes the code_verification_status with one of the following options: VERIFIED or NOT_VERIFIED. A sample response looks like this: 
[\
  {\
    "code_verification_status": "NOT_VERIFIED",\
    "id": "1754951608042154"\
  }\
]
Alternatively, you can get the status by calling a phone number’s ID: 
curl -i -X GET \
"https://graph.facebook.com/&lt;API_VERSION&gt;/&lt;PHONE_NUMBER_ID&gt;
  ?access_token=&lt;ACCESS_TOKEN&gt;"
Use the WhatsApp Business Account > Phone Numbers endpoint to get a phone number’s ID. See Retrieve Phone Numbers for usage details.

​
Filter phone numbers by account mode

You can query phone numbers and filter them based on their account_mode. For the request, you can use the parameters listed below.

​
Request parameters

NameDescription
fieldContains the field being used for filtering. In this example, you should use account_mode.
operatorContains how you want to filter the accounts. In this example, you should use EQUAL.
valueContain what account mode you are looking for. Supported Values:
SANDBOX: The account is unverified.
LIVE: The account is not eligible for the unverified trial experience or it has upgraded to a verified account.

​
Example request

In the following example, use the ID for the assigned WABA. 
curl -i -X GET "https://graph.facebook.com/&lt;API_VERSION&gt;/&lt;WABA_ID&gt;/phone_numbers
  ?filtering=[{\
    "field":"account_mode",\
    "operator":"EQUAL",\
    "value":"SANDBOX"}]
  &access_token=&lt;SYSTEM_USER_ACCESS_TOKEN&gt;"

​
Example 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"
  }
   }
}

​
Learn More

Phone numbers: WhatsApp for Business Platform Overview Phone numbers: Migrate an existing registered number Reference: WhatsApp Business Account Did you find this page helpful? Thumbs up icon Thumbs down icon ON THIS PAGE Basics Instructions for business customers Add Phone Numbers to a WhatsApp Business Account Instructions for Solution Partners Getting phone numbers Request Response Register phone numbers Get phone metadata Example request Example response Response parameters Get phone’s OTP status Filter phone numbers by account mode Request parameters Example request Example response Learn More