Skip to main content

Calls API

Tovie Platform provides the Calls API for working with outbound telephony.

Before starting your work with the Calls API, you need to:

  1. Configure telephony.
  2. Connect a telephone channel.
  3. Create a call campaign.

API methods

The API provides methods for the following operations:

  1. Adding phone numbers with parameters to the campaign.

    • POST /api/calls/campaign/{token}/addPhones
    • GET /api/crmCalls/campaign/{token}/addPhone
    • POST /api/crmCalls/campaign/{token}/addPhone
    • GET /api/crmCalls/campaign/{token}/test/addPhone
  2. Canceling previously created call jobs.

    • POST /api/calls/campaign/{token}/callJob/cancel
  3. Obtaining reports by call job ID or by phone number.

    • POST /api/calls/campaign/{token}/callJob/getReport
    • POST /api/calls/campaign/{token}/callAttempt/getReport
  4. Retrieving call campaign information.

    • GET /api/calls/campaign/{token}
    • GET /api/calls/campaign/{token}/status
  5. Pausing, resuming, and stopping the campaign.

    • POST /api/calls/campaign/{token}/control/pause
    • POST /api/calls/campaign/{token}/control/resume
    • POST /api/calls/campaign/{token}/control/stop

Request parameters

Required parameters

Requests to the Calls API must contain the following required parameters:

  • host_name is the host where the campaign is running.
  • token is a unique token for controlling the campaign.
You can obtain the token on the Outbound call campaigns tab by clicking either the  icon next to the campaign name or  > Copy API token.

For example, in the case of, the request URL for adding phone numbers to the campaign will look like this:

Idempotence key

In order to control the consistency of the created resources, client applications can generate and pass an idempotence key in their requests to the Calls API.

The idempotence key is a string passed along with the request which guarantees that several requests with the same idempotence key and the same content will return the same response.

If such requests contain no idempotence key or it is different between them, the requests are considered different and are not guaranteed to return equal results.

Passing the idempotence key

The GET method

For the GET /addPhone method, the idempotence is passed as an Idempotence-Key request parameter:

curl ''
POST methods

All the POST methods require passing the idempotence key in an Idempotence-Key request header:

curl --request POST '' \
--header 'Content-Type: application/json' \
--header 'Idempotence-Key: d5f41bd4' \
--data-raw '[
"phone": 16500000000

How to use

Passing the idempotency key in the request will help to avoid undesirable call duplicates in case of a technical error.

Suppose that a system failure caused a request to add a phone number to the campaign to be executed twice. The phone number and the data passed as payload were identical.

  • If the requests did not contain an idempotence key, the first created call job will be followed by a second with its ID distinct from the first, and they will both be put into the queue.
  • If the requests had an idempotence key, then a duplicate call job will not be created. The second request will return the ID of the same call job as the first request had created earlier.
Use different keys for call campaigns with the same numbers. This way you can add the same numbers to the different call campaigns and avoid call duplicates within one call campaign.


No restrictions are imposed on the key format: it may be an arbitrary string. However, using UUID is recommended so that keys are guaranteed to be unique.

The idempotence key applies to all projects and call campaigns on the account. To add the same phone numbers to the different call campaigns, you need to use different idempotence keys.

Idempotence keys expire 1 day after their first usage. After that period, requests with a key that was previously used can once again produce duplicates.