WhatsApp Business Platform > On-Premises API > Reference

Account

/v1/account

We are sunsetting On-Premises API. This endpoint can no longer be used to register business phone numbers and now returns the following error:

{
  "code": 1005,
  "title": "Access denied",
  "details": "Unknown error: biz_link_on_prem_reg_blocked"
}

The account node is for registering your WhatsApp Business API client.

Please be aware that Coreapp will restart if a new number is registered on a cluster that has another number registered already.

Edges

The following edges are connected to this node:

Edge	Description
`/verify`	Once you have received the registration code via your specified method, use this edge to complete your account registration.

Before You Start

You will need:

Authentication Tokens to be able to login to the service
A valid phone number associated with your WhatsApp Business Account
A WhatsApp approved display name associated with that phone number

Copy the Base64-encoded Certificate

A base64-encoded certificate string is generated for you and is used for validation during WhatsApp Business API client registration.

Go to the Business Settings in your Meta Business Manager.
Click on WhatsApp Accounts under the Accounts menu, then select your WhatsApp Account from the WhatsApp Accounts list, if it isn't already highlighted.
Go to the Settings tab, and click the WhatsApp Manager button.
Under the Phone Numbers tab, you should see your phone numbers listed. Click the View button of the phone number you want the certificate for.
Get the Certificate
A pop-up dialog will display the certificate string in a gray box. Click Get Certificate.
Download the Certificate String
Use this certificate string in the cert parameter when registering with the account endpoint.

See the Display Name documentation for more information.

Constraints

You must use the admin account to register the application.
If you are re-registering your account, the Coreapp needs to be restarted once registration is complete.

Requesting

Make a POST call to this endpoint to request a registration code. In your call, add your phone number and base64-encoded certificate string. You can receive your code via either SMS or voice call.

Example

POST /v1/account

{
    "cc": "COUNTRY_CODE",
    "phone_number": "PHONE_NUMBER_WITHOUT_COUNTRY_CODE",
    "method": "sms" or "voice",
    "cert": "VERIFIED_NAME_CERT_IN_BASE64",
    "pin": "EXISTING_6_DIGIT_PIN" # required if two-step verification is enabled
}

Depending on the response received, the registration procedure can be considered complete or require another step to complete. If successful, you receive one of the following HTTP status codes. Follow the instructions that match the response you received:

201 Created — The account already exists. You are already registered, so you do not need to do anything else.
202 Accepted — The account does not exist. Depending on the method selected in the request, check your SMS or voice number for the registration code. This response will include a returned payload that contains the vname decoded from the cert parameter for you to confirm the right display name is being set. If correct, proceed to Completing Your Account Registration to complete registration.

{
  "account": [{
      "vname": "decoded-vname-from-cert"
  }]
}

If any errors are returned, refer to Error and Status Messages for more information.

Parameters

Name	Description
`cc`	Required. Numerical country code for the phone number you are registering
`phone_number`	Required. Phone number you are registering, without the country code or plus symbol (`+`).
`method`	Required. Method of receiving your registration code Options: `voice`, `sms`
`cert`	Required. Base64-encoded certificate.
`pin`	Optional. Existing 6-digit PIN — This is only required when two-step verification is enabled on this account.

Changing Your Two-Step Verification PIN

To change your business phone number's two-step verification PIN:

Load the WhatsApp Business Account (WABA) associated with the phone number in WhatsApp Manager. See WhatsApp Manager if you have multiple portfolios and WABAs.
Mousever the menu on the left and navigate to Account tools > Phone numbers.
Use the dropdown menu on the top-right to select the WABA associated with the phone number, if necessary.
Click the phone number's settings (gear) icon.
Click Two-step verification.
Click Change PIN and complete the flow.

You must supply your current PIN in order to change it. Note that you can also set a new PIN using our APIs:

Disabling Two-Step Verification

To disable two-step verification, follow the steps for changing your PIN, but click the Turn off two-step verification button as the final step instead. An email with a link will be sent to the email address associated with your business portfolio. Use the link to disable two-step verification. Once disabled, you can re-enable it by setting a new PIN.

FAQ

Can I change the phone number or verified name at a later time?

Yes, we can set up a new phone number or change the verified name when you are ready to go live.

Permalink

Can we use toll-free numbers as our business account number?

Toll-free numbers are allowed as long as your country code is included. The reason is that toll-free numbers without country codes cannot be uniquely identified — the same number can apply for two different countries.

Also note that there are added complexities around toll-free numbers. Typically, if you call a toll-free number with the country code when you're inside the country, it will fail. This means that there is a chance your customers from your country will try to dial what shows in the business contact (country code included) and they won't be able to reach you. If this is a concern, you will need to let them know explicitly.