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.
Prerequisites
- Before sending the SMS, you must configure the SMS channel in kaleyra.io.
- After you sign up, your account will be on the trial version. You must complete the KYC to access all the features in kaleyra.io.
- 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>/v1/<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 |
API request to Create Sender ID
To create sender ID use the <api_domain>/v1/<sid>/sms/sender
endpoint with the following request method:
Request Format
The following is the request format to create sender ID:
curl --location --request POST 'https://<api_domain>/v1/<sid>/sms/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>",
}
]
}'
Note:
For Indian (IN) customers that they need to register the senderID with the DLT
Sample Request Format
The following is the sample request format to create sender ID:
curl --location --request POST 'https://api.in.kaleyra.io/v1/HXXXXXXX071IN/sms/sender' \
--header 'api-key:Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--header 'Content-Type:application/json' \
--data-raw '{
"data" :[
{
"sender": "ADPAI",
"description": "Sender ID testing",
"iso_code": "in",
"entity_id": "12xxxxxxxxxx12",
},
{
"sender": "ABCF01",
"description": "testing",
"iso_code": "in",
"entity_id": "12xxxxxxxxxx11",
}
]
}'
URL Parameters and Headers
Following is the list of parameters and headers to send the outgoing message request:
Parameter | Data Type | Description | Examples | Mandatory? |
---|---|---|---|---|
sid | String | Account SID (Security Identifier). | HXXXXXXX071IN | 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. | ABCF01 | Yes |
description | String | Description of the sender. The description field can only contain a maximum of 100 character and a minimum of 1 character. | 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. | 12xxxxxxxx12 | Yes |
Note:
Entity ID should contain numbers and have a length of a minimum of 12 and a maximum of 30 characters.
Success Response
The following success response is received when the JSON script has the correct syntax:
"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": {}}
Failure Responses
The following failure responses are received when the JSON script has an incorrect syntax:
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"
}
}
}
SMS Error Codes, SMS Status and Status Trace Codes
Refer to the following links for Error Codes, Status and Status Trace Codes:
- For information related to SMS error codes, see SMS Error Codes.
- For information related to SMS status and status trace codes, see SMS Status and Status Trace Codes.
Updated 14 days ago