Use the contacts node to manage WhatsApp users in your database by validating them before sending messages and verify a user's identity with identity hashes.

With the contacts node you can:

  • Verify that a phone number in your database belongs to a valid WhatsApp account. You must ensure that the status is valid before you can message a user.
  • Get the WhatsApp ID for a phone number. WhatsApp IDs are needed to send messages and user notifications.

Before You Start

You must present an option to your customers to opt-in to WhatsApp communications with your business. This opt-in flow is maintained by your business. After a customer opts-in, use the contacts node to validate the registered number. See Understanding How to Get Opt-in for WhatsApp for more information.


  • Use this endpoint to verify that a phone number within a business' database belongs to a valid WhatsApp account
  • The number of calls must not exceed the number of messages the phone number is sending


If a business is misusing the endpoint, the following actions will be taken:

  • All admins listed in the Business Manager will receive an initial warning via email if misuse is suspected
  • A business will have seven days after receiving the warning to adjust their behavior
  • If after seven days calls have not been adjusted, the phone number will be permanently disabled


We recommend checking contacts before sending messages, however you do not need to check contacts when responding to incoming customer messages as you can immediately respond using the provided wa_id. There is no additional cost as results are cached.


Before sending messages to users who have opted in, send a POST request to /v1/contacts endpoint to create a WhatsApp account user validation request. In your call, include a list of phone numbers you want to validate.


POST /v1/contacts
  "blocking": "wait" | "no_wait",
  "contacts": [
  	"+1 631 555 1001",
  	"+1 (631) 555-1004",
  "force_check": false | true

You will receive a response with the current status of the requested numbers and their WhatsApp IDs (wa_id):

  "contacts": [ {
    "wa_id": "16315551000",
    "input": "16315551000",
    "status": "valid"
    "wa_id": "16315551001",
    "input": "+1 631 555 1001",
    "status": "processing" # Only applicable when request is non-blocking
    "input": "6315551002",
    "status": "invalid"
    "input": "+163155588",
    "status": "failed"

Save the WhatsApp IDs for those numbers that returned a status of valid. Valid users are those with a WhatsApp account. Use the WhatsApp IDs to send messages and notifications.

Repeat these steps on a regular basis to manage your list of valid users. The results are cached in the WhatsApp Business On-Premises API client's database for 7 days.


The following parameters are supported for POST calls to /v1/contacts:

Name Description



Whether the request should wait for processing to complete or not before returning a response. For more information, read the Blocking section below.

Possible values: no_wait (default), wait



Array of phone numbers that you are validating.

The numbers can be in any standard telephone number format. The recommended format for contact phone numbers is with a plus sign (+) and the country code. For more information, see the Phone Number Formats section below.



Whether to check the contacts cache or not. Contact information is normally cached for 7 days. By setting the force_check parameter to true, the cache will be bypassed ensuring a check is performed.

Possible values: false (default), true


The following edges are connected to this node:



Use this edge to manage users' identities. See Understanding Identity Change for WhatsApp Business for more information.


There are two options for the blocking parameter: no_wait and wait. If the blocking parameter is not specified in a call it is no_wait by default.

The blocking parameter determines whether the request should wait for the processing to complete (synchronous) or not (asynchronous).



The processing of the phone numbers is asynchronous.

The response may include some numbers with status set to processing. If that happens, we recommend you follow these steps:

  1. You get a response with some numbers marked as processing.
  2. Issue another check contact request including the numbers with the processing status.
  3. If the processing is done in your new request, you get a correct status for that number (valid or invalid).
  4. If you still see numbers marked as processing, repeat step 2 until you have an answer for each number.


The processing of the numbers is synchronous. You see the final status for all of the contacts after syncing with server. This setting makes the query block wait until the numbers have all been checked before returning results. This might take some time.

Phone Number Formats

The phone numbers in the contacts request can be in any dialable format.

When there is no plus sign (+) at the beginning of the phone number, the country code is determined using the phone number that your WhatsApp Business On-Premises API client is registered under, so phone numbers associated with a different country code will fail.

The recommended best practice is to always specify the country code with the phone number and explicitly prefix it with a plus sign (+).

Here are some examples that demonstrate this behavior, assuming the WhatsApp Business On-Premises API client is registered with an Indian phone number (i.e., country code is +91):

Phone NumberTranslated Phone NumberValid?










"+1 (516) 283-7151"



"+54 9 11 5612-1008"



Returned Fields

The contacts response payload contains the same array of phone numbers sent in the request with the input, status, and wa_id properties:

Name Description


The value you sent in the contacts field of the request.


Status of the user.

Possible values:

  • processing — Input is still being processed
  • valid — A valid WhatsApp user
  • invalid — Not a valid WhatsApp user
  • failed — There was an error processing this check


WhatsApp user ID that can be used in other calls. Only returned if the status is valid

Along with the processing status, you should see an HTTP status of 200 OK. If there are any errors in the response, see Error and Status Messages for more information.