# Overview

CheckMobi APIs are based on HTTP methods, which make it easy to integrate into your own products no matter what platforms are you targeting or what programming languages you are using.

If you are looking for plug&play 2FA Mobile SDKs, you can find them here: Android Remote Config SDK (opens new window), iOS Remote Config SDK (opens new window).

The Rest API described here can be integrated using any HTTP client in any programming language. For certain platforms we provide SDKs that can make your life easy. Those are open source so you can modify/customize as you wish.

The API Endpoint is: https://api.checkmobi.com/{version}/, current version of the API being v1.

  • For security reasons, all CheckMobi APIs are served over HTTPS only.
  • All POST requests require a Content-Type header set to application/json.

# API Request

# Authentication

All requests to CheckMobi API are authenticated using your secret key. Your CheckMobi secret key can be found in your application settings.

The secret key is passed to the API as value of an HTTP header called Authorization.

# Content Type

CheckMobi only accepts input of the type application/json. All POST requests arguments must be passed as json with the Content-Type set as application/json.

All GET and DELETE request arguments must be passed in the query string.

# Phone number format

Our API is accepting only phone numbers in E.164 format. You can specify the number starting with + but this is not mandatory. In case + sign is missing, it will be added automatically by our service.

For more details about E.164 standard please click here (opens new window).

# API Response

All CheckMobi API endpoints return a response in JSON format. The API returns one of the following HTTP status codes depending on whether the API call is successful or a failure.

# HTTP status codes

Status Description
200 Success. The response has JSON encoded content.
204 Success. No content available.
400 Bad request due to missing or invalid parameters. Body will contain more information regarding the error nature.
401 Unauthorized request. The Secret Key is missing or it's invalid.
403 Forbidden request. The Secret Key is not allowed to run that request.
404 The requested resource was not found.
500 Internal Server Error. In case the problem persists you should contact support for investigating the problem.
503 Service Unavailable. In case the problem persists you should contact support for investigating the problem.
SUCCESS EXAMPLE

# Error codes

In case you receive one of the above HTTP status codes that indicates an error (400, 401, 403) you will receive in the response body one of the below error codes and the description to help you to debug the route of the problem.

Error Code Description
1 Invalid or expired API secret key.
2 Invalid phone number. Phone number should be provided into E.164 format.
3 Invalid Request ID.
4 Invalid validation type. Allowed (sms, ivr, reverse_cli).
5 Insufficient funds.
6 Insufficient Missed Call validation count.
7 Invalid request payload.
8 Validation method not available for this destination.
10 Invalid event payload.
11 This operation is currently disabled for your account.
12 Your account exceeded one or more limitations.
13 Destination is blocked due to application restrictions.
14 Number temporary blocked because of too many attempts.
15 Too many attempts to verify the pin.
16 Validation request expired.
17 Invalid lookup method.
18 No HLR lookup route available for this destination.
ERROR EXAMPLE

# Notification callbacks

All HTTP callbacks sent by CheckMobi (when you are using the notification_callback parameter while triggering Validation Requests, SMS or Voice Messages or Lookup operations) are signed using the Signature key that can be found in your application General tab.

The value of the signature can be found in X-CheckMobi-Signature header and it's calculated as HMAC SHA256 over the json payload received in the notification signed with the above key.

You can use this when you want to authenticate that the notifications you are receiving are not coming from a malicious source.

# Tracking End Customer IP

Tracking the End Customer IP is needed inside of our IP based AntiFraud rules like:

  • allow or block traffic (validations, sms or voice calls) only for certain IPs.
  • limit the number of validations/sms/voice calls attempts coming from a certain IP in a specified timeframe.

In case you are using a server-server integration (all requests come to us from your servers instead of client devices) we will not have visibility into the real end customer IP. From our point of view, all requests will come from your server’s IPs so for this reason in order to have the AntiFraud modules working properly you will need to pass your customer IP into the X-Client-IP header as a string.

EXAMPLES

# Account API

Perform actions related to your account such as getting account details.

# Retrieve account details

Using this resource you can retrieve your account details like email, available credit, subscription expiration date, monthly usage, etc.

REQUEST
RESPONSE
Property Description
email Registered account email address.
subscription Current subscription available object. More details below.
cli_validations The number of successfully validated numbers during the current billing period using Missed Call method.
sms_validations The number of SMS validation requests sent during the current billing period.
ivr_validations The number of IVR validation requests sent during the current billing period.
sms_api The number of SMS API requests sent during the current billing period.
voice_api The number of Voice API requests sent during the current billing period.
expiration_date UNIX Timestamp in seconds when the current subscription expires.
credit_balance The current credit balance in USD.
call_per_minute Indicates how many calls per minute the account can send.
sms_per_minute Indicates how many messages per minute the account can send.
max_concurrent_calls Indicates how many answered concurrent calls the account can have.
SUBSCRIPTION OBJECT
Property Description
id Subscription unique identifier. One of the following values: 0 => Trial Account, 1 => Startup, 2 => Growing Business, 3 => Big Business.
name Subscription name.
limit How many successful Missed Call validations the subscription can handle. 0 indicates no limit.
REQUEST
RESPONSE

# Authentication API

Perform actions related to Two Factor Authentication integration like: Request OTP code via SMS, IVR or Missed Call, verify the pin or get the validation status.

On almost all mobile platforms it's impossible to read the user phone number from it's SIM card memory for obvious security reasons. It depends on the SIM card manufacturer if they add the mobile number into the SIM card or not. So even there is a way available to read the mobile number from the SIM card, in most cases you will receive an empty value.

Because of this reason most of the available applications prefer to validate their user's phone number using one of the following methods: SMS, IVR's or Missed Call (flash call).

# SMS and IVR

SMS and IVR are the most reliable way to integrate 2FA (Two Factor Authentication) within your application. In the next diagram you can see how SMS and IVR validation is working with CheckMobi services:

CheckMobi SMS and IVR validation Flow

# Reverse Caller ID (Missed Call or Flash Call)

In case you want to reduce your validation costs with SMS and voice calls we provide you the Reverse CLI (aka: Missed call or Flash Call) method.

This method is based on a missed call sent by CheckMobi on the user's phone number. Then in order to validate the number the app has to send back the last 4 digits from the incoming call number as a pin. On Android this can be done without any interaction from the user. The app can detect the incoming call, can close it to make sure the user will not try to answer it and also can extract the pin automatically. On the other platforms where this is not possible the user should look into call history and insert in the app the last 4 digits.

In the next diagram you can see how Reverse Caller ID validation is working with CheckMobi services:

CheckMobi Missed Call validation Flow

Tips

  • This method is very powerful on Android and it has the same security level as SMS or IVR.
  • You will have a cost per validation only in case the users will answer your call otherwise it's totally free up to certain limits based on your subscription.
  • Another downside is that on iOS or any other platforms where OS will not allow you to intercept the calls the user should insert the last 4 number digits manually.

Implementation

# Request Validation

Using this resource you can trigger a validation request using one of the available methods:

  • Reverse CLI - Validating a user's mobile phone number by using a missed call.
  • SMS - Validating a user's mobile phone number by using SMS.
  • IVR - Validating a user's mobile phone number by using an IVR (interactive voice response).

Warning

By default the Request Validation TTL (time to live) is 60 minutes and you have a maximum of 3 attempts to verify the pin during this period. You can update this values from your application settings page.

REQUEST
  • Resource: /validation/request
  • Method: POST
  • Authentication: Authorization header
  • Content-Type: application/json
  • Success code: 200
  • This resource accepts also X-Client-IP HTTP header for properly tracking the End Customer IP when you are using a server-server integration.
PARAMETERS
Property Type Required Description
number string ✓ The number that has to be validated in E.164 format.
type string ✓ Validation method to be used. One of the following values: sms, ivr, reverse_cli (for missed call).
language string This property allows you to implement internationalization into your application. In case it's missing the default sms/ivr text selected into your application settings page will be used. If the value it's present and a custom setting with that language code exists, this one will be used instead of the default one. For IVR validations, language has priority in front of voice type (man or woman). See Supported voices and languages for IVR sections below for more details.
notification_callback string Set this parameter to the fully qualified URL where to receive notifications with the completed validations in real-time. Please see the Notifications section below.
platform string One of the following values: ios, android, web, desktop. We strongly recommend using this property for better analytics.
android_app_hash string In case you are sending messages from Android and you want to use the SMS Retriever API to perform SMS-based user verification in your Android app automatically, without requiring the user to manually type verification codes(and without requiring any extra app permissions), you need to populate this field with your application hash. Messages will be formatted like: <#> {MESSAGE}\n {ANDROID_APP_HASH} in order to have the SMS Retriever API working.
NOTIFICATIONS

If you specify the notification_callback parameter, when a user validates a number we are sending a HTTP request using the POST method to this URL.

Your callback needs to respond back with HTTP status 200 OK. Our service will retry to send the request maximum 3 times in case of another status code is received.

The request body is JSON encoded containing the following properties:

Property Type Description
key string Unique identifier of the validation request (as it was received in response).
number string The number that was validated in E.164 format.
description string A short description about carrier and country: for example: FR - Orange.

Note

In case you want to make sure that the notification is not triggered from an untrusted source you can use the X-CheckMobi-Signature header as described here.

SUPPORTED LANGUAGES FOR SMS

We support all ISO-639-1 language codes. Navigate in our dashboard to Settings -> [Your application name] -> SMS settings and under Custom SMS messages add your translations. Then when you send the Validation request set the language parameter to the associated ISO-639-1 code for that language. For example for English use en or for Italian use it.

SUPPORTED VOICES AND LANGUAGES FOR IVR
Language Value WOMAN Voice MAN Voice
Danish da-DK ✓
Dutch nl-NL ✓ ✓
English - Australian en-AU ✓ ✓
English - British en-GB ✓ ✓
English - USA en-US ✓ ✓
French fr-FR ✓ ✓
French - Canadian fr-CA ✓
German de-DE ✓ ✓
Italian it-IT ✓ ✓
Polish pl-PL ✓ ✓
Portuguese pt-PT ✓
Portuguese - Brazilian pt-BR ✓ ✓
Russian ru-RU ✓
Spanish es-ES ✓ ✓
Spanish - USA es-US ✓ ✓
Swedish sv-SE ✓
RESPONSE
Property Type Description
id string Unique identifier of the validation request.
type string Validation method as requested.
pin_hash string For Reverse CLI validation only. SHA1 over the last 3 digits of the incoming call. This can be used to identify the correct incoming call did by the user.
validation_info.country_code string Country prefix from where the number belongs.
validation_info.country_iso_code string The country code from where the number belongs in ISO 3166-1 alpha-2 format.
validation_info.carrier string The name of the carrier from where the number belongs.
validation_info.is_mobile bool Indicates if number is mobile or not.
validation_info.e164_format string The number in E.164 format including + sign.
validation_info.formatting string The number formatted in E.164 format.
REQUEST
RESPONSE

# Verify PIN

Using this resource you can match a validation request with a validation pin inserted by a user. Part of IVR, SMS and Reverse CLI (Missed call) validation process.

REQUEST
  • Resource: /validation/verify
  • Method: POST
  • Authentication: Authorization header
  • Content-Type: application/json
  • Success code: 200
PARAMETERS
Property Type Required Description
id string ✓ Unique identifier for the Validation Request.
pin string ✓ The PIN as inserted by the user.
use_server_hangup boolean Optional, default is false. In case of a Reverse CLI validation (missed call) if you send this flag with true the call will be closed from the server. Some carriers when the call is rejected from the phone (client side) will charge the caller because they answer the call in background and play all kinds of message like: user is busy for example. In order to avoid being charged in this scenarios you can set this flag on true and make sure the client is configured properly to not hangup the call as well.

Note

For Reverse CLI (Missed Call) the PIN number is represented by the last 4 digits of the incoming call number.

RESPONSE
Property Type Description
number string The number associated with the Validation Request.
validated boolean Indicates if the PIN was correct or not.
validation_date integer The date time as UNIX timestamp when the validation was completed (the pin was matched first time). In case the number is not validated the value is null.
charged_amount float The amount charged for that validation (in case the charged amount is available at that time). For Reverse CLI only in case the user is fast enough to answer the call you are charged for 1 minute on that destination.
REQUEST
RESPONSE

# Get Validation Status

Using this resource you can get the last status of a validation request.

REQUEST
  • Resource: /validation/status/{id}
  • Method: GET
  • Authentication: Authorization header
  • Success code: 200
RESPONSE
Property Type Description
number string The number associated with the Validation Request.
validated boolean Indicates if the request was validated or not.
validation_date integer The date time as UNIX timestamp when the validation was completed (the pin was matched first time). In case the number is not validated the value is null.
charged_amount float The amount charged for that validation (in case the charged amount is available at that time). For Reverse CLI only in case the user is fast enough to answer the call you are charged for 1 minute on that destination.
REQUEST
RESPONSE

# Get Remote Config profile

This resource enables applications to get the Remote Config profile that is configured in the web portal for a specific destination.

REQUEST
  • Resource: /validation/remote-config
  • Method: POST
  • Authentication: Authorization header
  • Content-Type: application/json
  • Success code: 200
PARAMETERS
Property Type Required Description
number string ✓ The destination number that needs to be validated in E.164 format.
platform string ✓ One of the following values: ios, android, web, desktop. We strongly recommend using this property for better analytics.
language string This property allows you to implement internationalization into your application. In case it's missing the default sms/ivr text selected into your application settings page will be used. If the value it's present and a custom setting with that language code exists, this one will be used instead of the default one. For IVR validations, language has priority in front of voice type (man or woman). See Supported voices and languages for IVR from Request Validation section for more details.
RESPONSE
Property Type Description
settings object Returns the validations methods in the order they need to be presented to the user. Each validation method contains the following properties: type - the validation type, max_attempts - how many times will repeat that validation type until goes to the next one, delay - how much time will wait for the method to complete.
country_code string Country prefix from where the destination number belongs.
country_iso_code string The country code from where the destination number belongs in ISO 3166-1 alpha-2 format.
carrier string The name of the carrier from where the destination number belongs.
is_mobile bool Indicates if destination number is mobile or not.
e164_format string The destination number in E.164 format including + sign.
formatting string The destination number formatted in E.164 format.

Note

For sms type the API returns 2 additional properties:

  • sms_template - The message template that will be delivered (as defined in the website portal).
  • android_app_hash - This property is sent only in case it's defined into the Remote Config Profile on the web portal and platform is android. This should be used in the Request Validation API to populate the android_app_hash property.
REQUEST
RESPONSE

# SMS API

CheckMobi SMS API is a simple REST interface for sending SMS messages to over 200 countries across the globe.

# Send SMS

This API enables you to send SMS via CheckMobi SMS service. The API supports Unicode UTF-8 encoded texts, so you can send messages in any language. It also handles long SMS automatically by splitting it into standard SMS sized chunks and sending them.

LONG SMS SUPPORT

A standard SMS contains at most 160 bytes. However, most mobile devices are displaying longer messages. The API supports sending long SMS to supported carriers and devices.

UNICODE OR MULTILINGUAL SMS

CheckMobi API supports sending SMS in languages other than English by encoding them in Unicode UTF-8. A single SMS can contain only up to 70 Unicode characters. SMS more than 70 Unicode characters, is automatically split as a long SMS.

TRANSACTIONAL AND PROMOTIONAL CONTENT

Make sure you set the proper value for is_transactional parameter based on your content. It is strictly prohibited to exploit transactional SMS for promotional/marketing use cases. Marketing messages and promotional SMS campaigns are not considered transactional SMS content.

Promotional dedicated routes for certain destinations can have different rates than the Standard pricing plan (usually lower). Make sure you are checking the pricing page..

REQUEST
  • Resource: /sms/send
  • Method: POST
  • Authentication: Authorization header
  • Content-Type: application/json
  • Success code: 200
  • This resource accepts also X-Client-IP HTTP header for properly tracking the End Customer IP when you are using a server-server integration.
PARAMETERS
Property Type Required Description
from string Optional. The name or number that is displayed as the sender of the SMS message to the receiver of the SMS message. This can be either alphanumeric (for example, CHKMOB) or numeric (for example, a mobile phone number). Sender IDs identify your business and help your customers recognize and recall your brand. This property overrides the value from your application settings. In case you don't send your custom sender id and you don't have one set into the application settings, the platform will use the best option that will make sure the messages are not filtered by operators because sender id doesn't met the legal requirements in that country/network.
to string ✓ The destination number in E.164 format.
text string ✓ The message that needs to be delivered.
is_transactional boolean Optional, default to true. Indicates if the message is transactional or promotional. Please check the Transactional and Promotional content section above for more details.
notification_callback string Set this parameter to the fully qualified URL where to receive in real time notifications with the delivery reports. Please see the Notifications section below.
platform string One of the following values: ios, android, web, desktop. We strongly recommend using this property for better analytics.
NOTIFICATIONS

If you specify the notification_callback parameter, when the sms state is updated we are sending a HTTP request using POST method to this URL.

You need to respond back with HTTP status 200 OK. We will retry to send the request maximum 3 times in case of another status code is received.

The request body is JSON encoded containing the following properties:

Property Type Description
id string Message Unique identifier.
to string The destination number in E.164 format where the message was delivered.
description string A short description about carrier and country: for example: FR - Orange.
status string The delivery status. One of the following values: queued, sent, failed, delivered, undelivered, rejected.
charged_amount float Sent only when is available. Total charge for sending the SMS (units*charged_rate).
charged_rate float Sent only when is available. This is the charge applicable per outbound SMS unit.
units integer Sent only when is available. Number of units into which a long SMS was split.

Note

In case you want to make sure that the notification is not triggered from an untrusted source you can use the X-CheckMobi-Signature header as described here.

RESPONSE
Property Type Description
id string Message Unique identifier.
number_info.country_code string Country prefix from where the destination number belongs.
number_info.country_iso_code string The country code from where the destination number belongs in ISO 3166-1 alpha-2 (opens new window) format.
number_info.carrier string The name of the carrier from where the destination number belongs.
number_info.is_mobile bool Indicates if destination number is mobile or not.
number_info.e164_format string The destination number in E.164 format (opens new window) including + sign.
number_info.formatting string The destination number formatted in E.164 format (opens new window).
REQUEST
RESPONSE

# Retrieve a message

This resource retrieves a Message Detail Record (MDR).

REQUEST
RESPONSE
Property Type Description
to string The destination number.
request_date integer The date time as UNIX timestamp when the request was sent.
description string A short description about carrier and country: for example: FR - Orange.
status string The delivery status. One of the following values: queued, sent, failed, delivered, undelivered, rejected.
charged_amount float Sent only when is available. Total charge for sending the SMS (units*charged_rate).
charged_rate float Sent only when is available. This is the charge applicable per outbound SMS unit.
units integer Sent only when is available. Number of units into which a long SMS was split.
REQUEST
RESPONSE

# Voice API

CheckMobi Voice API is a simple REST interface for managing outbound calls to over 200 countries across the globe.

# Place Call

This resource allows you to initiate an outbound call to a PSTN number. The API supports Unicode UTF-8 encoded texts to be played in different languages.

REQUEST
  • Resource: /call
  • Method: POST
  • Authentication: Authorization header
  • Content-Type: application/json
  • Success code: 200
  • This resource accepts also X-Client-IP HTTP header for properly tracking the End Customer IP when you are using a server-server integration.
PARAMETERS
Property Type Required Description
from string The source number in E.164 format. If missing a CheckMobi number randomly picked will be used.
to string ✓ The destination number in E.164 format.
ring_timeout integer Maximum number of seconds the call can ring. Integer value between 1 and 120.
notification_callback string Set this parameter to the fully qualified URL where to receive in real time notifications with the call status (ringing, hangup, answered). Please see the Notifications section below.
platform string One of the following values: ios, android, web, desktop. We strongly recommend using this property for better analytics.
events array ✓ The events that need to be performed during the call flow. Please see the above section Available call actions for more details.

ring_timeout is an approximate duration. Because of the way VoIP is designed to work is not possible to implement an accurate maximum duration for ringing. Be caution that lower values can close the call before even start ringing on devices. We don't recommend to use values lower than 10 seconds.

NOTIFICATIONS

If you specify the notification_callback parameter, when the call state is updated we are sending a HTTP request using POST method to this URL.

You need to respond back with HTTP status 200 OK. We will retry to send the request maximum 3 times in case of another status code is received.

The request body is JSON encoded containing the following properties:

Property Type Description
id string Call Unique identifier.
from string The number used as caller id in E.164 format.
to string The destination number in E.164 format where the call was placed.
description string A short description about carrier and country: for example: FR - Orange.
event string The call status. One of the following values: ringing, answer, hangup.
charged_amount float Sent only when is available. Total charge for placing the call based on duration_billed and charged_rate.
charged_rate float Sent only when is available. This is the charge applicable per minute.
duration_billed integer Sent only when is available. Number of seconds billed.

Note

In case you want to make sure that the notification is not triggered from an untrusted source you can use the X-CheckMobi-Signature header as described here.

AVAILABLE CALL ACTIONS

