Send OTP

Endpoint Overview

POST /api/v1/sms/send-otp

Description

This endpoint enables you to send a One-Time Password (OTP) via SMS to a specified mobile number. The service generates a unique OTP, sends it to the user's mobile device using the specified SMS template, and returns a client ID that can be used for subsequent verification. This API is essential for implementing secure two-factor authentication (2FA) flows, user verification processes, and secure transaction confirmations.

Key Benefits

Enhances security by adding a second layer of authentication beyond passwords

Reduces fraud by verifying the possession of the registered mobile device

Simplifies user verification with a familiar and widely accessible method

Provides a unique client ID for tracking the OTP verification lifecycle

Use Cases

Financial Services

E-commerce

Healthcare

Secure customer onboarding and KYC verification

Transaction authorization for high-value transfers

Password reset verification for banking applications

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	JWT Bearer token for authentication. Format: `Bearer <your_jwt_token>`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
template_id	String	Yes	The SMS template ID registered with telecom authorities that contains the OTP message format
mobile	String	Yes	The mobile number to which the OTP will be sent (10-digit format without country code)

Example Request

{
    "template_id": "1707167888866596321",
    "mobile": "7042174106"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the response data
data.client_id	String	Unique identifier for this OTP request, used for verification
data.mobile	String	The mobile number to which the OTP was sent
data.otp_sent	Boolean	Indicates whether the OTP was successfully sent
data.otp_verified	Boolean	Indicates whether the OTP has been verified (initially false)
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the API call was successful
message	String	Human-readable message describing the result
message_code	String	Machine-readable code representing the result

Example Successful Response

{
    "data": {
        "client_id": "send_sms_otp_rOUjQJFWppfhgxbawoQA",
        "mobile": "7042174106",
        "otp_sent": true,
        "otp_verified": false
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Mobile Number

Invalid Template ID

Authentication Error

Server Error

{
    "errors": {
        "mobile": "Mobile Number Value does not match pattern: \"^[0][1-9]\\d{9}$|^[1-9]\\d{9}$\""
    },
    "message": "Input payload validation failed"
}

The mobile number provided is not in a valid format. Ensure it's a 10-digit number without country code.

Integration Best Practices

Security Recommendations

Store the client_id securely as it will be needed for OTP verification

Implement rate limiting on your end to prevent OTP flooding attacks

Set appropriate timeouts for OTP validity (typically 5-10 minutes)

Do not log or store the actual OTP values in your systems

User Experience Guidelines

Clearly inform users that they will receive an OTP via SMS

Provide a resend option, but implement a cooldown period (30-60 seconds)

Display a countdown timer for OTP expiration

Automatically detect and fill OTP on mobile devices when possible

Code Samples

cURL

Python

Node.js

Related APIs

Verify OTP: Used to verify the OTP sent to the user's mobile number

Resend OTP: Allows resending an OTP if the previous one expired or was not received

Check OTP Status: Checks the verification status of a previously sent OTP

Compliance and Legal Considerations

When implementing SMS OTP functionality, ensure compliance with:

Telecom Regulatory Authority guidelines for SMS templates

Data protection regulations regarding user consent for SMS communications

Local regulations on authentication mechanisms for financial and sensitive transactions

Proper disclosure of SMS charges that may apply to the end user

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/sms/send-otp' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "template_id": "1707167888866596321", "mobile": "7042174106" }'

{ "data": { "client_id": "send_sms_otp_rOUjQJFWppfhgxbawoQA", "mobile": "7042174106", "otp_sent": true, "otp_verified": false }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Send OTP

Send OTP#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Send OTP

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples