Generate OTPs

POST Method

Description

Validate the authenticity of users with one-time passwords whenever they log in, perform transactions, make changes to their accounts.

Kaleyra’s Verify solution helps protect your customers and your business with 2FA (2-factor Authentication). You have the option to communicate the sequence of OTP generation as per your preferences. You can select the order of channels, the time interval between them, and the duration of expiration.

On our user-friendly dashboard, you can swiftly view the OTPs generated and their usage status. Each OTP expires after its successful single-use.

Prerequisites

Generate an OTP

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

Refer to the Generate an API Key page for steps to get your API key and SID (Security Identifier).

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.

ReplaceWithExamplesMandatory
Account SID (Security Identifier), created while generating an API key.HXXXXXXX071USTrue
<CONTENT_TYPE>Indicates the format of the content the API will be processing.application/jsonTrue
<API_KEY>Your API Key generated by Kaleyra.io.Ac4XXXXX21fTrue
<FLOW_ID>ID of the verification configuration based on which the OTP will be generated.d990xxxx-6946-4bxx-ac18-51cxxxx2344aIf a Configuration has been selected as "default" then this parameter is optional.
<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).
+1202XXXXXXXTrue
Email ID to which you want to send the 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": "4d3dxxxx-80xx-43xx-bexx-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": ""
  }
}

What’s Next