Mobile Number Verification API

Endpoint Overview

POST /api/v1/mobile-vintage/verification

Description

The Mobile Number Verification API provides comprehensive validation and detailed information about Indian mobile numbers. This endpoint performs real-time verification of mobile number validity, connection status, and retrieves extensive service provider information including network details, porting history, and roaming status.

The API delivers critical insights for businesses requiring mobile number validation for user onboarding, fraud prevention, marketing campaigns, and customer verification processes. It returns structured data about the mobile number's current and original service providers, connection type (prepaid/postpaid), network coverage region, and historical porting information.

Key Benefits

Real-time Validation: Instant verification of mobile number validity and connection status

Comprehensive Network Data: Detailed service provider information including MNC, MCC, and network prefixes

Porting Intelligence: Historical porting data to understand number migration patterns

Fraud Prevention: Connection status verification helps identify potentially fraudulent numbers

Use Cases

Financial Services

E-commerce & Retail

Healthcare & Insurance

Customer Onboarding: Verify mobile numbers during account opening and KYC processes

Fraud Detection: Identify suspicious patterns in mobile number usage and porting history

SMS Campaign Optimization: Ensure marketing messages reach active, valid mobile numbers

Risk Assessment: Analyze connection types and service providers for credit scoring

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 for API authentication (JWT format)
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
mobile_number	string	Yes	10-digit Indian mobile number to be verified (without country code)

Example Request

{
  "mobile_number": "9955486122"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container for all verification results
data.client_id	string	Unique identifier for the verification request
data.mobile_number	string	The verified mobile number
data.result	object	Detailed verification results
data.result.is_valid	boolean	Whether the mobile number format is valid
data.result.subscriber_status	string	Current subscriber status (CONNECTED, DISCONNECTED, etc.)
data.result.connection_status	object	Connection delivery status information
data.result.connection_status.status_code	string	Status code (DELIVERED, FAILED, etc.)
data.result.connection_type	string	Service type (prepaid or postpaid)
data.result.msisdn	object	Mobile Station International Subscriber Directory Number details
data.result.msisdn.msisdn_country_code	string	Country code (IN for India)
data.result.msisdn.msisdn	string	Complete international mobile number with country prefix
data.result.msisdn.type	string	Number type (MOBILE, LANDLINE, etc.)
data.result.msisdn.mnc	string	Mobile Network Code
data.result.msisdn.imsi	string	International Mobile Subscriber Identity
data.result.msisdn.mcc	string	Mobile Country Code
data.result.msisdn.mcc_mnc	string	Combined Mobile Country Code and Mobile Network Code
data.result.current_service_provider	object	Current network service provider details
data.result.current_service_provider.network_prefix	string	Network prefix code
data.result.current_service_provider.network_name	string	Service provider name (Airtel, Jio, Vi, etc.)
data.result.current_service_provider.network_region	string	Service coverage region
data.result.current_service_provider.mcc	string	Mobile Country Code
data.result.current_service_provider.mnc	string	Mobile Network Code
data.result.current_service_provider.country_prefix	string	Country calling code
data.result.current_service_provider.country_code	string	ISO country code
data.result.current_service_provider.country_name	string	Country name
data.result.original_service_provider	object	Original network service provider details (same structure as current)
data.result.is_ported	boolean	Whether the number has been ported to a different network
data.result.last_ported_date	string	Date of last porting operation (empty if never ported)
data.result.is_roaming	boolean	Whether the number is currently in roaming status
status_code	integer	HTTP status code
success	boolean	Whether the API call was successful
message	string	Error message if applicable (null on success)
message_code	string	Response status code (success, error, etc.)

Example Successful Response

{
  "data": {
    "client_id": "mobile_vintage_GNjwwiEQghSngUdCqxUx",
    "mobile_number": "9955486122",
    "result": {
      "is_valid": true,
      "subscriber_status": "CONNECTED",
      "connection_status": {
        "status_code": "DELIVERED"
      },
      "connection_type": "prepaid",
      "msisdn": {
        "msisdn_country_code": "IN",
        "msisdn": "+919955496199",
        "type": "MOBILE",
        "mnc": "52",
        "imsi": "405520000000000",
        "mcc": "405",
        "mcc_mnc": "40552"
      },
      "current_service_provider": {
        "network_prefix": "99554",
        "network_name": "Airtel",
        "network_region": "Bihar and Jharkhand",
        "mcc": "405",
        "mnc": "52",
        "country_prefix": "+91",
        "country_code": "IN",
        "country_name": "India"
      },
      "original_service_provider": {
        "network_prefix": "99554",
        "network_name": "Airtel",
        "network_region": "Bihar and Jharkhand",
        "mcc": "405",
        "mnc": "52",
        "country_prefix": "+91",
        "country_code": "IN",
        "country_name": "India"
      },
      "is_ported": false,
      "last_ported_date": "",
      "is_roaming": false
    }
  },
  "status_code": 200,
  "success": true,
  "message": null,
  "message_code": "success"
}

Possible Error Responses

Invalid Mobile Format

Authentication Error

Server Error

{
    "errors": {
        "mobile_number": "Mobile number Mobile should not start with 0 and should be of length 10"
    },
    "message": "Input payload validation failed"
}

Occurs when the mobile number format is incorrect or contains invalid characters.

Integration Best Practices

Security Recommendations

Token Management: Store JWT tokens securely and implement automatic token refresh mechanisms

Request Validation: Always validate mobile number format on the client side before API calls

Rate Limiting: Implement client-side rate limiting to avoid exceeding API quotas

Error Handling: Implement comprehensive error handling for network failures and API errors

Data Privacy: Ensure mobile number data is handled in compliance with privacy regulations

User Experience Guidelines

Progressive Validation: Validate mobile numbers as users type to provide immediate feedback

Clear Error Messages: Display user-friendly error messages for invalid numbers or verification failures

Loading States: Show appropriate loading indicators during verification processes

Retry Logic: Implement intelligent retry mechanisms for temporary network or service failures

Fallback Options: Provide alternative verification methods when primary validation fails

Code Samples

cURL

Python

Node.js

Related APIs

Aadhaar Verification API: Verify Aadhaar card details and link with mobile numbers for enhanced KYC

PAN Card Verification API: Cross-verify PAN card information with mobile number data

Bank Account Verification API: Validate bank account details using verified mobile numbers

GST Verification API: Verify business GST details with registered mobile numbers

Voter ID Verification API: Validate voter ID information with mobile number verification

Compliance and Legal Considerations

This API processes personal mobile number data and should be used in compliance with applicable data protection regulations including the Digital Personal Data Protection Act (DPDP) 2023 in India. Ensure proper user consent is obtained before processing mobile number information. The service should only be used for legitimate business purposes such as customer verification, fraud prevention, and service optimization. Organizations must implement appropriate data security measures and retention policies when handling mobile number data retrieved through this API.

{ "data": { "client_id": "mobile_vintage_GNjwwiEQghSngUdCqxUx", "mobile_number": "9955486122", "result": { "is_valid": true, "subscriber_status": "CONNECTED", "connection_status": { "status_code": "DELIVERED" }, "connection_type": "prepaid", "msisdn": { "msisdn_country_code": "IN", "msisdn": "+919955496199", "type": "MOBILE", "mnc": "52", "imsi": "405520000000000", "mcc": "405", "mcc_mnc": "40552" }, "current_service_provider": { "network_prefix": "99554", "network_name": "Airtel", "network_region": "Bihar and Jharkhand", "mcc": "405", "mnc": "52", "country_prefix": "+91", "country_code": "IN", "country_name": "India" }, "original_service_provider": { "network_prefix": "99554", "network_name": "Airtel", "network_region": "Bihar and Jharkhand", "mcc": "405", "mnc": "52", "country_prefix": "+91", "country_code": "IN", "country_name": "India" }, "is_ported": false, "last_ported_date": "", "is_roaming": false } }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Mobile Vintage Verification

Mobile Number Verification API#

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