The events should be provided into json format as an array with multiple objects which will be executed into the provided order.

# Speak element

The Speak element is used to read out text as speech to the caller. The text should be provided in UTF-8. The attributes supported by the Speak element are listed below. The default behavior of each attribute can be modified using the allowed values.

Attribute Type Mandatory Description
action string ✓ The unique identifier for the Speak element. Always equal with speak.
text string ✓ The text used as speech to the caller. Any UTF-8 encoded text supported.
loop integer >= 0 Specifies number of times to speak out the text. If value set to 0, speaks indefinitely. Allowed values - integer >= 0 (0 indicates a continuous loop). Defaults to 1.
voice string The tone to be used for reading out the text. Allowed values - WOMAN, MAN. Defaults to WOMAN.
language string Language used to read out the text. See Supported voices and languages for IVR section from here. Defaults to en-US.

# Play element

The Play element is used to play an audio file to the caller. The audio file is obtained from a remote URL(mp3 or wav file formats).

Attribute Type Mandatory Description
action string ✓ The unique identifier for the Play element. Always equal with play.
url string ✓ The url of the file that needs to be played. Any valid url to a mp3 or wav file format is supported.
loop integer >= 0 Specifies number of times the file will be played in loop. If value set to 0, play indefinitely. Allowed values - integer >= 0 (0 indicates a continuous loop). Defaults to 1.

# Send DTMF

This element is used to send digits on a call. This is usually used to automate the process of navigating through an IVR. Digits are sent in the background when the async parameter is set to true, so the call will jump to the next action element when the first digit is sent.

Attribute Type Mandatory Description
action string ✓ The unique identifier for the DTMF element. Always equal with send_dtmf.
digits string ✓ The digits that has to be sent as DTMF. Use the character w for a 0.5 second delay and the character W for a 1 second delay. Allowed values: 1234567890*#wW.
async boolean Proceed to next element after the first digit is sent. Defaults to true.

# Wait element

The Wait element waits silently for a specified number of seconds.

Attribute Type Mandatory Description
action string ✓ The unique identifier for the Wait element. Always equal with wait.
length integer >= 0 Time to wait in seconds. Allowed values - integer greater than 0. Defaults to 1.

# Hangup element

The Hangup element is used to end a call.

Attribute Type Mandatory Description
action string ✓ The unique identifier for the Hangup element. Always equal with hangup.
reason string Used to specify reason of hangup. Allowed values - rejected, busy. No default value.
schedule integer > 0 Used to schedule a call hangup. Should be followed by an element such as Speak, otherwise the call will be hung up immediately. Allowed values - integer > 0 (in seconds). No default value.
RESPONSE
Property Type Description
id string Call Unique identifier.
number_info.country_code string Country prefix from where the destination number belongs.
number_info.country_iso_code string The country code from where the destination number belongs in ISO 3166-1 alpha-2 (opens new window) format.
number_info.carrier string The name of the carrier from where the destination number belongs.
number_info.is_mobile bool Indicates if destination number is mobile or not.
number_info.e164_format string The destination number in E.164 format (opens new window) including + sign.
number_info.formatting string The destination number formatted in E.164 format (opens new window).
REQUEST
RESPONSE

# Retrieve a call

This resource retrieves a Call Detail Record (CDR).

REQUEST
RESPONSE
Property Type Description
to string The destination number.
request_date integer The date time as UNIX timestamp when the request was sent.
description string A short description about carrier and country: for example: FR - Orange.
charged_amount float Sent only when is available. Total charge for placing the call based on duration_billed and charged_rate.
charged_rate float Sent only when is available. This is the charge applicable per minute.
duration_billed integer Sent only when is available. Number of seconds billed.
REQUEST
RESPONSE

# Hangup a call

This resource enables you to hangup a call placed via CheckMobi APIs Place call or Request Validation (when using ivr or reverse_cli validation types).

REQUEST
REQUEST

# Lookup API

Lookup API enables you to validate or perform an HLR lookup or MNP lookup for a mobile phone number.

A phone number validation is free of charge and will tell you if the specified phone number looks valid. It will also include 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 is possible).

A MNP Lookup (implies additional charges) serve as a cost-efficient alternative to HLR lookup queries when the main objective is to retrieve the current MCCMNC of a specific mobile phone number accurately.

Mobile Number Portability (MNP) refers to a collection of technologies and protocols that allow mobile phone users to retain their phone number when changing service providers.

