Kaleyra Cloud API Documentation

Generate OTP

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 KCloud before sending an OTP.

  • Template: Create a message content that includes placeholders for parameters to include OTP.
  • Verification Flow: 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 KCloud 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 KCloud.

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 flow based on which the OTP will be generated. Flows can be created by visiting Kaleyra Cloud web application. If a flow 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"
  }
}

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 configuring the flow. 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 Flow ID
The Flow ID is either invalid or not approved in this use case. Enter the correct Flow 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 Flow associated with the ID does not support the alphanumeric OTP. Check the Flow and enter the appropriate OTP characters.

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

Updated 3 days ago


What's Next

Validate OTP

Generate OTP


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.