Check if a phone number is on WhatsApp

Using this endpoint you can check if a given number is registered on WhatsApp or not. This can be useful to know if you can use WhatsApp to send messages to a contact number.

info

Check out our GitHub repository with an example script using this API.

tip

👉 You can see this API live in 2Chat's free number checker, and try it yourself.

Parameters

These are query-string parameters that should go on the URL you use to invoke the endpoint.

Considering https://api.p.2chat.io/open/whatsapp/check-number/<your-number>/<number-to-check>:

<your-number> must be replaced with your actual WhatsApp number that you connected to 2Chat, and...
<number-to-check> with the number you want to check to verify if it has a WhatsApp account.

Example: https://api.p.2chat.io/open/whatsapp/check-number/+595981048477/+17137157533.

tip

Check this tutorial to connect your number to 2Chat.

Invocation

cURL
Python
NodeJS
PHP

curl --location --request GET 'https://api.p.2chat.io/open/whatsapp/check-number/+595981048477/+17137157533' \
--header 'X-User-API-Key: your_api_key_here'

import requests

url = "https://api.p.2chat.io/open/whatsapp/check-number/+595981048477/+17137157533"

payload={}
headers = {
  'X-User-API-Key': 'your_api_key_here'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

var axios = require('axios');

var config = {
  method: 'get',
  url: 'https://api.p.2chat.io/open/whatsapp/check-number/+595981048477/+17137157533',
  headers: { 
    'X-User-API-Key': 'your_api_key_here'
  }
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.p.2chat.io/open/whatsapp/check-number/+595981048477/+17137157533',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'X-User-API-Key: your_api_key_here'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

tip

Paid accounts can run up to 50 requests per minute per connected number.

For example: if you connect 1 number to 2Chat you can go as fast as 50 requests per minute, but with 2 numbers this limit jumps to 100 per minute, and so on with more numbers you connect.

caution

Trial accounts are rate-limited to 10 requests per minute and to up to 100 checks. To make requests at this speed, you must add a 6-second wait time between each request.

If you would like a faster throughput, please upgrade your account.

Billing

Making 1 request to this endpoint will be billed as 1 API call. If you include the query parameter extra-information=true, which can give you more detailed information about the number (see the whatsapp_info field below), the request will be billed as 2 API calls.

Example: https://api.p.2chat.io/open/whatsapp/check-number/+595981048477/+17137157533?extra-information=true

Response

If the phone number provided has a valid format, you will receive the output below. However, if the provided number is invalid in format or syntax, the field is_valid will return false without any further information.

info

You will need to connect a WhatsApp Business number to be able to pull status_text and the values inside business_information. You just need a free WhatsApp Business number. WhatsApp Business API is not required.

tip

Use the phone number returned by number_id as the target number when sending a message.

For example, WhatsApp may have the number +52 55 1234 5555 registered as +52 1 55 1234 5555 in their database. This can happen when local numbers are subjected to changes in their prefixes due to local regulations, while WhatsApp keeps using the old format that is oftentimes no longer valid.

When you check a number and you notice that the number you check is not the same as the number returned in the number_id field, always use the number_id value when sending messages to that number since this is how WhatsApp has this user registered in their network.

{
    "is_valid": true,
    "number": {
        "iso_country_code": "US",
        "region": "Texas",
        "carrier": "",
        "timezone": [
            "America/Chicago"
        ]
    },
    "on_whatsapp": true,
    "whatsapp_info": {
            "number_id": "17137157533",
            "contact_profile_pic": "https://2chat-user-data-dev.s3.amazonaws.com/chks/contacts/18321d356c7faf1e5f57cb03515fd0b71fdcf7e58f07a36dc530dcea47debb6c.jpeg",
            "is_business": true,
            "is_enterprise": false,
            "verified_name": "2Chat",
            "short_name": "2Chat",
            "pushname": "2Chat",
            "verified_level": 0,
            "status_text": "How cool is this?",
            "business_information": {
                "verified_name": "2Chat",
                "short_name": "2Chat",
                "lang_code": "en_US",
                "currency": "USD",
                "verified_level": 0,
                "business_hours": {
                    "config": {
                        "sun": {
                            "mode": "open_24h"
                        },
                        "mon": {
                            "mode": "open_24h"
                        },
                        "tue": {
                            "mode": "open_24h"
                        },
                        "wed": {
                            "mode": "open_24h"
                        },
                        "thu": {
                            "mode": "open_24h"
                        },
                        "fri": {
                            "mode": "open_24h"
                        },
                        "sat": {
                            "mode": "open_24h"
                        }
                    },
                    "timezone": "America/Chicago"
                },
                "map_pin": "https://maps.google.com...",
                "description": "Conversational Commerce automation software",
                "email": "support@2chat.co",
                "cart_enabled": true,
                "website": [
                    "https://2chat.co"
                ],
                "categories": [
                    {
                        "id": "1065597503495311",
                        "localized_display_name": "Software Company"
                    }
                ]
            }
        }
}

Field	Description
`is_valid`	Whether the number is syntactically valid or not
`number.iso_country_code`	Two-letter country code of the number
`number.region`	The approximate region the number belongs to
`number.carrier`	The first carrier (phone provider) that issued this number
`number.timezone`	The timezone this number is likely on based on its region
`on_whatsapp`	`true` when the number is using WhatsApp, `false` otherwise
`whatsapp_info.number_id`	this is the way WhatsApp has this number stored in their network. Use this value to send messages to this number
`whatsapp_info.is_business`	`true` when the number is a Business Account and has its profile public
`whatsapp_info.is_enterprise`	`true` when the number has an Enterprise Account
`whatsapp_info.contact_profile_pic`	URL of the public (not hidden from people who aren't contacts) profile picture if it has any
`whatsapp_info.verified_level`	`0` to `2`. Where `0` is not verified and `2` is verified with the green badge
`whatsapp_info.verified_name`	The business name of a verified account
`whatsapp_info.business_information.lang_code`	Spoken language code based on the country of the number
`whatsapp_info.business_information.currency`	Currency code based on the country of the number
`whatsapp_info.business_information.short_name`	The business short name of the account
`whatsapp_info.business_information.pushname`	Name the user selected when they created their WhatsApp account
`whatsapp_info.business_information.business_hours`	Business hours specified by the account
`whatsapp_info.status_text`	The status text defined by the owner of the number
`whatsapp_info.business_information`	Extra information available only for numbers that have a business account: WhatsApp Business and WhatsApp Business API

Check if a phone number is on WhatsApp

Parameters​

Invocation​

Billing​

Response​

Parameters

Invocation

Billing

Response