While MNP brings positive news for phone users, it poses challenges in terms of cost and complexity for various entities such as telecoms, SMS aggregators, and many others. These businesses heavily rely on accurate identification of the mobile network operator (MNO) associated with a subscriber's phone number for purposes like least-cost routing and ensuring correct SMS or voice termination.

As MNP becomes increasingly prevalent in numerous countries worldwide, it is no longer possible to determine the network identifier (MCCMNC) simply by examining a phone number and cross-referencing it with a numbering plan. To overcome this obstacle, our MNP Lookups service offers an effective solution.

An HLR lookup (implies additional charges) is a more accurate method that queries the mobile networks in order to retrieve which mobile number belongs to what operator in real time and see whether the number is active or not. Also will provide information regarding the portability (current network and issuing network). Using HLR lookup you will be able to keep your database clean by removing all inactive and fake numbers and communicating with your customer in a proper way.

MNP and HLR Lookup is relevant only for mobile numbers. In case you are trying to perform an HLR/MNP Lookup on a landline number the request will fall back to the Validation API and no charge will be applied. The exception makes the North American Number where in order to detect if a number is mobile or not you need to perform the Lookup.

# Validate a phone number

This resource allows you to validate a phone number. A phone number validation is free of charge and will tell you if the specified phone number looks valid. It will also include some alternative formats to display the phone number in, the timezone where number might belong and information regarding the country, area and operator where the number was originally issued (where is possible).

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

# Perform an HLR Lookup

An HLR lookup allows you to view which mobile number belongs to what operator in real-time and see whether the number is active or not. Also will provide information regarding the portability (current network and issuing network). Using HLR lookup you will be able to keep your database clean by removing all inactive and fake numbers and communicating with your customer in a proper way.

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 API 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 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 will be pushed to the specified URL via POST method. Your callback needs to respond back with HTTP status 200 OK. Our service will retry to send the request maximum 3 times in case of another status code is received.

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

# Perform a MNP Lookup

Provides a cost-efficient alternative to HLR lookup queries when the main objective is to retrieve the current MCCMNC of a specific mobile phone number accurately.

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 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 will be pushed to the specified URL via POST method. Your callback needs to respond back with HTTP status 200 OK. Our service will retry to send the request maximum 3 times in case of another status code is received.

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

# Miscellaneous

# Check Number

This resource allows you to receive information about a provided phone number into E.164 format (opens new window) and the supported validation methods for that number.

REQUEST
  • Resource: /checknumber
  • Method: POST
  • Authentication: Authorization header
  • Content-Type: application/json
  • Success code: 200
PARAMETERS
Property Type Required Description
number string ✓ The number that has to be checked in E.164 format (opens new window).
RESPONSE
Property Type Description
country_code string Country prefix from where the number belongs.
country_iso_code string The country code from where the number belongs in ISO 3166-1 alpha-2 format.
carrier string The name of the carrier from where the number belongs.
is_mobile bool Indicates if number is mobile or not.
e164_format string The number in E.164 format including + sign.
formatting string The number formatted in E.164 format.
validation_methods array Provide information about the validation methods available for a certain destination. In case of a CLI validation local_number is true in case CheckMobi support local number for that region otherwise the user needs to be able to call international numbers. In case of a Reverse CLI validation (missed call) the min_ratemax_rate and estimation_cost apply only in case the user insert a wrong number and the callee is fast enough to answer the call before CheckMobi closing it. Typical we are ringing maximum 2-3 seconds. In case the user is not answering the call you are not charged.
REQUEST
RESPONSE

# Get available countries

This resource enables you to get a list of all available countries, flags and country codes.

REQUEST
RESPONSE

A list of items. Each item will have the following properties:

Property Type Description
iso2 string Country ISO code 2 digits.
name string Country name.
prefix string Country calling code.
flag_32 string URL to the flag location. Size 32x32 pixels.
flag_128 string URL to the flag location. Size 128x128 pixels.
REQUEST
RESPONSE

# Get available prefixes

This resource enables you to get a list of all available countries and the associated calling prefixes.

REQUEST
RESPONSE

A list of items. Each item will have the following properties:

Property Type Description
iso2 string Country ISO code 2 digits.
name string Country name.
prefix integer Calling prefix for that country.
REQUEST
RESPONSE