Telecom Verification

Endpoint Overview

POST /api/v1/telecom/telecom-verification

Description

This API endpoint provides comprehensive verification and information about a mobile number. It validates whether a given mobile number is active and legitimate, identifies the telecom operator (service provider), and determines the geographical circle to which the number belongs. This service is essential for businesses that need to verify customer contact information, prevent fraud, or segment users by telecom provider and region.

Key Benefits

Instant verification of mobile number validity to reduce failed communications

Identification of telecom operator for targeted marketing or service delivery

Geographical circle information for regional segmentation and compliance

Streamlined KYC processes with reliable telecom data verification

Use Cases

Financial Services

E-commerce

Telecommunications

Verify customer mobile numbers during account registration to ensure communication channels

Reduce fraud by confirming the legitimacy of provided contact information

Segment customers by telecom circle for region-specific offers and services

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 format
Content-Type	Yes	Application/json

Request Body

Parameter	Type	Required	Description
id_number	String	Yes	The mobile number to be verified (10-digit format)

Example Request

{
    "id_number": "1234567890"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the verification result data
data.client_id	String	Unique identifier for the verification request
data.mobile_number	String	The mobile number that was verified
data.is_valid	Boolean	Indicates whether the mobile number is valid (true) or invalid (false)
data.operator	String	The telecom service provider for the mobile number (e.g., Jio, Airtel, Vodafone)
data.circle	String	The geographical telecom circle to which the number belongs
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates whether the API request was successful
message	String	Human-readable description of the response status
message_code	String	Machine-readable code representing the response status

Example Successful Response

{
    "data": {
        "client_id": "telecom_verification_TEMsLgQPzcOnripjzkph",
        "mobile_number": "910000000",
        "is_valid": true,
        "operator": "jio",
        "circle": "Rajasthan"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Number

Authentication Error

{
    "data": {
        "client_id": "telecom_verification_invalid_number",
        "mobile_number": "123456",
        "is_valid": false,
        "operator": null,
        "circle": null
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

The number provided is not a valid mobile number. Note that even though the verification failed, the API still returns a 200 status code with is_valid set to false.

Integration Best Practices

Security Recommendations

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

Implement token refresh mechanisms to handle token expiration

Validate and sanitize mobile numbers before sending to the API

Use HTTPS for all API communications to ensure data encryption in transit

User Experience Guidelines

Implement real-time validation during user registration to improve form completion rates

Display appropriate error messages when invalid mobile numbers are detected

Consider implementing progressive disclosure of fields based on verification results

Cache verification results (where appropriate) to avoid redundant API calls

Code Samples

cURL

Python

Node.js

Related APIs

Telecom Operator Lookup API: Provides detailed information about telecom operators

Number Portability Check API: Verifies if a number has been ported between operators

SMS Verification API: Sends OTP to verify mobile number ownership

Bulk Telecom Verification API: Validates multiple mobile numbers in a single request

Compliance and Legal Considerations

This API should be used in compliance with telecom regulations and data privacy laws. Ensure you have appropriate consent before verifying user mobile numbers. The information provided by this API should be used for legitimate business purposes only and in accordance with applicable telecom regulations in your region.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/telecom/telecom-verification' \ --header 'Authorization: Bearer TOKEN' \ --header 'Content-Type: application/json' \ --data-raw '{ "id_number": "1234567890" }'

{ "data": { "client_id": "telecom_verification_TEMsLgQPzcOnripjzkph", "mobile_number": "910000000", "is_valid": true, "operator": "jio", "circle": "Rajasthan" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Telecom Verification

Telecom Verification#

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

Telecom Verification

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples