Create Sender ID
POST Method
The Create Sender ID API allows you to create a new Sender ID for your SMS message. Also, this API allows both to create a single Sender ID and to create more than one Sender ID in bulk.
Note:
The maximum number of sender IDs that can be generated with a single API call is 5000.
Prerequisite:
Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
Base URL
https://<api_domain>/v2/<SID>
API request to create the sender ID
To create the sender ID, use the /messages/sender endpoint with the following request method:
Request Format
The following is the request format to create the sender ID.
curl --location --request POST '<base_url>/messages/sender' \
--header 'api-key: <api_key>' \
--header 'Content-Type:<content_type>' \
--data-raw '{
"data" :[
{
"sender" :"<sender>",
"description" : "<description>",
"iso_code" : "<iso_code>",
"entity_id" : "<entity_id>",
},
{
"sender" : "<sender>",
"description" :"<description>",
"iso_code" : "<iso_code>",
"entity_id" : "<entity_id>",
}
]
}'
Sample Request Format
The following is the sample request format to create the sender ID.
curl --location --request POST 'https://api.kaleyra.io/v1/HXXXXXXX071US/messages/sender' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--header 'Content-Type: application/json' \
--data-raw '{
"data" :[
{
"sender" : "ADPAI",
"description" : "Sender ID testing",
"iso_code" : "in",
"entity_id" : "123456789012",
},
{
"sender" : "ABCF01",
"description" : "testing",
"iso_code" : "in",
"entity_id" : "123456789011",
}
]
}'
Parameter and Data Types
The following table describes the parameters and data types used in the Create Sender ID API request.
| Parameter | Data Type | Description | Examples | Mandatory? |
|---|---|---|---|---|
sid | String | Account SID (Security Identifier). | HXXXXXXX071US | Yes |
api-key | String | Your API Key generated by kaleyra.io. | Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3 | Yes |
content_type | String | The format in which the data is sent. | application/json | Yes |
sender | String | Sender ID used for sending SMS. | ADPAI | Yes |
description | String | Description of the sender. | Sender ID testing | Yes |
iso_code | String | Country code in ISO format (Should have a valid ISO code). | in | Yes |
entity_id | Number | Mandatory for India and this is the DLT entity id. Note: Entity ID should contain numbers and have a length of minimum 12 and maximum 30 characters. | 123456789012 | Yes |
Sample Success Response
The following success message appears with the status 202 Accepted:
202 Accepted
{
"code":"WA202"
"message":"Request Accepted",
"data":{
"message_id":"AXXXXXXXXXXXXXXXXXXX"
}
"error":{}
}
The following success message appears with the status 200 Accepted.
"code": "MSG106",
"message": "Your Sender ID is submitted and will be verified by a Kaleyra Support Team member.",
"data": [
{
"id": 6XX67,
"status": "1",
"sender": "TESTEHR5",
"message": "Your Sender ID is submitted and will be verified by a Kaleyra Support Team member.",
"code": "MSG106"
},
{
"id": 68XX6,
"status": "1",
"sender": "TESTET5",
"message": "Your Sender ID is submitted and will be verified by a Kaleyra Support Team member.",
"code": "MSG106"
}
],
"error": {}
}
Sample Failure Response
The following are the failure responses:
401 Unauthorized
{
"code": "RBC001",
"message": "Incorrect SID or API key.",
"data": [],
"error": {
"error": "Incorrect SID or API key."
}
}
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."
}
}
400 Incorrect payload
{
"code": "WA400",
"message": "Refer to correct payload format",
"data": {},
"error": {
"payload": "Incorrect payload format"
}
}
500 Internal Server Error
{
"code": "WA500",
"message": "Please try again later",
"data": {},
"error": {
"error": "Internal server error"
}
}
400 Low balance
{
"code": "E110",
"message": "Please check your balance, You have a low balance!",
"data": {},
"error": {
"balance": "Please check your balance, You have a low balance!"
}
}
401 Unauthorised Account type
{
"code": "WA-401",
"message": "API is not available for given customer.Please contact support for more info",
"data": {},
"error": {
"account": "API is not available for given customer.Please contact support for more info"
}
}
401 Unauthorized phone number version
{
"code": "WA-401",
"message": "The phone number you're using is associated with different Version of our WA API. Please use the appropriate endpoint.",
"data": {},
"error": {
"phone_number": "The phone number you're using is associated with different Version of our WA API. Please use the appropriate endpoint."
}
}
The following are the failure response to create the sender ID.
400 Bad Request
{
"code": "MSG134",
"message": "Sender IDs not created",
"data": [],
"error": {
"0": {
"sender": "Sender ID Already exist.",
"sender_name": "ABCF01"
},
"1": {
"sender": "Sender ID Already exist.",
"sender_name": "ABCF99"
}
}
}
400 Bad Request
{
"code": "MSG134",
"message": "Sender IDs not created",
"data": [],
"error": {
"0": {
"sender": "Sender ID has to be registered and it can only be 6 character",
"sender_name": "ABCF992"
},
"1": {
"sender": "Sender ID Already exist.",
"sender_name": "ABCF01"
}
}
}
400 Bad Request
{
"code": "RBC192",
"message": "Exceeded max capacity of 5000 senders",
"data": [],
"error": {
"error": "Exceeded max capacity of 5000 senders"
}
}
Case 1:
If the API request includes ten Sender IDs, with seven being successful and three failing, the following is the API response.
The API will be successful only if all the Sender IDs are successful. For instance, if one of the sender IDs already exists out of the 10 provided, then the API will fail with the following message:
{
"code": "MSG134",
"message": "Sender IDs not created",
"data": [],
"error": {
"0": {
"sender": "Sender ID Already exist.",
"sender_name": "TESTEHJJ5"
}
}
}
Updated 4 months ago