Generate OTP Using Contact Details

Generate a One-Time Password (OTP) using a mobile number, email address, or both, without requiring a registered User ID.

This API is intended for scenarios such as POS, credit card applications, loan disbursal, or other onboarding flows where a user has not yet been assigned a User ID.

Endpoint

POST /v1/otp-using-contact-details

Authentication

Authorization: Bearer <access_token>

Request Body

Example Request

{
  "otpSpec": "N-6",
  "dispatchOptions": {
    "SMS": "smsTemplate1",
    "EMAIL": "emailTemplate1"
  },
  "mobileNumber": "8500490000",
  "emailId": "[email protected]",
  "dynamicMacros": {
    "__CUSTOMER_NAME__": "John Doe"
  },
  "attempts": 10,
  "expiresIn": 300,
  "hashSpec": "SHA_256",
  "msgId": "payment-12345"
}

Field Details

dispatchOptions

Specifies the delivery channels and template names.

{
  "SMS": "smsTemplate1",
  "EMAIL": "emailTemplate1"
}

mobileNumber

Required when the request sends the OTP using the SMS channel.

emailId

Required when the request sends the OTP using the EMAIL channel.

dynamicMacros

Mandatory key/value pairs used to replace macros in the configured templates.
If none then use
eg: "dynamicMacros": {
_": "John Doe"

otpSpec

Legacy OTP specification format.
Supported OTP specifications are:

• N-x
• L-x
• U-x
• M-x
• LN-x
• UN-x
• MN-x

Where,

• L – Lowercase alphabets,
• U – Uppercase alphabets,
• M – Mixed case alphabets,
• N – Numeric characters,
• LN – Lowercase alphabets and Numeric characters,
• UN – Uppercase alphabets and Numeric characters,
• MN – Mixed case alphabets and Numeric characters
• x – the length of OTP value to be generated. Minimum 4, Maximum 9.

Examples:

• N-6
• L-6
• U-6
• M-6
• LN-6
• UN-6
• MN-6

Please note that the character set and length is separated by the hyphen "-". The OTP specification followed by default is “N-6”, indicating that the OTP should consist of 6 characters and be generated solely from numeric characters.


Supported Hash Algorithms

• PLAIN
• SHA_256
• SHA_384
• SHA_512
• SHA_HEX_256
• SHA_HEX_384
• SHA_HEX_512

Success Response

{
  "otpUuid": "6c677c1e-e78e-4e19-a77c-1ee78efe1998"
}

Error Responses

Example - Missing Mobile Number

{
  "timestamp": "2025-03-26T10:22:21UTC",
  "status": 422,
  "error": "Invalid data",
  "message": "Mobile Number is Mandatory",
  "path": "/v1/otp-using-contact-details"
}

Example - Invalid OTP Specification

{
  "timestamp": "2025-02-20T09:00:26IST",
  "status": 422,
  "error": "Invalid data",
  "message": "Invalid OTP Specification",
  "path": "/v1/otp-using-contact-details"
}

Best Practices

• Use this API when a user has not yet been assigned a User ID.
• Supply mobileNumber when sending SMS and emailId when sending Email.
• Include both channels to deliver the same OTP through SMS and Email.
• Ensure all OTP templates contain the __RELID_OTP__ macro.
• Store the returned otpUuid for OTP validation.

Related APIs

• Validate OTP
• Check OTP Status