Overview

CheckMobi Number Lookup API gives you real-time phone intelligence for numbers across 200+ countries, through three tiers: a free phone number validation, a cost-efficient MNP lookup, and a full HLR lookup that queries the mobile network directly.

MNP and HLR Lookup are relevant only for mobile numbers. If you request an HLR/MNP Lookup on a landline number, it automatically falls back to the Phone Number Validation API and no charge is applied. The exception is the North American Numbering Plan, where a Lookup is required just to determine whether a number is mobile.

Phone Number Validation

Phone Number Validation is free of charge and tells you if the specified phone number looks valid. It also includes some alternative formats to display the phone number in, the timezone where the number might belong, and information regarding the country, area, and operator where the number was originally issued (where possible).

Validate a Phone Number

This resource validates phone numbers based on their syntax, length, and numbering-plan allocation — free of charge. It does not query the mobile network or verify whether the number is currently active.

REQUEST

• Resource: /lookup/verify/{NUMBER}
• Method: GET
• Authentication: Authorization header
• Content-Type: application/json
• Success code: 200

RESPONSE

Property	Type	Nullable	Description
id	string		Unique verification ID.
cost	float		For the validation process is always 0. Is relevant only for HLR Lookup.
phone_number	string		The Phone Number in E.164 format.
number_type	string		The number type as it was issued. See Number types section for more details.
timezone	string		The timezone associated with this number. This is based on the original location where the number was issued.
format.e164	string		The number formatted in E.164 format.
format.international	string		The number formatted in the international format.
format.national	string		The number formatted in the national format.
format.rfc3966	string		The number formatted in the RFC3966 format.
original_network.country_iso2	string		The country code (ISO2) where the number belongs.
original_network.country_prefix	string		The country international calling prefix.
original_network.area	string	✓	If this data is identifiable will be the area of the original network (issuing network).
original_network.network_name	string	✓	If this data is identifiable will be original operator that issued the number.

original_network.* refers to the issuing network (the one that issued the number). Information like area and network_name might not be available or accurate in certain destinations as the validation process is free of charge and is not querying the carrier's networks for retrieving the data.

REQUEST

RESPONSE

HLR Lookup

An HLR Lookup provides a comprehensive way to validate and enrich mobile number data by querying network-level information to determine the operator currently serving a number and whether the number is active.

Depending on the destination and available network data, an HLR lookup can also provide the number's portability status, distinguishing between the current serving network and the original issuing network, as well as the IMSI where available.

By validating numbers before sending messages or initiating calls, you can keep your customer database clean, identify inactive or invalid numbers, and reduce unnecessary messaging and termination costs.

Pairing HLR lookups with AntiFraud takes this further — filtering out unreachable numbers before you spend on an SMS or call to them.

Pricing scales with your volume and stays transparent, with no hidden fees — see the pricing page for validation, MNP and HLR rates by destination.

Perform an HLR Lookup

This resource queries network-level data to determine the current operator and number status, with portability information and additional network data such as IMSI available where supported — paid per lookup.

REQUEST

• Resource: /lookup/hlr/{NUMBER}
• Method: GET
• Authentication: Authorization header
• Content-Type: application/json
• Success code: 200

RESPONSE

