Skip to content

Playbook · 5 steps

Phone Number Registration

Also called: Register endpoint · /register API · Cloud API number registration

5steps

Level
Practitioner
Reading time
About 5 min

Reviewed

Definition
The POST /{phone-number-id}/register call that activates a verified business number on the WhatsApp Cloud API and sets its six-digit two-step PIN.

01 · How it works, in 5 steps

How does phone number registration work?

  1. 1

    Add and verify the number

    Add the number to the WABA and prove ownership with an SMS or voice code: request_code then verify_code, or the same step inside Embedded Signup. Registering an unverified number fails with error 133006.

  2. 2

    Settle the PIN

    If two-step verification is already on, find the existing six-digit PIN. If it is not, choose a new PIN and store it in your secrets manager, because you will need it again to re-register.

  3. 3

    Decide on data localisation

    Add data_localization_region only if you need local storage in a supported country. Leaving it out is the default, and keeps standard Cloud API storage.

  4. 4

    Call /register

    POST the body to /{PHONE_NUMBER_ID}/register with a token that has whatsapp_business_management. A successful call returns {"success": true}.

  5. 5

    Confirm, then send

    Read GET /{PHONE_NUMBER_ID}?fields=status until it reports CONNECTED, then send a test template to a number you control.

02Try it

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

Trace a number from added to CONNECTED

3 / 3
Number in WABAnot yet live
VerifiedSMS or voice code
POST /registerpin + region?
CONNECTEDready to send
133006not verified
133005wrong PIN
13301610 tries / 72 h
POST /deregisterto change region
  • Number in WABA to Verified: code
  • Verified to POST /register: API call
  • POST /register to CONNECTED: success
  • Number in WABA to 133006: too early
  • POST /register to 133005: PIN mismatch
  • 133005 to 133016: keep retrying
  • CONNECTED to POST /deregister: new region
  • POST /deregister to POST /register: re-register

Hop 3 of 3

POST /registerCONNECTEDsuccess

Arrives at CONNECTED — ready to send.

The happy path runs along the top: verify, register, connected. The lower boxes show the errors a register call can return, and the deregister loop you need to change the data-localisation region.

Hop 3 of 3: POST /register to CONNECTED — success.

03What is phone number registration?

Phone number registration is the step that activates a business phone number on the WhatsApp Cloud API. It is a single call, POST /{PHONE_NUMBER_ID}/register, with a body containing messaging_product: "whatsapp" and a six-digit pin. Until it succeeds, the number exists in the WhatsApp Business Account (WABA) but cannot send or receive messages through the API. Once it succeeds, the number's status reads CONNECTED and it can message.

Registration comes after phone number verification. Verification proves control of the number with a one-time code sent by SMS or voice call, and registration then switches the verified number on. Meta's docs say registration can only be done through the API, not in WhatsApp Manager or the App Dashboard. Embedded Signup and most providers make the call for you during onboarding.

The pin doubles as two-step verification. If the number already has two-step verification enabled, you must send its existing PIN. If not, the PIN you send becomes the number's new two-step PIN. The optional data_localization_region, a two-letter ISO 3166 country code such as IN, turns on Cloud API local storage so that message data at rest stays in that country. It cannot be changed in place: you have to deregister and register again.

Key takeaways

  • Registration is the POST /{PHONE_NUMBER_ID}/register call that switches a verified number on for the Cloud API.
  • It needs messaging_product: whatsapp and a six-digit pin: the existing two-step PIN, or a new one that becomes it.
  • Registration and deregistration are limited to 10 requests per number in a moving 72-hour window (error 133016).
  • The optional data_localization_region turns on local storage. Changing it later means deregistering and registering again.
  • Verification proves you own the number and registration activates it. An unverified number fails with error 133006.

04 · In code

Phone number registration in code

curl -X POST "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/register" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "pin": "{SIX_DIGIT_PIN}"
  }'
# → {"success": true}

05 · Mistakes to avoid

Common mistakes with phone number registration

  • Guessing a forgotten PIN

    Every attempt counts toward the 10 allowed in 72 hours, and repeated wrong PINs trigger error 133008. Reset two-step verification in WhatsApp Manager, then register once with the new PIN.

  • Registering before verifying

    An unverified number fails with 133006. Check code_verification_status first, and complete request_code and verify_code if needed.

  • Setting a region by accident

    data_localization_region cannot be changed in place. Switching it later means deregistering, which takes the number offline, and then registering again, which uses up attempts.

  • Scripts that re-register on every deploy

    Registration is a one-time activation, not a health check. Automation that calls /register at every start-up soon hits the 72-hour lockout. Check status instead.

06 · Key facts

Phone number registration: key facts and limits

Endpoint
POST /{PHONE_NUMBER_ID}/register
Required body
messaging_product = whatsapp, pin (6 digits)
Optional
data_localization_region (ISO 3166 alpha-2, e.g. IN)
Attempt limit
10 register or deregister requests per number per moving 72 h
Lockout error
133016: wait out the 72-hour window
Other errors
133005 wrong PIN · 133006 not verified · 133008 too many PIN guesses
Undo
POST /{PHONE_NUMBER_ID}/deregister (same limit)

07Example: Going live for a Lucknow clinic chain

A clinic chain in Lucknow onboards a new appointment number. The developer verifies it with an SMS code, then calls /register with a new PIN and no region. The call fails with error 133005, because a colleague had already enabled two-step verification with a different PIN. Guessing would be costly: each attempt counts toward the 10 register requests allowed in 72 hours, and repeated wrong PINs trigger their own lockout (133008). Instead, the team resets the PIN in WhatsApp Manager and registers once with the new value. They confirm the status reads CONNECTED before sending the first appointment reminder.

08 · Why it matters

Why does phone number registration matter?

Registration is the moment a number goes live, and it is easy to get stuck there. A forgotten two-step PIN blocks it. Repeated failed attempts lock the number out for 72 hours. Choosing a data-localisation region by accident cannot be undone without taking the number offline. For regulated Indian businesses deciding where message data rests, the region parameter is also a compliance decision, not just a technical flag.

09 · Pro tips

Best practices for phone number registration

  • Store the two-step PIN in a secrets manager, next to the phone number ID it belongs to.
  • Check GET /{PHONE_NUMBER_ID}?fields=status,code_verification_status before calling /register.
  • Decide on data localisation with your compliance team before go-live, not after.
  • Log every register and deregister call, so you know how many attempts remain in the 72-hour window.

10Phone Number Registration FAQs

What is the difference between verifying and registering a WhatsApp number?+
Verification proves you control the number, using an SMS or voice code. Registration then activates it for the Cloud API with a six-digit PIN. Verification always comes first, and an unverified number cannot be registered.
Which PIN do I use when registering?+
Use the number's existing two-step verification PIN if one is set. If none is set, the six-digit PIN you send in the register call becomes the number's new two-step PIN.
What does WhatsApp error 133016 mean?+
It means there were too many register or deregister attempts for that number. The limit is 10 requests in a moving 72-hour window, so wait until the number is unblocked, then try once.
Can I register a phone number in WhatsApp Manager instead of the API?+
No. Meta's docs say registration is API-only. Embedded Signup and providers make the API call for you, so many businesses never see it directly.
Do I need data_localization_region for India?+
No, it is optional. Add it only if you need Cloud API local storage in a supported country such as India. It cannot be changed later without deregistering the number.

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