Add Phone Number

POST Method

The Add Phone NumberAPI allows you to add new WhatsApp Business phone numbers associated with one of your existing WABA ID within the Kaleyra communications platform.

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 Add Phone Number

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

Request Format

The following is the request format to add phone number:

curl --location --request POST  'https://<api_domain>/v2/<SID>/whatsapp/<waba_id>/number/add' \
-H 'api-key: <api-key>' \
-H 'Content-Type: <content-type>' \
-d '{
    "phone_number" : "<phone_number>",
    "name" : "<name>",
    "verification_type" : "<verification_type>",
    "country_code" : "<country_code>"
}'

Sample Request Format

The following is the sample request format to add phone number:

curl -L -X POST 'https://api.in.kaleyra.io/v2/HXAP16XXXXXX97IN/whatsapp/766XXXXXXXXXX/number/add' \
-H 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
-H 'Content-Type: application/json' \
-d '{
    "phone_number" : "976XXXXXXX",
    "name" : "KALEYRA",
    "verification_type" : "SMS/VOICE",
    "country_code" : "+91"
}'

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.	Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3	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 add phone number in JSON format:

Parameter	Data Type	Description	Example	Mandatory?
`phone_number`	String	Phone number to be added without country code.	976XXXXXXX	Yes
`name`	String	Display name of the phone number. The maximum limit is 255 characters.	KALEYRA	Yes
`verification_type`	String	OTP required via SMS or VOICE. The supported value is SMS or VOICE	SMS	Yes
`country_code`	String	Country code of the phone number.	+91	Yes

Sample Success Response

The following is the sample success response:

{
    "code": "WA200",
    "message": "Request Processed Successfully",
    "data": "7654XXXXXXXXXX",
    "error": {}
}

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": "WA400",
    "message": "phone number already exists",
    "data": [],
    "error": {
        "phone_number": "phone number already exists"
    }
}

{
    "code": "WA400",
    "message": "key: 'cloudapinumberaddrequest.verification_type' error:field validation for 'verification_type' failed on the 'required' tag",
    "data": [],
    "error": {
        "verification_type": "key: 'cloudapinumberaddrequest.verification_type' error:field validation for 'verification_type' failed on the 'required' tag"
    }
}

{
    "code": "WA400",
    "message": "key: 'cloudapinumberaddrequest.name' error:field validation for 'name' failed on the 'required' tag",
    "data": [],
    "error": {
        "name": "key: 'cloudapinumberaddrequest.name' error:field validation for 'name' failed on the 'required' tag",
        "phone_number": "phone number already exists"
    }
}

{
    "code": "WA400",
    "message": "key: 'cloudapinumberaddrequest.waba_id' error:field validation for 'waba_id' failed on the 'required' tag",
    "data": [],
    "error": {
        "waba_id": "key: 'cloudapinumberaddrequest.waba_id' error:field validation for 'waba_id' failed on the 'required' tag"
    }
}

{
    "code": "WA400",
    "message": "phone number name exceeds 255 characters",
    "data": [],
    "error": {
        "name": "phone number name exceeds 255 characters"
    }
}

{
    "code": "WA500",
    "message": "the string supplied is too short to be a phone number",
    "data": [],
    "error": {
        "error": "the string supplied is too short to be a phone number"
    }
}

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

Updated about 18 hours ago