Property	Type	Nullable	Description
id	string		Unique lookup ID.
cost	float		The HLR lookup cost charged in USD.
phone_number	string		The Phone Number in E.164 format.
number_type	string		The phone number type. See Number types section for more details.
timezone	string		The timezone associated with this number. This is based on the original location where the number was issued. It doesn't track in any way the current user location.
is_ported	bool	✓	Indicates if the number is ported or not. null is sent in case the information is not available.
reachable	string		Indicates the reachability status in that specific moment where possible. Please see the Reachability State section for all possible values.
processing_status	string		Indicates the final processing status for the HLR lookup operation. Please see the Processing Statuses section for all possible values.
imsi	string	✓	International Mobile Subscriber Identity (IMSI). Unique identification number associated with the SIM card. The availability of the IMSI depends on the mobile network operator.
format.e164	string		The number formatted in E.164 format.
format.international	string		The number formatted in the international format.
format.national	string		The number formatted in the national format.
format.rfc3966	string		The number formatted in the RFC3966 format.
original_network.country_iso2	string		The country code (ISO2) where the number was originally issued.
original_network.country_prefix	string		The international calling prefix of the country where the number was originally issued.
original_network.area	string	✓	If this data is identifiable will be the area where the number was issued.
original_network.mccmnc	string	✓	A five or six character MCCMNC (mobile country code + mobile network code tuple) identifying the network that issued the phone number.
original_network.mcc	string	✓	A three character MCC (mobile country code) identifying the country where the mobile phone number was issued.
original_network.mnc	string	✓	A two or three character MNC (mobile network code) identifying the network the mobile phone number was issued to.
original_network.network_name	string	✓	If this data is identifiable will be the name of the operator that issued the number.
current_network.country_iso2	string	✓	The country code (ISO2) of the current network where the number is assigned.
current_network.country_prefix	string	✓	The international calling prefix of the country where the number currently assigned.
current_network.area	string	✓	If this data is identifiable will be the area where the number is currently assigned.
current_network.mccmnc	string	✓	A five or six character MCCMNC (mobile country code + mobile network code tuple) identifying the network the mobile phone number currently belongs to.
current_network.mcc	string	✓	A three character MCC (mobile country code) identifying the country where the mobile phone number currently belongs to.
current_network.mnc	string	✓	A two or three character MNC (mobile network code) identifying the network the mobile phone number currently belongs to.
current_network.network_name	string	✓	If this data is identifiable will be the name of the operator where the number is currently assigned.

REACHABILITY STATE

For every valid number processed through the HLR Lookup we'll return information regarding the current reachability status of that number. Using this information you can determine if the number is currently live and contactable.

State	Description
connected	Active mobile number.
absent	Number is not reachable at this moment. Please see our Absent Subscriber section for further details.
no-teleservice-provisioned	This number is not able to receive calls or SMS messages. This is usually a number relating to a data SIM.
inconclusive	We are unable to retrieve a response from the network for this number. The network doesn't provide this information.
no-coverage	We don't provide a coverage for this destination.
failed	The partner networks encountered an error while performing this operation.
invalid	The number provided is not valid.

ABSENT SUBSCRIBER

If your reachability property returns that the number is Absent Subscriber (absent) then there are a number of possible reasons for this:

• Phone is turned off and a call was made to the number during this period. When an attempt to connect to a number fails because is turned off, has no signal or is in Airplane mode, then the HLR will be updated to an Absent Subscriber status to reflect that calls cannot currently connect or SMS cannot be delivered to that number. When the handset is turned back on it will connect to a Cell Tower and the HLR will be updated and mark that the number is reachable.
• A long period of inactivity on the number. Each network operator has different thresholds when updating the HLR database to show a mobile number as Absent. Typically if a number has not been turned on in a handset for longer than 4 days then it will be deemed as Absent and an HLR Lookup will reflect this.
• The number has been allocated to a SIM card but has not yet been connected (for example a phone number that is still in a shop waiting to be sold).

PROCESSING STATUSES

State	Description
completed	The lookup query was completed with a valid response.
rejected	The number does not qualify for a lookup and has been rejected. Mostly invalid numbers or landlines.
failed	The lookup query was processed but an error or exception occurred.

NUMBER TYPES

Type	Description
landline	Landline phone number.
mobile	Mobile phone number.
mobile_or_landline	Landline or mobile phone number. Might qualify for HLR/MNP lookup (e.g. US and Canada).
toll_free	Toll free phone number.
premium_rate	Premium rate phone number with additional charges.
shared_cost	Shared cost phone number. Typically less expensive than premium rate phone numbers.
personal_number	A personal number is associated with a particular person, and may be routed to either a mobile or landline number. Some more information can be found here.
voip	Voice over IP phone number. Includes TSoIP phone numbers (Telephony Service over IP).
pager	Pager phone number. Typically no voice functionality.
uan	Universal Access Number (Company Number). Might be routed to specific offices but allows one number to be used for the company.
voicemail	Voicemail phone number.
unknown	Number type could not be determined.

REQUEST

RESPONSE

Perform bulk HLR Lookup

Using this method you can perform a series of asynchronous HLR Lookups and get the results posted back to your server via HTTP callback. This resource is suitable for processing a large number of mobile phone numbers that aren't real-time critical (e.g.: database cleanup).

REQUEST

• Resource: /lookup/hlr
• Method: POST
• Authentication: Authorization header
• Content-Type: application/json
• Success code: 200

PARAMETERS

Property	Type	Required	Description
numbers	[string]	✓	List of numbers to be checked in E.164 format (opens new window). Maximum 1000 numbers allowed.
notification_callback	string	✓	Fully qualified URL where to receive the results of the HLR lookup when ready. Please see the Lookup Notification Callback section below for more details.

RESPONSE

Property	Type	Description
total_count	integer	Count of numbers submitted in the request.
accepted_count	integer	Count of numbers queued for HLR lookup.
rejected_count	integer	Count of invalid numbers rejected.
rejected	[string]	The list of invalid numbers rejected.
notification_callback	string	The URL where the HLR results will be submitted when they are available.

LOOKUP NOTIFICATION CALLBACK

Each time a new HLR lookup result is available, it's pushed to the specified URL via the POST method. Your callback must respond with HTTP status 200 OK. If any other status code is returned, we retry the request up to 3 times.

For each bulk request sent, multiple callbacks can be triggered as numbers will be divided into multiple batches when lookup is performed. The request body is JSON encoded containing the following properties:

Property	Type	Description
lookup_method	string	The requested lookup method: hlr, mnp or verify.
error	object	null in case the operation was successful, otherwise indicates the error that occurred for a certain lookup batch (e.g.: there is no credit available so the entire operation is canceled). The object has 3 properties: error - indicates the error code, description - human readable description of the error, and affected_numbers - the numbers affected by the failure.
results	[object]	In case the error is null this property will be populated with the lookup responses (each object having the properties described below), otherwise in case of an error the property is null.

HLR RESULT PROPERTIES

Property	Type	Nullable	Description
id	string		Unique lookup ID.
original_msisdn	string		The number you sent for lookup in the original format specified into the request. You can use this property to match the numbers from the request with the one from the response.
cost	float		The HLR lookup cost charged in USD.
phone_number	string		The Phone Number in E.164 format.
number_type	string		The phone number type. See Number types section for more details.
timezone	string		The timezone associated with this number. This is based on the original location where the number was issued. It doesn't track in any way the current user location.
is_ported	bool	✓	Indicates if the number is ported or not. null is sent in case the information is not available.
reachable	string		Indicates the reachability status in that specific moment where possible. Please see the Reachability State section for all possible values.
processing_status	string		Indicates the final processing status for the HLR lookup operation. Please see the Processing Statuses section for all possible values.
imsi	string	✓	International Mobile Subscriber Identity (IMSI). Unique identification number associated with the SIM card. The availability of the IMSI depends on the mobile network operator.
format.e164	string		The number formatted in E.164 format.
format.international	string		The number formatted in the international format.
format.national	string		The number formatted in the national format.
format.rfc3966	string		The number formatted in the RFC3966 format.
original_network.country_iso2	string		The country code (ISO2) where the number was originally issued.
original_network.country_prefix	string		The international calling prefix of the country where the number was originally issued.
original_network.area	string	✓	If this data is identifiable will be the area where the number was issued.
original_network.mccmnc	string	✓	A five or six character MCCMNC (mobile country code + mobile network code tuple) identifying the network that issued the phone number.
original_network.mcc	string	✓	A three character MCC (mobile country code) identifying the country where the mobile phone number was issued.
original_network.mnc	string	✓	A two or three character MNC (mobile network code) identifying the network the mobile phone number was issued to.
original_network.network_name	string	✓	If this data is identifiable will be the name of the operator that issued the number.
current_network.country_iso2	string	✓	The country code (ISO2) of the current network where the number is assigned.
current_network.country_prefix	string	✓	The international calling prefix of the country where the number currently assigned.
current_network.area	string	✓	If this data is identifiable will be the area where the number is currently assigned.
current_network.mccmnc	string	✓	A five or six character MCCMNC (mobile country code + mobile network code tuple) identifying the network the mobile phone number currently belongs to.
current_network.mcc	string	✓	A three character MCC (mobile country code) identifying the country where the mobile phone number currently belongs to.
current_network.mnc	string	✓	A two or three character MNC (mobile network code) identifying the network the mobile phone number currently belongs to.
current_network.network_name	string	✓	If this data is identifiable will be the name of the operator where the number is currently assigned.

EXAMPLE

