Send OTP API

This document outlines the details of the Send Mobile OTP API.

API Description

Objective

The Send Mobile OTP API shares a one-time password (OTP) to the user's phone for verification.

Input	Output
The user's mobile number and the unique identifier for your organization	The API sends an OTP to the user's email and returns a relevant JSON response

API URL

https://ind-engine.thomas.hyperverge.co/v1/verifyMobileSendOtp

API Endpoint

verifyMobileSendOtp

API Request Details

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format, and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	The media type for the request payload.	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey.	This should be both unique and easily associated with the user's journey in your application(s).

Inputs

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
templateId	The unique template identifier assigned to your organization and format by HyperVerge	Mandatory	Not Applicable - This should be a unique value	Not Applicable
mobileNumber	The ten-digit mobile number of the user based in India	Mandatory	A valid ten-digit phone number	Not Applicable
otpLength	The number of digits in the OTP definition	Optional	Any number between 4 and 9	4
otpExpiry	The OTP expiry duration in minutes (default: 24 hours, max: 7 days, min: 1 minute)	Optional	Any value between the minimum and maximum range. Minimum: 1 minute and Maximum : 10080 minutes (7 days)	1440 (24 hours)
time	The time duration value for OTP expiry as required (used in combination with timeFormat), to be send along with the OTP message	Optional	Not Applicable	Not Applicable
timeFormat	The time unit format for OTP expiry duration (e.g., "minutes", "mins")	Optional	Not Applicable	Not Applicable
showLastFourDigits	Whether to show the last four digits of the mobile number in the OTP message	Optional	"yes" or "no"	"no"

Request

The following is a standard cURL request for the API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/verifyMobileSendOtp' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "templateId": "<Enter_the_Unique_Template_Identifier_from_HyperVerge>",
    "mobileNumber": "<Enter_the_Mobile_Number_of_the_User_for_Verification>",
    "otpLength": "<Enter_the_OTP_length>",
    "otpExpiry": "<Enter_the_OTP_Expiry_Duration>",
    "time":"<Enter_the_time_duration>",
    "timeFormat":"<Enter_the_required_time_format>",
    "showLastFourDigits":"<Enter_yes_or_no>"
  }'

Success Response

The following is a successful response sample:

{
  "status": "success",
  "statusCode": 200,
  "metaData": {
      "requestId": "<Request_Identifier>"
  }
}

Failure Response

OTP Mismatch

{
  "statusCode": 200,
  "status": "failure",
  "error": {
    "message": "OTP not match",
    "type": "error"
  },
  "metaData": {
    "requestId": "<Request_Identifier>"
  }
}

Mobile Already Verified

{
  "statusCode": 200,
  "status": "failure",
  "error": {
    "message": "Mobile no. already verified",
    "type": "error"
  }
}

Invalid Resend OTP Request

{
 "statusCode": 200,
 "status": "failure",
 "error": {
  "message": "last_otp_request_on_this_number_is_invalid",
  "type": "error"
 },
 "metaData": {
 "requestId": "<Request_Identifier>"
}
}

Initial OTP Request Not Found

{
  "statusCode": 200,
  "status": "failure",
  "error": {
    "message": "No OTP request found to retryotp",
    "type": "error"
  }
}

Error Responses

Input Validation Error

{
  "message": "Input Validation Error: does not meet minimum length of 4",
  "statusCode": 400,
  "status": "failure"
}

Input Validation error for Mobile Number

{
  "message": "Input Validation Error: does not meet minimum length of 10",
  "statusCode": 400,
  "status": "failure"
}

Invalid Retry Type

{
  "message": "Input Validation Error: is not one of enum values: text,voice",
  "statusCode": 400,
  "status": "failure"
}

Input Validation error for OTP

{
  "message": "Input Validation Error: does not meet minimum length of 4",
  "statusCode": 400,
  "status": "failure"
}

Invalid Credentials

{
  "message": "Missing/Invalid credentials",
  "statusCode": 401,
  "status": "failure"
}

Internal Server Error

{
  "statusCode": 500,
  "status": "failure",
  "error": "Internal Server Error"
}

Failure and Error Response Details

A failure or error response from the module contains a failure status, with a relavant status code and error message.

The following table lists all error responses:

Status Code	Error Message	Error Description
400	This error is returned when 'image' is not sent in the API call	This error is returned when more than 2 images are sent in the API call
400	API call handles only upto 2 images	This error is returned when more than 2 images are sent in the API call
400	image size cannot be greater than 6MB	The maximum size of input image is 6MB. Crossing this will result in this error
429	Rate limit exceeded	You have exceeded the configured limit on the number of transactions permitted in a minute. Please contact the HyperVerge team for resolution
500/501	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution
503	Server busy	Please contact the HyperVerge team for resolution