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:

Sign up for free with kaleyra.io. Before you get started, create a kaleyra.io account for free and Create an API Key. To view the API Key and the SID, see View API Key and SID.
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.

📘
Notes:

It is recommended to use /sms endpoints instead of /message endpoints for more efficient API requests and responses.

For North America (NA) pod users, use /sms endpoints for SMS API services provided by Kaleyra platform.

Base URL

https://<api_domain>/v1/<SID>

API Domain and Value

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

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 'https://<api_domain>/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.in.kaleyra.io/v1/HXXXXXXX071IN/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).	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.	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

Success Response

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": {}

}

Failure Response

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 7 days ago