This page provides you with information on generating OTP.
For detailed information about our APIs and for hands-on testing, refer documentation in API overview and step-by-step guide on making your first API call in Make your first API call .
WarningMake sure that the OTP template does not have multiple placeholders for the OTP. This can lead to displaying OTP in all placeholders.
This API enables the issuing of validation code (OTP) to the defined communication channel for redeeming points/coupons, and registration.
Prerequisites
- Basic or OAuth credentials
- OTP access group resource with WRITE access
- Make sure that the template contains a placeholder for OTP and that the appropriate templates are approved.
- Make sure that you have configured appropriate OTP configurations as required. For more information, refer to the OTP configuration documentation.
- Make sure that the channel gateway configuration is completed. For the configuration, create a JIRA ticket for the gateway team.
- Make sure that the appropriate OTP template is configured and approved. For more information on the OTP template, refer to the OTP template documentation.
Resource information
| URI | /v2/otp/generate |
| HTTP method | POST |
| Rate limit | Based on the configuration CONF_OTP_RATE_LIMIT_ONE_HOUR. This configuration decides the number of OTPs a user can request within a 60-minute rolling window. The default value is 1000. This limit applies per mobile number per organisation |
| Batch support | No |
OTP template selection hierarchy
First preference - OTP template defined in the API body
Second preference - The default template
Third preference - If no template is configured and the template field is left blank, the system uses the inbuilt Capillary template.
Request body parameters
Notes
- If the email template is not specified, the OTP will be sent in the default email template format specified below:
“emailTemplate”:{ “subject”:“Validation Code”, “body”:“Dear Customer, The validation code for your request is: {{ validation_code }}. You will also receive the validation code by SMS on your registered mobile number shortly.” },- If SMS template is not specified, the OTP will be sent in the SMS format
"Hi user.Your otp for validation is {{ validation_code }}."
| Parameter | Type | Description |
|---|---|---|
entityType |
enum |
Specify MOBILE to identify customer by mobile number or EMAIL to identify customer by email id. |
entityValue |
String |
Value of the entity |
action |
String |
Action performed. COUPON (for coupon redemption), POINTS (for points redemption), REGISTRATION, USERGROUP, SUBSCRIPTION, GENERIC (for other purposes), POINTSTRANSFER, CUSTOMER_STATUS_UPDATE, CUSTOMER_IDENTIFIER_CHANGE, CUSTOMER_ISSUE_LINK_CARD. |
template |
String |
Defines the message template for sending OTP via SMS. Example: "Hi user. Your OTP for validation is {{ validation_code }}.Enjoy".
|
whatsappTemplateName |
String |
Approved WhatsApp template name. This is applicable only to WhatsApp communication. |
zaloTemplateIdentifier |
String |
ZALO template identifier |
emailTemplate |
Object |
Defines the message template for sending OTP via Email.
|
-- subject |
String |
Email subject (e.g., Validation Code) |
-- body |
String |
Email body template (e.g., Dear Customer, The validation code for your request is: {{ validation_code }}. You will also receive the validation code by SMS on your registered mobile number shortly.) |
channels |
Array |
Array of communication channels |
--- type |
String |
Type of channel. The supported channels are EMAIL, SMS, MOBILE or PHONE (phone call), ZALO, and WHATSAPP. The OTPs are sent to the defined channels simultaneously. For example, if you have defined SMS and Email, OTP will be sent to both Email and SMS channel simultaneously. |
--- value |
String |
Value for the channel |
{
"entityType":"email",
"entityValue":"[email protected]",
"action":"REGISTRATION",
"template":"Hi user.Your OTP for validation is {{ validation_code }}.Enjoy",
"emailTemplate":{
"subject":"Validation Code",
"body":"Dear Customer, The validation code for your request is: {{ validation_code }}. You will also receive the validation code by SMS on your registered mobile number shortly."
},
"channels":[
{
"type":"SMS",
"value":"9955882233"
},
{
"type":"EMAIL",
"value":"[email protected]"
},
{
"type":"PHONE",
"value":"9955882233"
}
]
}
{
"entityType": "mobile",
"entityValue": "919986000581",
"action": "POINTS",
"whatsappTemplateName": "test_temp2",
"channels": [
{
"type": "whatsapp",
"value": "919986000586"
}
]
}
{
"entityType":"MOBILE",
"entityValue":"911234567896",
"action":"POINTSTRANSFER",
"template":"Hi user.Your OTP for validation is {{ validation_code }}.Enjoy",
"channels":[
{
"type":"SMS",
"value":"911234567896"
},
{
"type":"PHONE",
"value":"911234567896"
}Response
| Parameter | Type | Description |
|---|---|---|
| createdId | long | Unique ID generated for the current request. |
{
"createdId": 10,
"warnings": []
}
NoteIf the OTPs are regenerated within the OTP expiry limit, the same OTP is generated again, and the createdId value appears as 1.
Error codes
| Error code | Description |
|---|---|
| 517 Rate limit exceeded | The user has reached the OTP request limit. Check the value set for the configuration CONF_OTP_RATE_LIMIT_ONE_HOUR. |
| 607 Mandatory template name not passed for WhatsApp type channel | If WhatsApp is included as a channel in the payload, ensure the whatsappTemplateName parameter is provided. |
| 621 Zalo template identifier cannot be empty | If Zalo is included as a channel in the payload, ensure the zaloTemplateIdentifier parameter is provided. |
| 8056 Invalid mobile | Enter a valid mobile number. |
| 608 Something went wrong while fetching OTP template | Ensure that OTP templates are properly configured and approved. |
| Gateway error | The Gateway configuration is incomplete. Contact the Gateway team for assistance. |