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": "telecom_kpZTf8LuNsdVbGkJmTqW",
    "otp": "123456"
}

Process Response

Response Parameters

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

Parameter	Type	Required	Description
client_id	String	Yes	Unique identifier of the client
mobile_number	String	Yes	Registered mobile number of the user
address	String	Yes	Registered address of the user
correspondence_address	String	Yes	Correspondence or alternate address
city	String	No	City of residence
state	String	No	State of residence
pin_code	String	Yes	Postal/ZIP code of the user’s address
full_name	String	Yes	Full name of the user
dob	String	Yes	Date of birth in human-readable format (e.g., "12 Feb, 1990")
parsed_dob	Date	Yes	Date of birth in ISO format (YYYY-MM-DD)
user_email	String	Yes	User’s registered email address
operator	String	Yes	Telecom operator, e.g., Airtel, Jio, Vodafone, or Idea
billing_type	String	Yes	Billing type — either "prepaid" or "postpaid"
alternate_phone	String	Yes	Alternate contact number
is_enterprise	Boolean	No	Indicates if the account belongs to an enterprise/business
extra_fields	Object	No	Contains additional telecom-related information such as loyalty category, device name, pack details, payment history, etc.

Example Successful Response

{
    "data": {
        "client_id": "telecom_kpZTf8LuNsdVbGkJmTqW",
        "mobile_number": "9876543210",
        "address": "23, Laxmi Nagar, Andheri East, Mumbai, Maharashtra-400069",
        "correspondence_address": "Flat 4B, Sunrise Apartments, Andheri East, Mumbai",
        "city": "Mumbai",
        "state": "Maharashtra",
        "pin_code": "400069",
        "full_name": "Rohit Kumar Sharma",
        "dob": "12 Feb, 1990",
        "parsed_dob": "1990-02-12",
        "user_email": "rohit.sharma90@example.com",
        "operator": "Airtel",
        "billing_type": "prepaid",
        "alternate_phone": "9123456789",
        "is_enterprise": false,
        "extra_fields": {
            "loyalty_category": "Gold",
            "device_name": "Samsung Galaxy S23",
            "international_romaing": null,
            "international_roaming": false,
            "auto_pay": true,
            "credit_limit": null,
            "activation_date": "2023-03-15",
            "current_pack": {
                "name": "Rs299_28D_1.5GB/D_AirtelXstream",
                "price": "299",
                "expiry": "2025-11-28"
            },
            "payment_mode": ["UPI", "Credit Card"],
            "billing_history": [
                {
                    "date": "2025-10-20",
                    "amount": "299",
                    "payment_mode": "UPI",
                    "description": "Plan: Rs299_28D_1.5GB/D_AirtelXstream, Txn ID: AR000TP9942, Payment mode: UPI",
                    "type": "recharge"
                },
                {
                    "date": "2025-09-20",
                    "amount": "299",
                    "payment_mode": "Credit Card",
                    "description": "Plan: Rs299_28D_1.5GB/D_AirtelXstream, Txn ID: AR000TT2845, Payment mode: Credit Card",
                    "type": "recharge"
                },
                {
                    "date": "2025-08-20",
                    "amount": "299",
                    "payment_mode": "UPI",
                    "description": "Plan: Rs299_28D_1.5GB/D_AirtelXstream, Txn ID: AR000TR8820, Payment mode: UPI",
                    "type": "recharge"
                },
                {
                    "date": "2025-07-22",
                    "amount": "149",
                    "payment_mode": "UPI",
                    "description": "Plan: Rs149_20D_1GB/D, Txn ID: AR000TM7721, Payment mode: UPI",
                    "type": "recharge"
                },
                {
                    "date": "2025-06-15",
                    "amount": "19",
                    "payment_mode": "UPI",
                    "description": "Plan: MRP 19, Txn ID: AR000TK4520, Payment mode: UPI",
                    "type": "recharge"
                }
            ],
            "payment_history": []
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

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.

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/telecom/submit-otp' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "{{client_id}}", "otp": "{{otp}}" }'

{ "data": { "client_id": "telecom_kpZTf8LuNsdVbGkJmTqW", "mobile_number": "9876543210", "address": "23, Laxmi Nagar, Andheri East, Mumbai, Maharashtra-400069", "correspondence_address": "Flat 4B, Sunrise Apartments, Andheri East, Mumbai", "city": "Mumbai", "state": "Maharashtra", "pin_code": "400069", "full_name": "Rohit Kumar Sharma", "dob": "12 Feb, 1990", "parsed_dob": "1990-02-12", "user_email": "rohit.sharma90@example.com", "operator": "Airtel", "billing_type": "prepaid", "alternate_phone": "9123456789", "is_enterprise": false, "extra_fields": { "loyalty_category": "Gold", "device_name": "Samsung Galaxy S23", "international_romaing": null, "international_roaming": false, "auto_pay": true, "credit_limit": null, "activation_date": "2023-03-15", "current_pack": { "name": "Rs299_28D_1.5GB/D_AirtelXstream", "price": "299", "expiry": "2025-11-28" }, "payment_mode": [ "UPI", "Credit Card" ], "billing_history": [ { "date": "2025-10-20", "amount": "299", "payment_mode": "UPI", "description": "Plan: Rs299_28D_1.5GB/D_AirtelXstream, Txn ID: AR000TP9942, Payment mode: UPI", "type": "recharge" }, { "date": "2025-09-20", "amount": "299", "payment_mode": "Credit Card", "description": "Plan: Rs299_28D_1.5GB/D_AirtelXstream, Txn ID: AR000TT2845, Payment mode: Credit Card", "type": "recharge" }, { "date": "2025-08-20", "amount": "299", "payment_mode": "UPI", "description": "Plan: Rs299_28D_1.5GB/D_AirtelXstream, Txn ID: AR000TR8820, Payment mode: UPI", "type": "recharge" }, { "date": "2025-07-22", "amount": "149", "payment_mode": "UPI", "description": "Plan: Rs149_20D_1GB/D, Txn ID: AR000TM7721, Payment mode: UPI", "type": "recharge" }, { "date": "2025-06-15", "amount": "19", "payment_mode": "UPI", "description": "Plan: MRP 19, Txn ID: AR000TK4520, Payment mode: UPI", "type": "recharge" } ], "payment_history": [] } }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

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