Send SMS (JSON/XML)

POST Method

The Send SMS JSON/XML API allows you to send the same message to multiple numbers or different messages to different numbers.

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.
  • You must have an approved SenderID or a specific number to be used as SenderID.

Base URL

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

API Domain and Value

api_domainValue
IN podapi.in.kaleyra.io
SG Podapi.kaleyra.io
EU Podapi.eu.kaleyra.io
NA podapi.na.kaleyra.ai

API request to send SMS in JSON/XML

To send SMS in JSON/XML, use the <api_domain>/v1/<sid>/sms/json endpoint with the following request method:

Request Format

The following is the request format to send SMS with JSON:

curl -X POST "https://<api_domain>/v1/<sid>/sms/json" \
--header 'api-key: <api-key>' \
--header 'content-type: <content_type>' \
--data-raw '{
    "channel": "<channel>",
    "type": "<type>",
    "source":"<source>",
    "prefix": "<prefix>",
    "time":"<time>",
    "from": "<from>",
    "body":"<body>",
    "template_id":"<template_id>",
    "entity_id": "<entity_id>",
    "unicode": "<unicode>",
    "callback_profile_id": "<callback_profile_id>",
"sms": [
        {
            "to": "<to>",
            "from": "<from>",
            "body":"<body>",
            "template_id": "<template_id>",
            "entity_id": "<entity_id>",
            "unicode": "<unicode>",
            "callback_profile_id": "<callback_profile_id>"
        }
    ]
}'

Sample Request Format

The following is the sample request format to send SMS with JSON:

curl -X POST "https://api.in.kaleyra.io/v1/HXXXXXXX071US/sms/json" \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--header 'content-type: application/x-www-form-urlencoded' \
--data-raw '{
    "channel": "SMS",
    "type": "TXN",
    "source":"API",
    "prefix": "+1",
    "time":"2021-02-02T12:58:00+05:30",
    "from": "+91XXXXXXXXXX",
    "body":"Hello! This is the request to send SMS in JSON format.",
    "template_id":"912XXXXXXXX312",
    "entity_id": "1356XXXXXXXX4312",
    "unicode": "0",
    "callback_profile_id": "SG_074aXX38-2XXd-4e53-b5XX-b60c5XXXXXc5 ",
       "sms": [
        {
            "to": "+91XXXXXXXXXX",
            "from": "+91XXXXXXXXXX",
            "body":"This is the SMS JSON format.",
            "template_id": "912XXXXXXXXX12",
            "entity_id": "1356XXXXXXXXX312",
            "unicode": "0",
            "callback_profile_id": "SG_074aXX38-2XXd-4e53-b5XX-b60c5XXXXXc5"
        }
    ]
}'

Sample Request Format

The following is the sample request format to send SMS with XML:

curl --location --request POST 'https://api.in.kaleyra.io/v1/HXXXXXXX071US/sms/xml' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--header 'Content-Type: application/xml' \
--data-raw '
<?xml version="1.0" encoding="UTF-8"?>
<api>
   <channel>sms</channel>
   <type>TXN</type>
   <source>API</source>
   <prefix>+1</prefix>,
   <time>2021-02-02T12:58:00+05:30</time>
   <body>Hello! This is the request to send SMS in JSON format.</body>
   <from>+91XXXXXXXXXX</from>
   <template_id>912XXXXXXXX312</template_id>
   <entity_id>1356XXXXXXXX4312</entity_id>
   <unicode>0</unicode>
   <callback_profile_id>SG_074aXX38-2XXd-4e53-b5XX-b60c5XXXXXc5</callback_profile_id>
    <ref_custom>
    <ref_name>REF_Name</ref_name>
    <ref_age>REF_AGE</ref_age>
   </ref_custom>
   <sms>
      <to>+91XXXXXXXXXX</to>
      <from>+91XXXXXXXXXX</from>
      <body>This is the SMS JSON format.</body>
      <template_id>912XXXXXXXXX12</template_id>
      <entity_id>1356XXXXXXXXX312</entity_id>
      <unicode>0</unicode>
      <callback_profile_id>SG_074aXX38-2XXd-4e53-b5XX-b60c5XXXXXc5</callback_profile_id>
        <ref_custom>
        <ref_name>john</ref_name>
        <ref_age>25</ref_age>
      </ref_custom>
   </sms>
</api>'

Parameter and Data Types

Following is the list of parameters and data types supported for sending SMS with JSON/XML:

Parameter

Data Type

Description

Example

Mandatory

sid

String

Account SID (Security Identifier).

HXXXXXXX071US

Yes

api-key

Alphanumeric

API key generated from Kaleyra.io account.

Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3

Yes

content-type

String

The format in which the data is sent.

application/json

Yes

channel

String

API supports only SMS and the SMS will be rejected, if any other channel is passed.

SMS

No

type

String

If SMS is not provided or left empty, the default value will be MKTfor Indian customers and DEFAULT for customers from other regions.
Supported Values:

  • *MKT,DEFAULT,TXND,TXN, andOTP**.

TXN

No

source

String

If value is not passed or kept empty, then the default value is shown as API.

API

False

prefix

String

Prefix field holds country code as a value. If defined it is applicable for all the numbers in the SMS node.
Note: Priority will be given to numbers with a country code. The prefix will only be applied if the number does not include a country code.

+1

No

time

ISO

Specifies the time at which the message is sent to the recipient.
The time must be specified in the below format:
YYYY-MM-DDThh:mm:ss<Time_Zone>

2021-02-02T12:58:00+05:30

No

body

String

Specifies the message content which needs to be sent.

Hello! This is the request to send SMS in JSON format.

No

template_id

String

Specifies the Template ID registered with DLT Platform.
Mandatory only for India-based company.

912XXXXXXXX312

No

entity_id

String

Specifies the Entity ID that is registered with DLT Platform.
Mandatory only for India-based company.

1356XXXXXXXX4312

No

unicode

String

If the value is not passed in the Unicode, then the default is set to Auto.
If you want to encode the body which is in Unicode, then value is set to 1.
If you want to send SMS via JSON/XML API, without encoding the message content, then the value is set to 0.

Supported values are Auto, 0, and 1.

0

No

callback_profile_id

String

The ID of the callback profile to be used for sending webhooks related to the SMS status to the customer's system.
For more information related to callback profiles, see callback profiles page.

SG_074aXX38-2XXd-4e53-b5XX-b60c5XXXXXc5

No

SMS

JSON/XML Object

Specifies the SMS node which contains individual SMS configuration. SMS node can be repeated in the payload.

For more information related to SMS Node Fields, see SMS Node Fields table.

Yes

Object of the "SMS" Array

Following is the list of SMS object attributes:

Replace

Variable

Description

Example

Mandatory

to

Numeric

Customer Mobile Number.

+91XXXXXXXXXX

Yes

from

String

Specifies the Sender ID assigned to the account from which the SMS is sent.

+91XXXXXXXXXX

No

body

String

Message content which needs to be sent.
Note: If the body is not passed in the SMS object, then this will be considered.

This is the SMS JSON format.

No

template_id

String

Specify the Template ID registered with DLT Platform.
Mandatory only for India-based company.

912XXXXXXXX312

No

entity_id

String

Specifies the Entity ID that is registered with DLT Platform.
Mandatory only for India-based company.

1356XXXXXXXX4312

No

unicode

String

If the value is not passed, then the default is set to Auto.

Supported values are Auto, 0, and 1.

0

No

callback_profile_id

String

Specifies the Callback profile ID generated as per customer settings.

SG_074aXX38-2XXd-4e53-b5XX-b60c5XXXXXc5

No

📘

Note:

  • While sending the type of OTP, only one element is allowed into the array
  • The maximum number of elements in the SMS array is 1000.

Success Response

The following success response is received when the JSON script has the correct syntax:


{
    "body": "Hello! This is the request to send SMS in JSON format.",
    "createdDateTime": "2021-09-13 06:47:44+05:30",
    "id": "be4XXXX3-24a7-428f-b5dd-f09XXXXc14fb",
    "sms": [
        {
            "body": "This is the SMS JSON format.",
            "from": "sample",
            "message_id": "be4XXXX3-24a7-428f-b5dd-f0XXXXXX9c14:0",
            "recepient": "91XXXXXXXXXX",
            "template_id": "912XXXXXXXXX12"
        },
        {
            "body": "This is the second message",
            "from": "sample1",
            "message_id": "be43XXXX-24a7-428f-b5dd-f0XXXXXX9c14:1",
            "recepient": "91XXXXXXXXXX",
            "template_id": "912XXXXXXXXX12"
        },
        {
            "body": "This is the third message",
            "from": "sample2",
            "message_id": "be4XXXX3-24a7-428f-b5dd-f09XXXXXXXXc:2",
            "recepient": "91XXXXXXXXXX",
            "template_id": "912XXXXXXXXX12"
        }
    ],
    "source": "API",
    "type": "TXN"
}

Failure Responses

The following failure responses are received when the JSON script has an incorrect syntax:

  1. The following failure response appears when a JSON request body is invalid (if some of the fields are not appropriate).
{
    "error": {
        "code": "E700",
        "type": "VALIDATION_ERROR",
        "parameter": "sms",
        "message": "Please enter a valid JSON object",
        "reference": "0"
    }
}
  1. The following failure response appears when the user is trying to send the type of OTP to two or more recipients.
{
    "error": {
        "code": "E708",
        "type": "VALIDATION_ERROR",
        "parameter": "sms",
        "message": "For type OTP you can send only 1 sms. Sms node must have only 1 object.",
        "reference": "1"
    }
}
  1. The following failure response appears when SMS object in the request is empty.
{
    "error": {
        "code": "E703",
        "type": "VALIDATION_ERROR",
        "parameter": "sms",
        "message": "sms field is mandatory and cannot be empty",
        "reference": "2"
    }
}

SMS Error Codes, SMS Status and Status Trace Codes

Refer to the following links for Error Codes, Status and Status Trace Codes:





© 2025 Kaleyra Inc. All rights reserved.
Trademarks, logos and service marks displayed on this site are registered and unregistered trademarks of Kaleyra Inc.