Core API Concepts

Authentication

All requests to our API need authentication and must be made over SSL (HTTPS, not HTTP).
We serve our API over HTTPS to secure your requests to our servers and use Digest / Basic Authentication for each request.

📘

How to find the API user?

• For module Core API: you can obtain API credentials by visiting API Management
• For module Click2Call: you can obtain API credentials by visiting Click2Call Integrations
• For module Webhook: you can obtain API credentials by visiting Dispatch Automation

For Basic Authentication, there is no need to generate credentials:

• Choose a username (e.g., "apiuser") and get an automatic strong password (e.g., "s3cur3P@ssw0rd!")
• Combine the username and password with a colon: apiuser:s3cur3P@ssw0rd!
• Encode this string in Base64
• Prepend "Basic " to the encoded string
• Add this to the Authorization header in your request

curl --location 'https://example.td.commpeak.com/api/calls/' \
--header 'Authorization: Basic YXBpdXNlcjpzM2N1cjNQQHNzdzByZCE='

Note: The Base64 encoded string YXBpdXNlcjpzM2N1cjNQQHNzdzByZCE= is the encoded form of apiuser:s3cur3P@ssw0rd!

Digest Authentication is more complex and secure than Basic Auth. Here's a simplified example:

 curl --location 'https://example.td.commpeak.com/api/calls/' \
  --digest -u apiuser:s3cur3P@ssw0rd!

In practice, Digest Auth involves:

• The client requests a protected resource
• The server responds with a 401 and provides a nonce
• The client sends a new request with a hashed response, including the nonce.

cURL handles these steps automatically when you use the --digest flag.

⚠️

Keep in mind that an API token is tied to a specific user on your account and gives access to all accounts' data.

If you change the API user credentials, including IP ACL list, all existing integrations using this API user will not be able to make successful requests against our API and will stop working.

URL naming

Our API uses a straightforward URL naming convention.
We have 3 API modules:

Each request must be made to the API endpoint https://{COMPANY_SUBDOMAIN}.td.commpeak.com/api/ followed by the endpoint type name in a plural form.
for example: https://{COMPANY_SUBDOMAIN}.td.commpeak.com/api/calls

When one item is being asked, and such a method exists, the ID of the item must be appended to the URL. for example https://{COMPANY_SUBDOMAIN}.td.commpeak.com/api/calls/{id}

Content-Type

We require using JSON body format when performing API POST PUT DELETE requests. To do a proper JSON-formatted request, ensure you provide Content-Type: application/json in HTTP request headers.
We require using query string body format when performing API GET requests.

Our API supports UTF-8 for character encoding.

Our API uses the HTTP verbs for each action:

Field selector

When asking for a collection/list of objects, you can pass in a field selector to indicate which fields you want to fetch per each object. Most endpoints in our API support this. fields param and the next field names are separated by ; will be included in the response.

For example, you can specify which fields should be returned in response by setting a field parameter like
/api/campaigns/fields/id;name. In this case, the response includes only the id and name for every object.

Pagination

Cursor-based endpoints accept the offset and limit query parameters. A cursor is a marker indicating the next page’s first item. You can control the number of entities returned per page by specifying the limit. The maximum limit value is 500.

Each GET request can limit response objects count by specifying limit parameters like /api/calls/limit/10 to get only the first 10 calls.
Additionally, the offset can be specified separated with a semicolon ; like 5;10 .
For fetching the first 50 calls result /api/calls/limit/50;0, and for the next 50 results /api/calls/limit/50;50.

Examples of fetching calls: We have 600 calls in the system
To get 10 calls in places 40 – 49, send the following:

curl --request GET \
     --url https://example.td.commpeak.com/api/calls/limit=10;40 \
     --header 'accept: application/json' \
     --header 'authorization: Basic dGVzdDoxMjM0NTY='

Another example is fetching all calls and returning 500 new items.

curl --request GET \
     --url https://example.td.commpeak.com/api/calls/limit=500;0 \
     --header 'accept: application/json' \
     --header 'authorization: Basic dGVzdDoxMjM0NTY='

The second request will only return 100 new items because the next item is from 500 to 999 - but there are only 600 calls. So there is no need to send another request because the last response returned results count < 500.

Ordering

Each GET request can have an order defined by setting order parameter like /api/campaigns/order/name.
Order can be applied to any field based on the result set. Ascending name;asc or Descending name;desc can be specified.

Filtering

The filter can be specified using other comparison operators in the following syntax: /api/campaigns/id/5;< this will select all campaigns whose ID is less than 5.

The following comparison operators can be used: =, <, >, <=, >=, like (as a search value, it accepts MySQL's like syntax).

The filter can be specified using a pipe | symbol to make different criteria for the same field like /api/campaigns/id/5;<|3;>this will select all campaigns whose ID is less than 5 or greater than 3.

Date format

All dates and times received by the API will be in ISO 8601 format 2021-01-24 08:25:59
(would be the same as 2021-01-24T08:25:59).

The times sent to the API should also be converted to the UTC timezone before being sent.

📘

Which timezone we support?

All times received or sent by the API should be only in UTC.

Rate limitation

Rate limiting of the API is considered company domain and not per user (token).
We allow 400 requests per minute per domain and IP address.

Exceeding this limit triggers a Cloudflare block.
Requests receive a 429 "Too Many Requests" error.

📘

Limit Exceeds?

Our API implements request limits to ensure fair usage and maintain system stability.
These limits are carefully calculated based on typical use cases and our API's capabilities. Adhering to these limits is crucial, and with our API's efficient design, you should rarely need to approach these limits.

According to that, must of GET endpoints support fetching multiple objects in a single request and must of POST PUT endpoints supported update multiple records in a single request.

HTTP status codes

Each response sent from the API contains a response code according to this list: