Submit OTP

Endpoint Overview

POST /api/v1/telecom/submit-otp

Description

This endpoint allows you to submit the One-Time Password (OTP) received by a user after a successful Generate OTP request. It validates the OTP against the client ID and returns telecom verification data if successful. This is the second step in the two-factor telecom verification process, completing the user authentication flow.

Key Benefits

Completes the secure two-factor authentication process for telecom verification

Validates user identity through possession of the registered mobile device

Provides comprehensive telecom data upon successful verification

Helps prevent fraud by ensuring the person making the request has access to the registered phone

Use Cases

Financial Services

E-commerce

Telecom

Verify customer identity during account opening or high-value transactions

Authenticate users before allowing changes to account settings or payment methods

Complete KYC verification processes with telecom data validation

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 token
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
client_id	String	Yes	ID Number of the client to validate the OTP against
otp	String	Yes	The One-Time Password received by the user

Example Request

{
    "client_id": "ABCD1234",
    "otp": "123456"
}

Process Response

Response Parameters

The response follows the Telecom Model structure with the following key components:

Parameter	Type	Description
success	Boolean	Indicates if the OTP verification was successful
data	Object	Contains the telecom verification data
data.client_id	String	The client ID that was verified
data.verification_status	String	Status of the verification (e.g., "completed", "failed")
data.telecom_details	Object	Contains detailed telecom information
error	Object	Present only if an error occurred
message	String	Human-readable message about the result

Example Successful Response

{
    "success": true,
    "data": {
        "client_id": "ABCD1234",
        "verification_status": "completed",
        "telecom_details": {
            "name": "John Doe",
            "phone_number": "+91XXXXXXXXXX",
            "address": "123 Main St, City, State, PIN",
            "connection_type": "Postpaid",
            "activation_date": "2022-01-15"
        }
    },
    "message": "OTP verification successful"
}

Possible Error Responses

Invalid OTP

Invalid Client ID

OTP Expired

{
    "success": false,
    "error": {
        "code": "INVALID_OTP",
        "message": "The OTP provided is incorrect or has expired"
    }
}

This error occurs when the submitted OTP doesn't match the expected value or has expired.

Integration Best Practices

Security Recommendations

Implement proper error handling to manage failed OTP submissions without revealing sensitive information

Set appropriate timeouts for OTP submission to balance security with user experience

Store client IDs securely and never expose them in client-side code or logs

Implement rate limiting to prevent brute force attacks on OTP submission

User Experience Guidelines

Provide clear instructions to users on where to find the OTP (SMS, email, etc.)

Implement a resend OTP option if the user doesn't receive the code

Display meaningful error messages that guide users on how to resolve issues

Consider implementing auto-submission when OTP is detected via SMS (on mobile applications)

Code Samples

cURL

Python

Node.js

Related APIs

Generate OTP API: Initiates the OTP verification process by sending an OTP to the user's registered phone number

Telecom Verification Status API: Checks the current status of a telecom verification process

Telecom Data Retrieval API: Retrieves previously verified telecom data for a client

Compliance and Legal Considerations

When implementing telecom verification, ensure compliance with local data protection regulations such as GDPR, CCPA, or India's Personal Data Protection Bill. Obtain proper consent before initiating verification processes and clearly communicate to users how their telecom data will be used. Implement appropriate data retention policies for verification records.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/telecom/submit-otp' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "{{client_id}}", "otp": "{{otp}}" }'

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Submit OTP

Submit 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

Submit 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