How to generate an OTP and send SMS notifications with Kaleyra Cloud

POST Method

Description

Kaleyra's Verify offers API for businesses to authenticate their users during the signup process by sending a One Time Password (OTP) across different channels. Create a Verify object via APIs to initiate the verification through OTP.

Prerequisites

Ensure that you have configured the following in Kaleyra Cloud before sending an OTP.

  • Template: Create a message content that contains placeholders for parameters to include OTP.
  • Verify Configuration: Select the channel through which OTP has to be sent and the validity of the OTP.

To Generate the OTP:

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

Refer to the Create an API Key page for steps to create your API key.

šŸ“˜

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 Cloud.

2. API Call

Execute the following API command to generate the OTP.

curl -X POST "https://api.kaleyra.io/v1/<SID>/verify" \
-H "Content-Type: <CONTENT_TYPE>" \
-H "api-key: <API_KEY>" \
-d '{
  "flow_id":"<FLOW_ID>",
       "to" : {
                 "mobile" : "<TO_NUMBER>",
                 "email" : "<Email_ID>"
    }
}'

Ensure to replace the parameter values with the proper inputs in the above code. The below table has a list of parameters and their information.

Replace

With

Examples

Mandatory

<SID>

Account SID (Security Identifier). Generated by Kaleyra Cloud while creating an API key.

HXXXXXXX071US

True

<CONTENT_TYPE>

Indicates the format of the content the API will be processing.

application/json

True

<API_KEY>

Your API Key generated by Kaleyra Cloud.

Ac4XXXXX21f

True

<FLOW_ID>

Id of the Configuration based on which the OTP will be generated. Configurations can be created by visiting Kaleyra Cloud web application. If a Configuration has been selected as "default" then this parameter is optional.

d990xxxx-6946-4bxx-ac18-51cxxxx2344a

False

<TO_NUMBER>

The phone numbers you want to send OTP to. Multiple phone numbers must be separated with a comma (,)
_Note:_Ensure that the country code is prefixed to the number. (E164 format).

+1202XXXXXXX

True

<EMAIL>

Email ID to which you want send OTP to.

[email protected]

False

3. Response Formats

This section provides you the success and error JSON response formats of different scenarios.

Success Response

{
  "data": {
    "verify_id": "4d3d0959-805e-43fa-bece-5815ce0795a1",
    "to": {
      "mobile": "91xxxxxxxxxx",
      "email": "Email_ID"
    },
    "flow_id": "f55b8994-7b69-47af-9ef2-1fdee4295e2b"
  }
}

šŸ“˜

Note:

The Verify ID in the above success response acts as a unique reference to the generated OTP. You must pass this ID as a parameter while validating the OTP using the API.

Error Responses

Missing Mobile Number
You will get this error as a response if you do not include the mobile number in the request. Enter the appropriate mobile number and re-execute the command.

{
  "error": {
    "code": "E804",
    "type": "VALIDATION_ERROR",
    "parameter": "mobile",
    "message": "Mobile number is mandatory.",
    "reference": ""
  }
}

Incorrect Mobile Number
You must have entered an incorrect number. The Mobile number must contain only numbers between 3 to 20 characters. Update the mobile number parameter and re-execute the command.

{
  "error": {
    "code": "E805",
    "type": "VALIDATION_ERROR",
    "parameter": "mobile",
    "message": "Please enter a valid mobile number.",
    "reference": ""
  }
}

Invalid Email ID
You must have entered an invalid email ID. Enter the correct email address and re-execute the command.

{
  "error": {
    "code": "E802",
    "type": "VALIDATION_ERROR",
    "parameter": "email",
    "message": "Please enter a valid email",
    "reference": ""
  }
}

OTP Length Mismatch
You will get this error as a response because the OTP length in the request does not match with the length you have set while creating the Verify configuring. Correct the OTP length and re-execute the command.

{
  "error": {
    "code": "E903",
    "type": "validation_error",
    "parameter": "OTP",
    "message": "Given OTP length does not match the given Flow ID OTP Length",
    "reference": ""
  }
}

Invalid Configuration ID
The Configuration ID is either invalid or not approved in this use case. Enter the correct Configuration ID and re-execute the command.

{
  "error": {
    "code": "E905",
    "type": "validation_error",
    "parameter": "flow_id",
    "message": "Flow Id not approved or not found",
    "reference": ""
  }
}

To field is mandatory
You have not included the To field parameters in the request. Enter the required details and re-execute the command.

{
  "error": {
    "code": "E600",
    "type": "VALIDATION_ERROR",
    "parameter": "to",
    "message": "to field is mandatory",
    "reference": ""
  }
}

Invalid OTP
You must have entered the incorrect OTP. The OTP must contain only alphanumeric characters. Update the parameter and re-execute the command.

{
  "error": {
    "code": "E803",
    "type": "VALIDATION_ERROR",
    "parameter": "OTP",
    "message": "OTP can contain only alphanumeric values.",
    "reference": ""
  }
}

Alphanumeric OTP
The Verify configuration associated with the ID does not support the alphanumeric OTP. Check the Configuration and enter the appropriate OTP characters.

{
  "error": {
    "code": "E914",
    "parameter": "",
    "type": "VALIDATION_ERROR",
    "message": "Flow does not support alphanumeric OTP.",
    "reference": ""
  }
}




Ā© 2020-2021 Kaleyra Inc. All rights reserved

Trademarks, logos and service marks displayed on this site are registered and unregistered trademarks of Kaleyra Inc.

Updated 2 months ago


What's Next

Validating OTP

How to generate an OTP and send SMS notifications with Kaleyra Cloud


POST Method

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.