Telecom HLR

Endpoint Overview

POST /api/v1/telecom/hlr

Description

The Telecom HLR API enables real-time verification and detailed profiling of mobile numbers by querying the Home Location Register (HLR) database. This API provides information about the validity, type, operator, circle, porting status, and current status of a mobile number. It is designed to help businesses validate user phone numbers, prevent fraud, and optimize communication workflows by ensuring accurate and up-to-date telecom data.

Key Benefits

Instantly verifies if a mobile number is valid and active.

Identifies the original and current operator, circle, and porting status.

Reduces fraud and improves onboarding by validating user-provided numbers.

Enhances communication deliverability by filtering out invalid or inactive numbers.

Use Cases

Telecommunications

Banking & Fintech

E-commerce & Logistics

Automate SIM registration and KYC by validating mobile numbers in real time.

Detect ported numbers to optimize routing and reduce SMS/voice costs.

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.app

Production: https://kyc-api.surepass.app

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token (JWT) for API authentication
Content-Type	Yes	Must be `application/json`

Request Body

Parameter	Type	Required	Description
mobile_number	string	Yes	Mobile number with country code (e.g. for India (91))

Example Request

{
  "mobile_number": "919682439234"
}

Process Response

Response Parameters

Parameter	Type	Description
client_id	string	Unique identifier for the HLR request
mobile_number	string	The mobile number queried
is_valid	boolean	Indicates if the number is valid
number_type	string	Type of number (e.g., MOBILE, LANDLINE)
original_operator	object	Original operator details
current_operator	object	Current operator details
operator	string	Operator name
circle	string	Telecom circle/region
is_ported	boolean	Indicates if the number has been ported
number_status	string	Status of the number

original_operator / current_operator Object Fields

Parameter	Type	Description
name	string	Name of the operator
mcc_mnc	string	MCC-MNC code of the operator
country	string	Country of the operator

Number Status Values

Status Value	Alternative Name	Description
ACTIVE	OPERATIONAL	Number is active and able to receive calls or messages.
INACTIVE	DISCONNECTED	Number is disconnected and cannot receive communication.
TEMPORARILY_UNAVAILABLE	UNREACHABLE	Number is temporarily unreachable (e.g., phone off).
NO_SMS_SERVICE	DISABLED	Number cannot receive SMS messages.
NETWORK_UNAVAILABLE	NOT_AVAILABLE	Network does not provide full status information.
NO_COVERAGE_INFO	UNKNOWN	Coverage status cannot be determined.
NOT_APPLICABLE	INVALID	Status check is not applicable for this number.
UNDETERMINED	UNABLE_TO_VERIFY	Current status of the number cannot be determined.

Example Successful Response

{
  "data": {
    "client_id": "telecom_hlr_kWRWvgRBRzeKyKKiiFlF",
    "mobile_number": "919682439234",
    "is_valid": true,
    "number_type": "MOBILE",
    "original_operator": {
      "name": "Vodafone - Delhi & NCR",
      "mcc_mnc": "40411",
      "country": "India"
    },
    "current_operator": {
      "name": "Vodafone - Delhi & NCR",
      "mcc_mnc": "40411",
      "country": "India"
    },
    "operator": "Vodafone",
    "circle": "Delhi & NCR",
    "is_ported": false,
    "number_status": "UNDETERMINED"
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

Invalid Mobile Number Format

Unauthorized

{
  "status_code": 422,
  "success": false,
  "message": "Invalid Mobile Number Format. Please Enter A Valid Number With Country Code",
  "message_code": "invalid_mobile_number_format"
}

Returned when the mobile number format is invalid or missing the country code.

Integration Best Practices

Security Recommendations

Always use HTTPS to encrypt API requests and responses.

Store your API keys and JWT tokens securely; never expose them in client-side code.

Rotate your API credentials periodically and revoke unused tokens.

User Experience Guidelines

Validate mobile number format on the client side before making API requests.

Display clear error messages to users when a number is invalid or cannot be verified.

Code Samples

cURL

Python

Node.js

Related APIs

Telecom Operator Lookup API – Retrieve operator and circle details for a given mobile number.
Mobile Number Portability API – Check if a number has been ported and its current operator.
Phone Number Validation API – Validate the format and existence of a phone number.

Compliance and Legal Considerations

Ensure you have user consent before performing HLR lookups. Use this API in compliance with local telecom regulations and data privacy laws. Do not use this service for unsolicited marketing or spam.

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

{ "data": { "client_id": "telecom_hlr_kWRWvgRBRzeKyKKiiFlF", "mobile_number": "919682439234", "is_valid": true, "number_type": "MOBILE", "original_operator": { "name": "Vodafone - Delhi & NCR", "mcc_mnc": "40411", "country": "India" }, "current_operator": { "name": "Vodafone - Delhi & NCR", "mcc_mnc": "40411", "country": "India" }, "operator": "Vodafone", "circle": "Delhi & NCR", "is_ported": false, "number_status": "UNDETERMINED" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Number Status Values#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses