Skip to content

Playbook · 5 steps

Phone Number Verification

Also called: request_code · verify_code · Number ownership verification

5steps

Level
Practitioner
Reading time
About 5 min

Reviewed

Definition
Proving control of a WhatsApp business number with a one-time code sent by SMS or voice call, through the request_code and verify_code endpoints.

01 · How it works, in 5 steps

How does phone number verification work?

  1. 1

    Check the current status

    Call GET /{PHONE_NUMBER_ID}?fields=code_verification_status. If it already reads VERIFIED, skip straight to registration.

  2. 2

    Request a code

    Call POST /{PHONE_NUMBER_ID}/request_code with code_method=SMS, or VOICE for landlines and IVR numbers. Add a two-letter language code such as en for the SMS or call.

  3. 3

    Receive it on the number

    Someone with access to the line reads the code from the SMS or answers the call. For IVR numbers, route the call to a person or forward the line for a few minutes.

  4. 4

    Submit the code

    Call POST /{PHONE_NUMBER_ID}/verify_code with code. A correct code returns {"success": true}, and the status becomes VERIFIED.

  5. 5

    Register the number

    Continue with POST /{PHONE_NUMBER_ID}/register and the six-digit PIN to activate the number for messaging.

02Try it

Hands-on: use the controls to work through it yourself.

Send request_code and see what comes back

2 / 2
POSThttps://graph.facebook.com/v26.0/106540352242922/request_code?code_method=SMS&language=en

POST 200 in 640 ms

Request

2 headers
POST /v26.0/106540352242922/request_code?code_method=SMS&language=en HTTP/1.1
Host: graph.facebook.com
Authorization: Bearer {ACCESS_TOKEN}

Response

200 OK
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true
}
Try another response
Press Send to request an SMS code for a business number. Toggle the alternatives to see the 136024 response for an already verified number, and error 100 for an invalid code_method. Error bodies are abridged and illustrative.

Response: 200 OK after 640 ms.

03What is phone number verification?

Phone number verification is how a business proves to Meta that it controls a phone number before using it on the WhatsApp Business Platform. Meta sends a one-time code to the number by SMS or voice call, and the business submits that code back. Through the Cloud API, this takes two calls on the number's phone number ID. First, POST /{PHONE_NUMBER_ID}/request_code with code_method (SMS or VOICE) and language. Then POST /{PHONE_NUMBER_ID}/verify_code with the code received.

Verification is about ownership, not activation. A verified number still cannot message until phone number registration switches it on. That is the separate /register call, made with a six-digit two-step PIN. The number's code_verification_status field shows where it stands. Meta asks you to check it first, because calling request_code for a number that is already verified returns HTTP 400 with error 136024.

Most businesses meet verification inside Embedded Signup or WhatsApp Manager, where the same code step is a form. The API calls matter when you onboard numbers programmatically, for example a provider adding many outlets' numbers, or a landline that can only take a voice call. The number must be able to receive an SMS or a voice call and must have a country and area code; short codes are not supported. A number already in use on WhatsApp cannot be added unless that account is deleted first.

Key takeaways

  • Phone number verification proves you control a business number: Meta sends it a one-time code and you return that code.
  • POST /{PHONE_NUMBER_ID}/request_code sends the code by SMS or VOICE, and POST /{PHONE_NUMBER_ID}/verify_code submits it.
  • Check code_verification_status first. Requesting a code for an already verified number returns HTTP 400 with error 136024.
  • The number must be able to receive an SMS or a voice call and have a country and area code. Short codes are not supported.
  • Verification proves ownership. Registration then activates the number with a six-digit PIN.

04Example: A landline support number in Bengaluru

A Bengaluru insurer wants its existing landline support number (080-…) on WhatsApp. The line cannot receive SMS, so the developer calls request_code with code_method=VOICE. The IVR answers first, so the telecom team forwards the line to a desk phone for ten minutes. An agent hears the code, the developer submits it with verify_code, and the status changes to VERIFIED. Registration follows the same afternoon, and the forwarding is removed.

05 · Mistakes to avoid

Common mistakes with phone number verification

  • Requesting an SMS for a line that cannot receive one

    Landlines and many IVR numbers never get the SMS. Use code_method=VOICE, and make sure a person can answer the call.

  • Requesting codes again and again

    Several requests in a row make it unclear which code is current, and repeated requests can be throttled. Request once, wait a few minutes, then submit the latest code you received.

  • Skipping the status check

    Calling request_code for a verified number returns error 136024 and confuses onboarding scripts. Read code_verification_status first.

  • Number still active on a WhatsApp app

    A number in use on the WhatsApp or WhatsApp Business app cannot be added until that account is deleted, unless you onboard it through coexistence where that is supported. Plan the switch before verification.

  • Confusing it with business verification

    Phone number verification proves you control one line. Business verification proves your company is real and is one way to unlock higher messaging limits. They are separate processes.

06 · In code

Phone number verification in code

curl -X POST "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/request_code?code_method=VOICE&language=en" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
# → {"success": true}

Use SMS for mobile numbers and VOICE for landlines or numbers behind an IVR.

07 · Key facts

Phone number verification: key facts and limits

Request endpoint
POST /{PHONE_NUMBER_ID}/request_code
Parameters
code_method = SMS or VOICE; language = two-letter code such as en
Verify endpoint
POST /{PHONE_NUMBER_ID}/verify_code (code)
Success response
{"success": true}
Already verified
HTTP 400, error 136024
Eligible numbers
Can receive SMS or voice; country and area code; no short codes
Token
System user token with whatsapp_business_management

08 · Why it matters

Why does phone number verification matter?

Onboarding stalls at verification more often than anywhere else. The code never arrives because the line is an IVR, or the SMS is filtered. The number is still active on a WhatsApp app. Someone requests codes again and again until nobody knows which one is current. If you know the two calls, the voice option for landlines and the status field to check first, these become five-minute fixes rather than support tickets.

09 · Pro tips

Best practices for phone number verification

  • Schedule verification for a time when someone can physically answer the line.
  • For IVR numbers, forward the line temporarily or add a menu option that reaches a person.
  • Log request_code calls with timestamps, so support can tell which code is current.
  • Keep verification and registration as separate, retryable steps in onboarding scripts.

10Phone Number Verification FAQs

Why am I not receiving the WhatsApp verification code?+
Usually the line cannot receive SMS, the message is filtered, or an IVR answers the voice call. Switch to `code_method=VOICE`, make sure a person can answer, and request again after a short wait.
Can I verify a landline number for the WhatsApp Business API?+
Yes, if it can receive a voice call and has a country and area code. Request the code with the VOICE method and have someone answer the call to hear it.
What does WhatsApp error 136024 mean?+
It means the number is already verified, so no code is needed. Check `code_verification_status` before calling request_code, and move on to registration.
Is phone number verification the same as Meta business verification?+
No. Phone number verification proves control of one number with a code. Business verification checks your company's documents, and is one way to unlock higher messaging limits.

See InfiQ pricing

From definition to your first message

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms