Core API Concepts

These conventions apply to every endpoint of the PBX API. For your first request, see Getting Started with CommPeak APIs.

Authentication

Every request must be made over HTTPS and authenticated with your Portal API key in the Authorization header:

curl 'https://api.commpeak.com/pbx/acme/api/calls/limit/10' \
  -H "Authorization: $COMMPEAK_API_KEY"

The key needs Full access (all services). To create a key and restrict it to your servers' IP addresses, see Managing Portal API Keys.

Send the key as the raw header value, without a Bearer prefix.

Click2Call does not use your Portal API key. You call it on your own subdomain, and the Click2Call ID and the caller's IP address are checked against the setup's allowed IP list. See Click2Call Integrations Overview.

URL naming

The PBX API has two modules. The Core API runs through api.commpeak.com, and Click2Call runs on your own subdomain:

For the Core API, add the endpoint name in plural form to the base URL, for example https://api.commpeak.com/pbx/acme/api/calls. To get one item, add its ID: https://api.commpeak.com/pbx/acme/api/calls/{id}. Replace acme with your company subdomain.

Content-Type

Send Content-Type: application/json with POST, PUT, and DELETE requests, and pass GET parameters in the URL. Text uses UTF-8 encoding.

Field selector

When you retrieve a list of objects, you can choose which fields each object includes. Add fields to the path, followed by the field names separated by ;. For example, /api/campaigns/fields/id;name returns only the ID and name of each campaign. Most endpoints support this.

Pagination

Limit the number of objects a GET request returns by adding limit to the path. For example, /api/calls/limit/10 returns the first 10 calls. To skip objects, add an offset after a semicolon: /api/calls/limit/50;0 returns the first 50 calls, and /api/calls/limit/50;50 returns the next 50. The maximum limit is 500.

For example, to get the 10 calls in positions 40–49:

curl 'https://api.commpeak.com/pbx/acme/api/calls/limit/10;40' \
  -H "Authorization: $COMMPEAK_API_KEY"

When a response returns fewer objects than the limit, you have reached the last page.

Ordering

Sort the results of a GET request by adding order to the path, for example /api/campaigns/order/name. You can sort by any field in the result, in ascending (name;asc) or descending (name;desc) order.

Filtering

Filter results by adding a field name and value to the path. To compare instead of matching exactly, add an operator after a semicolon: /api/campaigns/id/5;< returns all campaigns with an ID lower than 5.

You can use these operators: =, <, >, <=, >=, and like, which accepts MySQL LIKE syntax.

To combine several conditions on the same field, separate them with a pipe (|). For example, /api/campaigns/id/5;<|10;> returns campaigns with an ID lower than 5 or higher than 10.

Date format

All dates and times use ISO 8601 format, for example 2021-01-24 08:25:59 or 2021-01-24T08:25:59.

Rate limitation

Requests through api.commpeak.com are limited to about 10 per second, and requests over the limit return 429 (Too Many Requests). To stay within the limit, use endpoints that retrieve or update multiple records in one request. For the limits of every CommPeak API, see Rate limits.

HTTP status codes

For the status codes every CommPeak API returns, and fixes for the most common errors, see Handling errors and Troubleshooting your first request.