How to register a phone number on WhatsApp Cloud API: two-step PIN and common errors

Updated on October 28, 2026

To register a phone number on WhatsApp Cloud API, send POST /{phone-number-id}/register with messaging_product: "whatsapp" and a 6-digit pin. If the number does not have two-step verification yet, that PIN becomes its PIN; if it already has one, you must send the current PIN or you get error 133005. Without this registration, the number exists in your account but cannot send or receive messages through the API.

This guide covers the right order (verify, register, check), what the PIN does, attempt limits, deregister, and a table of registration errors from Meta’s documentation.

Where registration fits

Getting a number onto Cloud API involves three steps that often get mixed up:

Step	What it proves	Call
Add the number	That it belongs to your WhatsApp Business account	Done in WhatsApp Manager or Embedded Signup
Verify the number	That you have access to the phone (code by SMS or voice call)	POST /{id}/request_code and POST /{id}/verify_code
Register the number	That it should run on Cloud API, with a two-step PIN	POST /{id}/register

If you onboard through a provider’s Embedded Signup, part of these steps happens on the signup screen itself; it still helps to know what each one does to make sense of the errors below. Before you start, check the number requirements in how to use an existing WhatsApp number with the Business API.

Step 1: verify the number (if it is not yet)

Per Meta’s phone numbers page, first check the verification status:

curl "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID?fields=code_verification_status,display_phone_number,verified_name" \
  -H "Authorization: Bearer $TOKEN"

If code_verification_status is not VERIFIED, request a code. code_method accepts SMS or VOICE:

curl -X POST "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/request_code" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "code_method": "SMS", "language": "en_US" }'

Then confirm with the code you received:

curl -X POST "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/verify_code" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

If the number is already verified, request_code returns HTTP 400 with error 136024, so check the status first.

Want to try it while you read? Create a Vectalk account and send your first message through the official API. Create free account →

Step 2: register with the PIN

The registration call, per Meta’s registration documentation:

curl -X POST "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/register" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "pin": "482915"
  }'

Parameters:

• messaging_product (required): always "whatsapp".
• pin (required): 6 digits. If two-step verification is already on, use the existing PIN. If not, the value you send becomes the number’s PIN.
• data_localization_region (optional): 2-letter ISO 3166 country code to enable local data storage. You cannot disable or change it directly later: you have to deregister and register again.

The token needs the whatsapp_business_management and whatsapp_business_messaging permissions. For production, use a permanent system user access token.

What the two-step PIN is

The two-step verification PIN is an extra security layer: once set, every new registration of the number requires the current PIN. It is not the same as the 6-digit code sent by SMS. The SMS code proves you hold the SIM; the PIN proves you own the registration.

Per the two-step verification page, you can also set the PIN with POST /{phone-number-id} and the body {"pin": "123456"}. There is no endpoint to disable two-step verification. To change the PIN in WhatsApp Manager, open the number’s settings, go to the Two-step verification tab and click Change PIN.

Keep the PIN in your company’s password vault, not in the head of whoever did the setup. You will need it again for any new registration, including when switching providers. More in WhatsApp Business account security.

A change in progress: Meta says it is gradually deprecating the 6-digit PIN for eligible Cloud API numbers. For eligible numbers, the two-step verification tab disappears from WhatsApp Manager; if you still see it, the number is not eligible yet. Check the official page before automating this step.

Step 3: check the status

After registering, query the number:

curl "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID?fields=status,code_verification_status,name_status,quality_rating" \
  -H "Authorization: Bearer $TOKEN"

What to look for:

• status: must be CONNECTED to send and receive through the API.
• code_verification_status: VERIFIED.
• name_status: display name state (APPROVED, AVAILABLE_WITHOUT_REVIEW, DECLINED, EXPIRED, PENDING_REVIEW or NONE).
• quality_rating: the number’s quality.

Attempt limits

Registration and deregistration are rate limited: 10 requests of each per number in a moving 72-hour window. Beyond that, the API returns 133016 and blocks the action for the next 72 hours. So do not put register inside an automatic retry loop. If it fails, read the error, fix the cause, and only then try again.

Registration errors and how to fix them

The codes below come from the Cloud API error code table, except 136024, which comes from the phone numbers page:

Code	Meaning	What to do
133000	A previous deregistration attempt failed	Deregister again before registering
133004	Server temporarily unavailable	Check the platform status page and the details field before retrying
133005	Two-step verification PIN incorrect	Use the current PIN, or change it in WhatsApp Manager and register with the new one
133006	Number must be verified before registering	Run request_code and verify_code
133008	Too many PIN guesses for this number	Wait for the time given in details
133009	PIN entered too quickly	Check details before retrying
133010	Number not registered on the platform	Register the number before sending messages
133015	Number was recently deleted and deletion has not finished	Wait 5 minutes and retry
133016	Too many registration or deregistration attempts in a short time	Wait for the 72-hour block to end
136024	Number already verified (on request_code)	Skip to registration

The cases you will see most often:

133010 when sending a message. The number was added and even verified, but register was never called. Common with manually connected numbers and test setups. The fix is to register.

133005 when switching providers. The number comes from another platform with two-step verification on, and nobody knows the PIN. Ask the previous provider for the PIN, or change it in WhatsApp Manager if you have access to the account, and register with the new value. See how to switch WhatsApp API providers without losing your number.

131031 during registration. This code usually means the account was restricted for a policy violation, but Meta also lists request data that does not match the account, such as an incorrect two-step PIN, as a cause. If the account has no restriction, check the PIN.

When to register again

Per the registration documentation, registration is not a one-time event:

• When you first implement the API, where Meta enforces two-step verification.
• After a display name change: once the new name is approved (the phone_number_name_update webhook confirms it), register the number again. Registering before approval has no effect.
• To change or disable local storage (data_localization_region): deregister and register again.
• When migrating from On-Premises to Cloud API, which has extra steps before registration.

Deregistering

curl -X POST "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/deregister" \
  -H "Authorization: Bearer $TOKEN"

What happens, per Meta: the number stops working on Cloud API and local storage is disabled if it was on. The number and its message history are not deleted. Two key restrictions: you cannot deregister a number used on both Cloud API and the WhatsApp Business app (coexistence), and without the whatsapp_business_management permission the call returns error 200. Keep in mind that deregistration has its own limit of 10 requests per number in 72 hours.

How to do this with Vectalk

With Vectalk, phone number routes use the instance token, which already identifies the number, so you do not pass a phone-number-id. The Vectalk API provides POST https://apis.vectalk.com.br/api/phone-numbers/register with the pin in the body, POST /phone-numbers/deregister, POST /phone-numbers/request-code, POST /phone-numbers/verify-code and GET /phone-numbers to check status, quality and throughput level. Vectalk also supports coexistence, so the number can stay on the WhatsApp Business app while using the API. Sign up at apps.vectalk.com.br/register.

With the number registered, the next steps are to validate the webhook signature and stay within throughput and rate limits. The full picture of the platform is in our WhatsApp Cloud API guide.

Frequently asked questions

Is the two-step PIN the same as the SMS code?

No. The SMS or voice code verifies that you have access to the phone. The 6-digit PIN is set by you and is required for every new registration of the number.

I forgot the PIN. How do I register the number?

Change the PIN in WhatsApp Manager, under the number’s two-step verification tab, and register with the new value. There is no endpoint to disable two-step verification.

How many times can I try to register?

Up to 10 registrations and 10 deregistrations per number in 72 hours. Beyond that, the API returns 133016 and blocks the action for 72 hours.

Does deregistering delete the number or the messages?

No. The number just stops working on Cloud API. The number and its history remain, and you can register again later.

Do I need to register again after changing the display name?

Yes. Once the new name is approved, call register again. Registering before approval has no effect.

---

Official sources consulted on October 28, 2026: Register a phone number (Meta), Two-step verification (Meta), Phone numbers (Meta), Error codes (Meta), Register number in the Vectalk API.