Generate OTPs

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

• Register on Kaleyra.io and complete the KYC (Know Your Customer) procedure.
• If you wish to include verification via SMS - Create a Sender ID
• If you wish to include verification via Voice calls Purchase a Number
• All OTP templates must go through an approval process. Depending on your country, you may also be required to follow certain regulations in your region. - Create a Template
• Setup the configuration to trigger the verification process - Create a Verification Configuration

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.

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": ""
  }
}