Fetch Phone Number Details API

GET Method

The Fetch Phone Number API allows you to get information about your WhatsApp business phone number, including status, messaging limit, quality rating, and other Information.

This API retrieves the information associated with a phone number, such as:

Messaging limit tier.
Name status.
Quality rating.
Quality score.
Status of phone number.
Throughput level of phone number.
Verified name associated with the phone number.
Can a call be received using the phone number?
Can a message be sent using the phone number?
Entity type associated with phone number.
Error associated with phone number (if any)?
Error description.
Possible solution for the associated error.

Prerequisites

Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
A prerequisite for using Kaleyra WhatsApp APIs is to have an active WhatsApp plan on Kaleyra platform.
To set up a WhatsApp account on Kaleyra platform, see Manual Signup
and Embedded Signup.
An active WhatsApp for Business API plan that includes:
- A WhatsApp business number.
- An associated profile with the business number.
- A WhatsApp verified and approved profile.
- A WABA ID onboarded on Kaleyra WhatsApp API.

Base URL

https://<api_domain>/v2/<SID>

📘
Note:
If you are using WhatsApp V1 version, use https://<api_domain>/v1/<SID> endpoint.

API Domain and Value

api_domain	Value
IN pod	api.in.kaleyra.io
SG Pod	api.ap.kaleyra.io
EU Pod	api.eu.kaleyra.io
NA pod	api.na.kaleyra.io

API request to fetch phone numbers details

To fetch phone numbers details, use:
https://<api_domain>/v2/<sid>/whatsapp/<business_phone_number>/phone_number_details
endpoint with the following request method.

Request Format

The following is the request format to fetch the phone number details:

curl --location --request GET 'https://<api_domain>/v2/<sid>/whatsapp/<business_phone_number>/phone_number_details' \
-header 'api-key: <api-key>' \
-header 'Content-Type: <content-type>'

Sample Request Format

The following is the sample request format to fetch the phone number details:

curl --location --request GET 'https://api.in.kaleyra.io/v2/HXAP16XXXXXX97IN/whatsapp/914XXXXXX139/phone_number_details' \
-header 'api-key: AXXXXXXXXXXXXXXXXXXXXX3' \
-header 'Content-Type: application/json'

URL Parameters and Headers

The following is the list of parameters and headers to send the outgoing message request:

Parameter / Headers	Data Type	Description	Example	Mandatory?
`sid`	String	Account SID (Security Identifier).	HXAP16XXXXXX97IN	Yes
`business_phone_number`	String	Phone number for which you want to fetch the details.	914XXXXXX139	Yes
`api-key`	String	API key generated from kaleyra.io account.	AXXXXXXXXXXXXXXXXXXXXX3	Yes
`Content-Type`	String	Indicates the format of the content the API will be processing.	The only allowed value is application/json.	Yes

Sample Success Response

The following success message appears with the status 200 Accepted for WhatsApp Business phone number associated with a WABA ID belonging to Kaleyra WA API v2:

{
    "display_phone_number": "+91 4X XXXX X139",
    "health_status": {
        "can_send_message": "LIMITED",
        "entities": [
            {
                "additional_info": [
                    "Your display name has not been approved yet. Your message limit will increase after the display name is approved."
                ],
                "can_receive_call_sip": "BLOCKED",
                "can_send_message": "LIMITED",
                "entity_type": "PHONE_NUMBER",
                "errors": [
                    {
                        "error_code": 138024,
                        "error_description": "WhatsApp Business calling cannot use SIP because it is not enabled",
                        "possible_solution": "Configure SIP using {PHONE_NUMBER_ID}/settings API"
                    }
                ],
                "id": "489XXXXXXXX9632"
            },
            {
                "can_send_message": "AVAILABLE",
                "entity_type": "WABA",
                "id": "535XXXXXXXX5436"
            },
            {
                "can_send_message": "AVAILABLE",
                "entity_type": "BUSINESS",
                "id": "109XXXXXXXX55566"
            },
            {
                "can_receive_call_sip": "BLOCKED",
                "can_send_message": "AVAILABLE",
                "entity_type": "APP",
                "errors": [
                    {
                        "error_code": 138025,
                        "error_description": "This app cannot use SIP for WhatsApp Business calling because it has not configured a SIP server for this business phone number",
                        "possible_solution": "Configure SIP server using {PHONE_NUMBER_ID}/settings API"
                    }
                ],
                "id": "115XXXXXXXX82110"
            }
        ]
    },
    "id": "489XXXXXXXX9632",
    "messaging_limit_tier": "TIER_1K",
    "name_status": "DECLINED",
    "quality_rating": "GREEN",
    "quality_score": {
        "score": "GREEN"
    },
    "status": "CONNECTED",
    "throughput": {
        "level": "STANDARD"
    },
    "verified_name": "MKLRV2"
}

The following success message appears with the status 200 Accepted for WhatsApp Business Phone Number associated to a WABA ID belonging to Kaleyra WA API v1:

{
    "display_phone_number": "+91 80 XXXX XX79",
    "health_status": {
        "can_send_message": "AVAILABLE",
        "entities": [
            {
                "can_receive_call_sip": "AVAILABLE",
                "can_send_message": "AVAILABLE",
                "entity_type": "PHONE_NUMBER",
                "id": "104XXXXXXXX2733"
            },
            {
                "can_send_message": "AVAILABLE",
                "entity_type": "WABA",
                "id": "140XXXXXXXX2074"
            },
            {
                "can_send_message": "AVAILABLE",
                "entity_type": "BUSINESS",
                "id": "109XXXXXXXX55566"
            },
            {
                "can_receive_call_sip": "BLOCKED",
                "can_send_message": "AVAILABLE",
                "entity_type": "APP",
                "errors": [
                    {
                        "error_code": 138025,
                        "error_description": "This app cannot use SIP for WhatsApp Business calling because it has not configured a SIP server for this business phone number",
                        "possible_solution": "Configure SIP server using {PHONE_NUMBER_ID}/settings API"
                    }
                ],
                "id": "115XXXXXXXX82110"
            }
        ]
    },
    "id": "104XXXXXXXX2733",
    "messaging_limit_tier": "TIER_1K",
    "name_status": "APPROVED",
    "quality_rating": "GREEN",
    "quality_score": {
        "score": "GREEN"
    },
    "status": "CONNECTED",
    "throughput": {
        "level": "STANDARD"
    },
    "verified_name": "Kaleyracloud2"
}

For more information on Meta's policy and meaning of parameter used in the response, see WhatsApp Business Account Phone Number API.

Sample Failure Response

The following are the failure responses for V2 and V1 numbers:

401 Unauthorized
{
    "code": "RBC201",
    "message": "Incorrect SID or API key.",
    "data": [],
    "error": {
        "body": "Incorrect SID or API key.",
        "error": "API Key Not Found"
    }
}

401 Unauthorized phone number
{
    "code": "WA401",
    "message": "Phone number is not present or does not belong to the account.",
    "data": {},
    "error": {
        "phone_number": "Phone number is not present or does not belong to the account."
    }
}

Updated about 2 hours ago