Get Phone Number Details

GET Method

The Get Phone Number Details API allows you to fetch details about a WhatsApp Business phone number associated with a given WABA ID from your WA Account to get the details like status, name, if it is enabled for voice call or not and many more.

You can get both the WhatsApp business phone numbers associated with a Kaleyra V1 API WABA and with a Kaleyra V2 API WABA. You can check to which API version your WABA is associated with in the WhatsApp section of your Kaleyra account.

Prerequisites

Know Your Customer (KYC) approval is mandatory. For more information on submission and approval, see Completing the Know Your Customer page.
For prepaid customers, the credit balance should be sufficient to purchase numbers, make and receive calls, and monthly subscription charges. For more information on balance details, see Adding Credits page.
You must have Proof of Business/Business Address and Proof of Identification (Individual/Company-Signatory) depending on the regulations of that particular region or country.
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 verified and approved profile.
- A WABA ID onboarded on Kaleyra WhatsApp API.

Base URL

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

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 Get Phone Number Details

To get the phone number details, use the https://<api_domain>/v2/<sid>/whatsapp/<waba_id>/number endpoint with the following request method:

Request Format

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

curl --location --request GET  'https://<api_domain>/v2/<sid>/whatsapp/<waba_id>/number?name=<name>&status=<status>&phone_number=<phone_number>&voice_status=<voice_status>&limit=<limit>&offset=<offset>' \
-H 'api-key: <api-key>' \
-H 'Content-Type: <content-type>' \

Sample Request Format

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

curl --location --request GET  'https://<api_domain>/v2/<sid>/whatsapp/<waba_id>/number?name=Samuel&status=APPROVED&phone_number=+9197654XXXXX&voice_status=Enabled&limit=10&offset=2' \
-H 'api-key: AXXXXXXXXXXXXXXXXXXXXXXXXX3' \
-H '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
`waba_id`	String	The waba_id associated with the WhatsApp Business Account. For more information, see step 1 to step 3 of Adding a new WABA ID.	766XXXXXXXXXX	Yes
`api-key`	String	API key generated from kaleyra.io account.	AXXXXXXXXXXXXXXXXXXXXXXXXX3	Yes
`Content-Type`	String	Indicates the format of the content the API will be processing.	The only allowed value is application/json.	Yes

The following is the list of attributes to be used in the payload to get phone number details in JSON format:

Parameter	Data Type	Description	Example	Mandatory?
`name`	String	The name associated with the WhatsApp Business Phone Number that you want to search.	Samuel	No
`status`	string	Status of the WhatsApp Business phone number you want to search. The accepted values are APPROVED, PENDING, and REJECTED.	APPROVED	No
`phone_number`	String	WhatsApp Business Phone Number for which details are requested. Numbers must contain country code.	+9197654XXXXX	No
`voice_status`	String	Defines the voice status of the WhatsApp Business number to be returned. The accepted values are Enabled and Disabled.	Enabled	No
`limit`	Integer	Limit the number of responses in output. Note: If the value is not provided, by default the value is set to 25.	10	No
`offset`	Integer	Indicates the starting index in the list of fetched objects returned in the response. Note: If the value is not provided, it defaults to zero.	2	No

Sample Success Response

The following is the sample success response.

{
    "code": "WA200",
    "message": "Request Processed Successfully",
    "data": [
        {
            "phone_number": "+9197654XXXXX",
            "waba_id": "766XXXXXXXXXX",
            "status": "APPROVED",
            "name": "Samuel",
            "address": "EGL",
            "description": "Beauty Products",
            "about_info": "Cosmetics",
            "email": "[email protected]",
            "incoming_url": "www.google.com",
            "callback_profile_id": "e5a4f212-b0b0-4c77-9f04-7bXXXXXXd34f",
            "outgoing_callback_profile_id": "aasfc4b4-b700-4aec-be15-b6e7XXXXXXXf",
            "voice_enabled": "Enabled",
            "message_limit": "TIER_1K",
            "category": "AUTOMOTIVE",
            "call_hours": {
                "status": "ENABLED",
                "timezone_id": "Asia/Kolkata",
                "holiday_schedule": [
                    {
                        "date": "2025-12-08",
                        "end_time": "1730",
                        "start_time": "1230"
                    },
                    {
                        "date": "2025-12-12",
                        "end_time": "1840",
                        "start_time": "1430"
                    }
                ],
                "weekly_operating_hours": [
                    {
                        "open_time": "0900",
                        "close_time": "2000",
                        "day_of_week": "Monday"
                    }
                ]
            }
        }
    ],
    "error": {},
    "limit": 10,
    "total": 1
}

Response Parameters

The following is the list of parameters shown in the API response:

Parameter	Data Type	Description	Example
code	String	The response code for the request was sent.	WA200
message	String	The response message corresponds to the response code.	Request Processed Successfully.
data	Object	Array of the objects returned by the API response with details of the WhatsApp Business Phone Number returned.	See the specific table below for details.
error	Array	The error list associated with the response.
limit	Integer	The number of templates shown in the GET response. The default value is 25.	10
total	Integer	The count of the phone numbers records in the response output.	1

Data object Parameters

The following is the list of parameters for Data object in the API response.

Parameter	Data Type	Description	Example	Mandatory?
`phone number`	String	The WhatsApp Business Phone Number matches the query parameters.	+9197654XXXXX	Yes
`waba_id`	String	The waba_id associated with the WhatsApp Business Account to which the WhatsApp Business Phone number belongs.	766XXXXXXXXXX	Yes
`status`	string	Status of the phone number. The accepted values are APPROVED, PENDING, and REJECTED.	APPROVED	Yes
`name`	String	WhatsApp Business Phone Number name.	Samuel	Yes
`address`	String	The address associated with the phone number. Note: The maximum character limit is set to 256 characters.	EGL	Yes
`description`	String	The description associated with the phone number. Note: The maximum character limit is set to 256 characters.	Beauty Products	Yes
`about_info`	String	The information associated with the phone number. Note: The maximum character limit is set to 139 characters.	Cosmetics	Yes
`email`	String	Valid email address linked to the phone number.	[email protected]	Yes
`incoming_url`	String	Incoming messages for V1 version numbers will be routed to this URL.	www.google.com	Yes
`callback_profile_id`	String	Defines the callback profile ID attached to the phone number.	e5a4f212-b0b0-4c77-9f04-7bXXXXXXd34f	Yes
`outgoing_callback_profile_id`	String	Defines the callback profile ID attached to the phone number for the outgoing message notification.	aasfc4b4-b700-4aec-be15-b6e7XXXXXXXf	Yes
`voice_enabled`	String	Defines whether the WhatsApp voice calling is enabled for the number. The accepted values are Enabled and Disabled.	Enabled	Yes
`message_limit`	String	Defines the message limit for the phone number in a day. Default limit is set to `TIER_1K`from Meta.	TIER_1K	Yes
`category`	String	The category of the business. Note: The following are the valid values: AUTOMOTIVE, BEAUTY_SPA_SALON, CLOTHING_APPAREL, EDUCATION, ENTERTAINMENT, EVENT_PLANNING_SERVICE, FINANCE_AND_BANKING, FOOD_GROCERY, PUBLIC_SERVICE, HOTEL_LODGING, MEDICAL_HEALTH, NON_PROFIT, PROFESSIONAL_SERVICES, SHOPPING_RETAIL, TRAVEL_TRANSPORTATION, RESTAURANT, OTHER.	AUTOMOTIVE	Yes
`call_hours`	JSON	Indicates whether call hours are enabled and, if so, includes the time zone, holiday schedule, and weekly working hours.	See the specific table for details.	Yes

The following is the list of parameters for call_hours object in the API response.

Parameter	Data Type	Description	Example	Mandatory?
`status`	String	Status indicates whether the call hours are enabled or disabled.	Enabled	Yes
`timezone_id`	String	Time zone that the call hours are set in.	Asia/Kolkata	Yes
`holiday_schedule`	List of JSON	Holiday schedule of the business for calling.	See the specific table for details.	Yes
`weekly_operating_hours`	List of JSON	Weekly operating hours of the business for calling.	See the specific table for details.	Yes

The following is the list of parameters for holiday_schedule object in the API response.

Parameter	Data Type	Description	Example	Mandatory?
`date`	String	Date of the business holiday in the YYYY-MM-DD format.	2025-12-08	Yes
`end_time`	String	End time of the business holiday in 24-hours format.	1730	Yes
`start_time`	String	Start time of the business holiday in 24-hours format.	1230	Yes

The following is the list of parameters for weekly_operating_hours object in the API response.

Parameter	Data Type	Description	Example	Mandatory?
`open_time`	String	Opening time of the business in 24-hours format.	0900	Yes
`close_time`	String	Closing time of the business in 24-hours format.	2000	Yes
`day_of_week`	String	Specifies the corresponding day of the week.	Monday	Yes

Sample Failure Response

The following are the failure responses:

{
    "code": "RBC001",
    "message": "Incorrect SID or API key.",
    "data": [],
    "error": {
        "body": "Incorrect SID or API key.",
        "error": "record not found"
    }
}

{
    "code": "WA401",
    "message": "Waba_id is not present or does not belong to the account.",
    "data": {},
    "error": {
        "waba_id": "Waba_id is not present or does not belong to the account."
    }
}

{
    "code": "WA400",
    "message": "Refer to correct payload format",
    "data": {},
    "error": {
        "payload": "Incorrect payload format"
    }
}

{
    "code": "WA500",
    "message": "Please try again later",
    "data": {},
    "error": {
        "error": "Internal server error"
    }
}

Updated about 18 hours ago