# Overview

CheckMobi provides REST APIs that can be integrated into virtually any application or backend using standard HTTP clients. This documentation covers API authentication, request and response formats, HTTP status and error codes, notification callbacks, and passing the end customer's IP address.

For plug-and-play 2FA integrations, you can also use our mobile SDKs:

The REST API can be integrated using any programming language with HTTP client support. We also provide open-source SDKs for selected platforms to simplify integration and allow you to customize the implementation to fit your requirements.

The API endpoint is:

https://api.checkmobi.com/{version}/

The current API version is v1.

  • All CheckMobi APIs are available over HTTPS only.
  • All POST requests must include the Content-Type: application/json header.

# API Requests

# Authentication

All requests to the CheckMobi API must be authenticated using your Secret Key. You can find your Secret Key in your application settings.

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

# Content Type

CheckMobi accepts request payloads in JSON format.

For POST requests, parameters must be provided as a JSON payload with the Content-Type header set to application/json.

For GET and DELETE requests, parameters must be provided in the URL query string.

# Phone Number Format

Phone numbers must be provided in E.164 format. The leading + is optional. If it is omitted, CheckMobi automatically adds it before processing the request.

For more information, see the E.164 standard (opens new window).

# API Responses

All CheckMobi API endpoints return responses in JSON format.

The HTTP status code indicates whether the request was successful or an error occurred.

# HTTP Status Codes

Status Description
200 Success. The request was processed successfully and the response contains JSON data.
204 Success. The request was processed successfully with no response content.
400 Bad Request. The request contains missing or invalid parameters. The response body provides additional details.
401 Unauthorized. The Secret Key is missing or invalid.
403 Forbidden. The Secret Key is valid but is not authorized to perform the requested operation.
404 Not Found. The requested resource could not be found.
500 Internal Server Error. An unexpected error occurred while processing the request. If the problem persists, contact CheckMobi Support.
503 Service Unavailable. The service is temporarily unavailable. If the problem persists, contact CheckMobi Support.
SUCCESS RESPONSE EXAMPLE

# Error Codes

For HTTP responses indicating an API error (400, 401, or 403), the response body includes an error code and description to help identify the cause of the failure.

Error Code Description
1 Invalid or expired API Secret Key.
2 Invalid phone number. The phone number must be provided in E.164 format.
3 Invalid Request ID.
4 Invalid validation type. Allowed values are sms, ivr, and reverse_cli.
5 Insufficient funds.
6 Insufficient Missed Call validation count.
7 Invalid request payload.
8 The requested validation method is not available for this destination.
10 Invalid event payload.
11 This operation is currently disabled for your account.
12 Your account has exceeded one or more configured limitations.
13 The destination is blocked due to application restrictions.
14 The number is temporarily blocked due to too many attempts.
15 Too many attempts to verify the PIN.
16 The validation request has expired.
17 Invalid lookup method.
18 No HLR lookup route is available for this destination.
19 This operation is not permitted when using a testing Secret Key.
ERROR RESPONSE EXAMPLE

# Notification Callbacks

CheckMobi can send HTTP callbacks to your application to notify you about events resulting from API operations.

Callbacks can be configured using the notification_callback parameter when creating:

# Callback Authentication

All callbacks sent by CheckMobi are signed using the Signature Key configured in your application's General tab.

The signature is provided in the X-CheckMobi-Signature HTTP header and is calculated using HMAC-SHA256 over the JSON request payload and your Signature Key.

You can use this signature to verify that callbacks received by your application were sent by CheckMobi and have not been tampered with.

# Callback Response

Your callback endpoint must return HTTP status 200 OK. If CheckMobi receives a different status code, the notification will be retried up to 3 times.

# Tracking the End Customer IP

Passing the end customer's IP address enables IP-based AntiFraud rules, including:

  • Allowing or blocking traffic from specific IP addresses.
  • Limiting the number of validation requests, SMS messages, or voice calls originating from an IP address within a defined time period.
  • Enabling our AI-based antifraud mechanisms to use IP intelligence and reputation signals as part of real-time traffic risk assessment, while helping protect your applications from fraudulent and abusive activity.

# Server-to-Server Integrations

In a server-to-server integration, API requests are sent to CheckMobi from your backend rather than directly from the customer's device. As a result, CheckMobi normally sees your server's IP address instead of the end customer's IP address.

To make our AntiFraud rules work correctly, pass the end customer's IP address in the X-Client-IP HTTP header.

The value should contain the customer's public IP address as a string.

EXAMPLES