Mobile Age

Endpoint Overview

POST /api/v1/mobile-vintage/mobile-age

Description

The Mobile Age API provides detailed information about a mobile number's history, including its age (how long it has been active), telecom operator, porting status, and regional information. This API helps businesses verify the authenticity and stability of a customer's mobile number, which is valuable for risk assessment, fraud prevention, and customer verification processes.

Key Benefits

Verify the age and stability of a customer's mobile number to assess risk

Identify ported numbers and their original/current telecom operators

Confirm if a mobile number is currently active and in which region

Detect potential fraud patterns based on number characteristics

Use Cases

Financial Services

E-commerce

Telecom

Assess risk during loan application by verifying mobile number stability

Enhance KYC verification by confirming mobile number authenticity

Reduce fraud by identifying recently activated or frequently ported numbers

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 authentication. Format: `Bearer YOUR_JWT_TOKEN`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
mobile_number	String	Yes	The mobile number to check. Should be a valid Indian mobile number without country code or special characters.

Example Request

{
    "mobile_number": "1231231231"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the mobile number information
data.client_id	String	Unique identifier for the client request
data.mobile_number	String	The mobile number that was checked
data.is_ported	String	Indicates if the number has been ported ("Yes" or "No")
data.mobile_age	String	Duration the mobile number has been active (e.g., "5 to 6 Years")
data.number_active	String	Indicates if the number is currently active ("Yes" or "No")
data.ported_region	String	Region to which the number was ported (if applicable)
data.ported_telecom	String	Telecom operator to which the number was ported (if applicable)
data.region	String	The region where the mobile number is registered
data.roaming	String	Indicates if the number is in roaming ("Yes" or "No")
data.telecom	String	Current telecom operator of the number
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the API call was successful
message	String	Response message
message_code	String	Code representing the response message

Example Successful Response

{
    "data": {
        "client_id": "mobile_age_vehrjYNewCoRiOqngvov",
        "mobile_number": "7827212345",
        "is_ported": "No",
        "mobile_age": "5 to 6 Years",
        "number_active": "Yes",
        "ported_region": "",
        "ported_telecom": "",
        "region": " Delhi",
        "roaming": "No",
        "telecom": "Reliance Jio "
    },
    "status_code": 200,
    "success": true,
    "message": "success",
    "message_code": "success"
}

Possible Error Responses

Invalid Mobile Number

Authentication Error

Server Error

{
    "status_code": 422,
    "success": false,
    "message": "Invalid mobile number format",
    "message_code": "invalid_input"
}

The mobile number provided is not in a valid format or contains invalid characters.

Integration Best Practices

Security Recommendations

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

Implement proper error handling to avoid exposing sensitive information

Use HTTPS for all API communications to ensure data encryption

Rotate JWT tokens periodically to minimize risk from token leakage

User Experience Guidelines

Implement proper validation for mobile numbers before making API calls

Display clear error messages to users when mobile number validation fails

Consider caching results for frequently checked numbers to improve performance

Implement appropriate retry logic with exponential backoff for temporary failures

Code Samples

cURL

Python

Node.js

Related APIs

Mobile Verification API: Verify mobile numbers through OTP

Mobile Network Operator API: Get detailed information about telecom operators

Mobile Number Validation API: Validate mobile number format and existence

Compliance and Legal Considerations

When using this API, ensure compliance with telecom regulations and data privacy laws such as TRAI regulations in India. The mobile number data should be used only for legitimate business purposes with proper user consent. Storing this information may require compliance with data protection regulations.

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/mobile-vintage/mobile-age' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "mobile_number": "1231231231" }'

{ "data": { "client_id": "mobile_age_vehrjYNewCoRiOqngvov", "mobile_number": "7827212345", "is_ported": "No", "mobile_age": "5 to 6 Years", "number_active": "Yes", "ported_region": "", "ported_telecom": "", "region": " Delhi", "roaming": "No", "telecom": "Reliance Jio " }, "status_code": 200, "success": true, "message": "success", "message_code": "success" }

Mobile Age

Mobile Age#

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

Mobile Age

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples