Overview

CheckMobi Voice API is a simple REST interface for placing and managing outbound calls to over 200 countries across the globe, with HD-quality, natural-sounding text-to-speech available in 16 languages listed below, with both male and female voice options — well suited for IVR flows, appointment reminders, urgent alerts, and voice-based two-factor authentication.

Every call benefits from Multiple Carrier Support, which keeps two independent routes available per destination so calls connect reliably worldwide, and from the same AI-powered AntiFraud protection that runs across the whole platform, at no extra cost. Because a voice call adds a layer of verification that's harder to bypass than SMS alone, it's also a strong option for higher-security use cases and for end users who prefer or need audio over text.

Pricing is transparent and scales with you, with no hidden fees — see the pricing page for rates by destination.

Languages and Voices

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	✓

Place Call

This resource lets you initiate an outbound call to a PSTN number and control the call flow with a sequence of actions — reading out UTF-8 encoded text-to-speech in any of the supported languages, playing an audio file, sending DTMF digits, waiting, and hanging up.

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 omitted, a CheckMobi number is randomly picked and 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 a fully qualified URL to receive real-time notifications about the call status (ringing, hangup, answered). See the Callback 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 dialplan events that need to be performed during the call flow. Please see Available Elements for more details.

ring_timeout is an approximate duration — the way VoIP works makes it impossible to guarantee an exact maximum ringing time. Be careful: lower values can end the call before it even starts ringing on some devices. We don't recommend using values below 10 seconds.

RESPONSE

Property	Type	Description
id	string	The call's 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

Callback Notifications

If you specify the notification_callback parameter, we send an HTTP POST request to this URL each time the call status changes.

Your endpoint must respond with HTTP status 200 OK. If any other status code is returned, we retry the request up to 3 times.

The request body is JSON encoded containing the following properties:

Property	Type	Description
id	string	The call's 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 available. Total charge for placing the call based on duration_billed and charged_rate.
charged_rate	float	Sent only when available. This is the charge applicable per minute.
duration_billed	integer	Sent only when 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.

RESPONSE

Retrieve a call

This resource retrieves a Call Detail Record (CDR).

REQUEST

• Resource: /call/{id}
• Method: GET
• Authentication: Authorization header
• Success code: 200

RESPONSE

Property	Type	Description
to	string	The destination number.
request_date	integer	The date and time as a 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 available. Total charge for placing the call based on duration_billed and charged_rate.
charged_rate	float	Sent only when available. This is the charge applicable per minute.
duration_billed	integer	Sent only when available. Number of seconds billed.

REQUEST

RESPONSE

Hangup a call

This resource lets you hang up a call placed via the Place Call API or Request Validation (when using ivr or reverse_cli validation types).

REQUEST

• Resource: /call/{id}
• Method: DELETE
• Authentication: Authorization header
• Success code: 204

REQUEST

Dialplan Overview

The CheckMobi JSON Dialplan provides a flexible, declarative interface for controlling the behavior and execution flow of outbound voice calls. By defining a sequence of JSON instructions, you can orchestrate call handling logic such as IVR interactions, playback, prompts, and other call-control operations.

Each instruction specifies an action to be performed by CheckMobi during the lifecycle of a call, allowing you to build dynamic and programmable voice workflows without implementing the underlying telephony logic yourself.

Available Elements

Speak element

The Speak element reads 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, each with its default behavior and 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 is supported.
loop	integer >= 0		Specifies the number of times to speak the text. If set to 0, it 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 the Supported voices and languages table above. Defaults to en-US.

EXAMPLE

Play element

The Play element plays an audio file to the caller. The audio file is fetched 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 to play. Any valid URL to an mp3 or wav file is supported.
loop	integer >= 0		Specifies the number of times the file will be played in a loop. If set to 0, it plays indefinitely. Allowed values - integer >= 0 (0 indicates a continuous loop). Defaults to 1.

EXAMPLE

Send DTMF

This element sends DTMF digits on a call, typically used to automate navigation through an IVR menu. When async is set to true, digits are sent in the background and the call moves on to the next action as soon as 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 have 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		Proceeds to the next element after the first digit is sent. Defaults to true.

EXAMPLE

Wait element

The Wait element pauses the call 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 >= 0. Defaults to 1.

EXAMPLE

Hangup element

The Hangup element ends the call.

Attribute	Type	Mandatory	Description
action	string	✓	The unique identifier for the Hangup element. Always equal with hangup.
reason	string		Specifies the reason for the hangup. Allowed values - rejected, busy. No default value.
schedule	integer > 0		Schedules the hangup to occur after the given delay. 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.

EXAMPLE