{
	"lookup_method": "hlr",
	"error": null,
	"results": [
		{
			"id": "c08c0e33-e1b8-43a2-a4f8-4518c3a82cb4",
			"original_msisdn": "4074XXXXXXX",
			"cost": 0,
			"phone_number": "+4074XXXXXXX",
			"number_type": "mobile",
			"timezone": "Europe/Bucharest",
			"format": {
				"e164": "+4074XXXXXXX",
				"international": "+40 74X XXX XXX",
				"national": "074X XXX XXX",
				"rfc3966": "tel:+40-74X-XXX-XXX"
			},
			"is_ported": false,
			"reachable": "connected",
            "processing_status": "completed",
			"imsi": "226100000000000",
			"current_network": {
				"country_iso2": "RO",
				"country_prefix": 40,
				"country_name": "Romania",
				"mccmnc": "22610",
				"mcc": "226",
				"mnc": "10",
				"area": "RO",
				"network_name": "Orange"
			},
			"original_network": {
				"country_iso2": "RO",
				"country_prefix": 40,
				"country_name": "Romania",
				"mccmnc": "22610",
				"mcc": "226",
				"mnc": "10",
				"area": "RO",
				"network_name": "Orange"
			}
    	},
    	...
	]
}

REQUEST

RESPONSE

MNP Lookup

Mobile Number Portability (MNP) enables mobile subscribers to retain their phone number when switching from one service provider to another. As number portability has become widespread globally, the operator originally associated with a number’s numbering range can no longer be assumed to be its current network.

For telecom operators, SMS aggregators, and other applications that require accurate network identification, this distinction is critical for determining the current MCCMNC and ensuring correct routing and termination.

A MNP Lookup provides the current MCCMNC at a lower cost than a full HLR lookup, making it a cost-efficient option when you only need to identify the network currently serving the number.

Perform a MNP Lookup

This resource identifies the mobile network currently serving a number based on portability data, including its current MCCMNC — paid per lookup. It does not verify whether the number is currently active or provide network-level subscriber information.

REQUEST

• Resource: /lookup/mnp/{NUMBER}
• Method: GET
• Authentication: Authorization header
• Content-Type: application/json
• Success code: 200

RESPONSE

Property	Type	Nullable	Description
id	string		Unique lookup ID.
cost	float		The MNP lookup cost charged in USD.
phone_number	string		The Phone Number in E.164 format (opens new window).
number_type	string		The phone number type. See Number types section for more details.
timezone	string		The timezone associated with this number. This is based on the original location where the number was issued. It doesn't track in any way the current user location.
processing_status	string		Indicates the final processing status for the MNP lookup operation. Please see the Processing Statuses section for all possible values.
imsi	string	✓	International Mobile Subscriber Identity (IMSI) (opens new window). Unique identification number associated with the SIM card. The availability of the IMSI depends on the mobile network operator.
format.e164	string		The number formatted in E.164 format (opens new window).
format.international	string		The number formatted in the international format.
format.national	string		The number formatted in the national format.
format.rfc3966	string		The number formatted in the RFC3966 format (opens new window).
current_network.country_iso2	string	✓	The country code (ISO2) of the current network where the number is assigned.
current_network.country_prefix	string	✓	The international calling prefix of the country where the number currently assigned.
current_network.area	string	✓	If this data is identifiable will be the area where the number is currently assigned.
current_network.mccmnc	string	✓	A five or six character MCCMNC (mobile country code + mobile network code tuple) identifying the network the mobile phone number currently belongs to.
current_network.mcc	string	✓	A three character MCC (mobile country code) identifying the country where the mobile phone number currently belongs to.
current_network.mnc	string	✓	A two or three character MNC (mobile network code) identifying the network the mobile phone number currently belongs to.
current_network.network_name	string	✓	If this data is identifiable will be the name of the operator where the number is currently assigned.

REQUEST

RESPONSE

Perform bulk MNP Lookup

Using this method you can perform a series of asynchronous MNP Lookups and get the results posted back to your server via HTTP callback. This resource is suitable for processing a large number of mobile phone numbers that aren't real-time critical.

REQUEST

• Resource: /lookup/mnp
• Method: POST
• Authentication: Authorization header
• Content-Type: application/json
• Success code: 200

PARAMETERS

Property	Type	Required	Description
numbers	[string]	✓	List of numbers to be checked in E.164 format (opens new window). Maximum 1000 numbers allowed.
notification_callback	string	✓	Fully qualified URL where to receive the results of the MNP lookup when ready. Please see the Lookup Notification Callback section below for more details.

RESPONSE

Property	Type	Description
total_count	integer	Count of numbers submitted in the request.
accepted_count	integer	Count of numbers queued for MNP lookup.
rejected_count	integer	Count of invalid numbers rejected.
rejected	[string]	The list of invalid numbers rejected.
notification_callback	string	The URL where the MNP results will be submitted when they are available.

MNP LOOKUP NOTIFICATION CALLBACK

Each time a new lookup result is available, it's pushed to the specified URL via the POST method. Your callback must respond with HTTP status 200 OK. If any other status code is returned, we retry the request up to 3 times.

For each bulk request sent, multiple callbacks can be triggered as numbers will be divided into multiple batches when lookup is performed. The request body is JSON encoded containing the following properties:

Property	Type	Description
lookup_method	string	The requested lookup method: hlr, mnp or verify.
error	object	null in case the operation was successful, otherwise indicates the error that occurred for a certain lookup batch (e.g.: there is no credit available so the entire operation is canceled). The object has 3 properties: error - indicates the error code, description - human readable description of the error, and affected_numbers - the numbers affected by the failure.
results	[object]	In case the error is null this property will be populated with the lookup responses (each object having the properties described below), otherwise in case of an error the property is null.

MNP RESULT PROPERTIES

Property	Type	Nullable	Description
id	string		Unique lookup ID.
original_msisdn	string		The number you sent for lookup in the original format specified into the request. You can use this property to match the numbers from the request with the one from the response.
cost	float		The MNP lookup cost charged in USD.
phone_number	string		The Phone Number in E.164 format (opens new window).
number_type	string		The phone number type. See Number types section for more details.
timezone	string		The timezone associated with this number. This is based on the original location where the number was issued. It doesn't track in any way the current user location.
processing_status	string		Indicates the final processing status for the MNP lookup operation. Please see the Processing Statuses section for all possible values.
imsi	string	✓	International Mobile Subscriber Identity (IMSI) (opens new window). Unique identification number associated with the SIM card. The availability of the IMSI depends on the mobile network operator.
format.e164	string		The number formatted in E.164 format (opens new window).
format.international	string		The number formatted in the international format.
format.national	string		The number formatted in the national format.
format.rfc3966	string		The number formatted in the RFC3966 format (opens new window).
current_network.country_iso2	string	✓	The country code (ISO2) of the current network where the number is assigned.
current_network.country_prefix	string	✓	The international calling prefix of the country where the number currently assigned.
current_network.area	string	✓	If this data is identifiable will be the area where the number is currently assigned.
current_network.mccmnc	string	✓	A five or six character MCCMNC (mobile country code + mobile network code tuple) identifying the network the mobile phone number currently belongs to.
current_network.mcc	string	✓	A three character MCC (mobile country code) identifying the country where the mobile phone number currently belongs to.
current_network.mnc	string	✓	A two or three character MNC (mobile network code) identifying the network the mobile phone number currently belongs to.
current_network.network_name	string	✓	If this data is identifiable will be the name of the operator where the number is currently assigned.

EXAMPLE

{
	"lookup_method": "mnp",
	"error": null,
	"results": [
		{
			"id": "c08c0e33-e1b8-43a2-a4f8-4518c3a82cb4",
			"original_msisdn": "4074XXXXXXX",
			"cost": 0,
			"phone_number": "+4074XXXXXXX",
			"number_type": "mobile",
			"timezone": "Europe/Bucharest",
			"format": {
				"e164": "+4074XXXXXXX",
				"international": "+40 74X XXX XXX",
				"national": "074X XXX XXX",
				"rfc3966": "tel:+40-74X-XXX-XXX"
			},
            "processing_status": "completed",
			"imsi": "226100000000000",
			"current_network": {
				"country_iso2": "RO",
				"country_prefix": 40,
				"country_name": "Romania",
				"mccmnc": "22610",
				"mcc": "226",
				"mnc": "10",
				"area": "RO",
				"network_name": "Orange"
			}
	    },
    	...
	]
}

REQUEST

RESPONSE