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
.
POST
requests require a Content-Type
header set to application/json
.All requests to CheckMobi API are authenticated using your secret key. Your CheckMobi secret key can be found in your account settings.
The secret key is passed to the API as value of an HTTP header called Authorization
.
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.
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).
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.
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. |
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. |
9 | Callback URL provided is invalid. |
10 | Invalid event payload. |
11 | Restricted account due to suspicious activity. |
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. |
All HTTP callbacks sent by CheckMobi (when you are using the notification_callback
parameter while triggering Validation Requests, SMS or Voice Messages) 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 the End Customer IP is needed inside of our IP based AntiFraud rules like:
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.
Perform actions related to your account such as getting account details.
Using this resource you can retrieve your account details like email, available credit, subscription expiration date, monthly usage, etc.
/my-account
GET
200
Property | Description |
---|---|
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 |
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. |
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. |
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 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:
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:
Tips
Implementation
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
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.
/validation/request
POST
application/json
200
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<#> {MESSAGE}\n {ANDROID_APP_HASH} in order to have the SMS Retriever API working. |
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.
We support all ISO-639-1 language codesSettings -> [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
.
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 | ✓ |
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 |
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 |
validation_info.formatting | string | The number formatted in E.164 format |
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.
/validation/verify
POST
application/json
200
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.
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. |
Using this resource you can get the last status of a validation request.
/validation/status/{id}
GET
200
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. |
This resource enables applications to get the Remote Config profile that is configured in the web portal for a specific destination.
/validation/remote-config
POST
application/json
200
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. |
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 |
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 |
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.CheckMobi SMS API is a simple REST interface for sending SMS messages to over 200 countries across the globe.
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.
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.
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.
/sms/send
POST
application/json
200
Property | Type | Required | Description |
---|---|---|---|
to | string | ✓ | The destination number in E.164 format |
text | string | ✓ | The message that needs to be delivered. |
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. |
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 |
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.
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). |
This resource retrieves a Message Detail Record (MDR).
/sms/{id}
GET
200
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. |
CheckMobi Voice API is a simple REST interface for managing outbound calls to over 200 countries across the globe.
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.
/call
POST
application/json
200
Property | Type | Required | Description |
---|---|---|---|
from | string | The source number in E.164 format | |
to | string | ✓ | The destination number in E.164 format |
text | string | ✓ | The message that needs to be delivered. |
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. |
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.
The events should be provided into json
format as an array with multiple objects which will be executed into the provided order.
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 . |
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 . |
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 . |
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 . |
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. |
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). |
This resource retrieves a Call Detail Record (CDR).
/call/{id}
GET
200
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. |
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).
/call/{id}
DELETE
204
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.
/checknumber
POST
application/json
200
Property | Type | Required | Description |
---|---|---|---|
number | string | ✓ | The number that has to be checked in E.164 format (opens new window). |
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 |
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 |
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. |
This resource enables you to get a list of all available countries, flags and country codes.
/countries
GET
200
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. |
This resource enables you to get a list of all available countries and the associated calling prefixes.
/prefixes
GET
200
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. |