Generate OTP

Endpoint Overview

POST /api/v1/telecom/generate-otp

Description

This endpoint generates a One-Time Password (OTP) for a specified mobile number. It's designed to facilitate secure authentication and verification processes by sending a time-limited OTP to the user's mobile device. The service helps verify the ownership of a mobile number before proceeding with sensitive operations or account access.

Key Benefits

Enhances security through two-factor authentication

Prevents unauthorized access to user accounts

Reduces fraud by verifying mobile number ownership

Provides a simple yet effective verification mechanism

Use Cases

Financial Services

Telecom

E-commerce

Secure customer onboarding during account creation

Transaction verification 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	Bearer token authentication using JWT
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
id_number	String	Yes	Mobile number to which the OTP will be sent
skip_otp	Boolean	No	Skip otp generation

Example Request

{
    "id_number": "9876543210"
}

Process Response

Response Parameters

Parameter	Type	Description
client_id	String	Unique identifier for the client making the request
otp_sent	Boolean	Indicates whether the OTP was successfully sent
if_number	Boolean	Indicates whether the provided number exists/is valid

Example Successful Response

{
    "client_id": "client_12345",
    "otp_sent": true,
    "if_number": true
}

Possible Error Responses

Rate Limit Exceeded

Invalid Number

Authentication Error

{
    "status_code": 429,
    "error": "Too Many Requests",
    "message": "Please wait 60 seconds before requesting another OTP for this mobile number"
}

This error occurs when you attempt to generate an OTP for the same mobile number within 60 seconds of a previous request.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement proper error handling for failed OTP generation attempts

Set appropriate timeouts for OTP verification to balance security and user experience

Consider implementing IP-based rate limiting in addition to the per-number rate limiting

User Experience Guidelines

Clearly communicate to users that an OTP will be sent to their mobile number

Provide clear instructions on where to find and how to enter the OTP

Implement a resend OTP option, but respect the 60-second cooldown period

Display appropriate error messages when rate limits are exceeded

Code Samples

cURL

Python

Node.js

Related APIs

Verify OTP: Validates the OTP entered by the user against the generated OTP

User Authentication: Authenticates users based on verified mobile numbers

Mobile Number Validation: Validates the format and existence of mobile numbers

Compliance and Legal Considerations

When implementing OTP verification, ensure compliance with telecommunications regulations and data protection laws in your operating regions. The storage and processing of mobile numbers may be subject to regulations such as GDPR in Europe, CCPA in California, or similar data protection laws in other jurisdictions. Always obtain proper consent before sending SMS messages to users.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Generate OTP

Generate 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

Generate 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