Send OTP SMS

POST Method

Description

Kaleyra provides an API that simplifies sending critical and high priority SMS containing a one-time password. Use this API to send OTP SMS to your customers in no time.

Base URL

<https://api.kaleyra.io/v1/><SID>

To send OTP SMS, follow the below steps:

  1. Signup or Login to Kaleyra.io and create your API key.

Refer to the Create an API Key page for steps to create your API key. To view the API Key and the SID, see View API Key and SID.

📘

Note:

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.

  1. API command to Send OTP SMS

Request Format

To send OTP SMS, use the /messages endpoints.

curl -X POST "https://api.kaleyra.io/v1/<SID>/messages" \
     -H "Content-Type: <CONTENT_TYPE>" \
     -H "api-key: <API_KEY>" \
     -d "to=<TO_NUMBER>" \
     -d "type=OTP" \
     -d "sender=<SENDER_ID>" \
     -d "body= <BODY_CONTENT>" \
     -d "callback=<CALLBACK_URL>"
Request Format-Indian Customers
curl -X POST "https://api.kaleyra.io/v1/<SID>/messages" \
     -H "Content-Type: <CONTENT_TYPE>" \
     -H "api-key: <API_KEY>" \
     -d "to=<TO_NUMBER>" \
     -d "type=OTP" \
     -d "sender=<SENDER_ID>" \
     -d "body= Dear Customer, 1234 is your OTP (One Time Password) for the transaction." \
     -d "callback=<CALLBACK_URL>" \
     -d "template_id=<TEMPLATE_ID>"

📘

Note:

Ensure to replace the parameter values with the proper inputs in the above code.

Parameters and Variables

Below is the list of parameters and variables used:

ParameterVariableDescriptionExampleMandatory
SIDStringAccount SID (Security Identifier)HXXXXXXX071USYes
CONTENT_TYPEAlphabetThe format in which the data is sent.application/x-www-form-urlencodedYes
API_KEYStringAPI Key generated by Kaleyra.ioAc4XXXXX21fYes
TO_NUMBERIntegerRecipient's MSISDN (only one recipient is allowed in a single request.)+1XXXXXXXXXXYes
TYPEStringRoute typeOTPYes
SENDER_IDStringOriginator/Alphanumeric ID (default KLRHXA)KLRHXATrue
CALLBACK_URLObjectThe URL that Kaleyra Cloud should send information to when your number receives a response. This URL can be accessed publicly.https://webhook.site/89b43b12-b889-4f66-8ebf-3379b4b3345cOptional
TEMPLATE_IDIntegerUnique ID of the template (Only for Indian Customers)2xxxxxxxxxxxxYes
  1. Response Format

This section provides you the success and failure JSON response format for different scenarios.

Success Response

{
  "id": "ee8aXXXX-XXXX-XXXX-XXXX-9b717XXXX30d",
  "sender": "KLRHXA",
  "type": "OTP",
  "body": "Hello! Your OTP is 1234.",
  "createdDateTime": "2019-11-04 10:42:23+00:00",
  "totalCount": 1,
  "data": [
    {
      "message_id": "ee8aXXXX-XXXX-XXXX-XXXX-9b717XXXX30d:1",
      "recipient": "1XXXXXXXXXX"
    }
  ],
  "dlrurl": null,
  "error": {}
}
Success Response - Indian Customers
{
  "id": "ee8aXXXX-XXXX-XXXX-XXXX-9b717XXXX30d",
  "sender": "KLRHXA",
  "type": "OTP",
  "template_id": "2xxxxxxxxxxxx",
  "body": "Hello! Your OTP is 1234.",
  "createdDateTime": "2019-11-04 10:42:23+00:00",
  "totalCount": 1,
  "data": [
    {
      "message_id": "ee8aXXXX-XXXX-XXXX-XXXX-9b717XXXX30d:1",
      "recipient": "1XXXXXXXXXX"
    }
  ],
  "dlrurl": null,
  "error": {}
}

Failure Response

Multiple Mobile Numbers
Multiple Mobile Numbers are not allowed for the OTP type message. Check the To parameter for the multiple numbers.

{
  "code": "E404",
  "message": "If Type is OTP then only one mobile number is allowed.",
  "error": {
    "time": "If Type is OTP then only one mobile number is allowed."
  }
}

📘

Note:

In case of an error, ensure that the parameter values are correct in the above code. Refer to the SMS Error Codes page for detailed information.

Sample Request

curl -X POST "https://api.kaleyra.io/v1/HXXXXXXX071US/messages" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "api-key:Ac4XXXXX21f" \
     -d "to=+1XXXXXXXXXX"\
     -d "type=OTP" \
     -d "sender=KLRHXAD" \
     -d "body= Dear Customer, 1234 is your OTP (One Time Password) for the transaction."
     -d "callback=<https://webhook.site/89b43b12-b889-4f66-8ebf-3379b4b3345c"
Sample Request-Indian Customers
curl -X POST "https://api.kaleyra.io/v1/<HXXXXXXX071US>/messages" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "api-key:Ac4XXXXX21f" \
     -d "to=+1XXXXXXXXXX" \
     -d "type=OTP" \
     -d "sender=KLRHXA" \
     -d "body= Dear Customer, 1234 is your OTP (One Time Password) for the transaction." \
     -d "callback=https://webhook.site/89b43b12-b889-4f66-8ebf-3379b4b3345c" \
     -d "template_id=2xxxxxxxxxxxx"