API Integration

Introduction

At the end of this article, you will be able to configure API requests to the PBX. This feature is currently in Beta and only available to customers that have requested Beta features be activated on their account. Please note, API calls are limited to 100 queries per 15 minutes. Should you need any assistance, feel free to contact our support department.

Obtain API Key for your account
Whitelist IP address(es)
[GET] /api/integration/v1/get-user-calls
[GET] /api/integration/v1/get-queue-calls
[GET] /api/integration/v1/get-ringgroup-calls
[POST] /api/integration/v1/call-to-number
[GET] /api/integration/v1/get-system-status
Codes

Obtain API Key for your account

To make an API request, you will need the API key for your account. This can be found in the Billing tab in the customer portal in the customer details. Click the Edit details button and you will be able to copy the key to then paste into your API parameters.

Note: From 4/12/2020 we are moving the API key from a parameter to a HTTP Headers for additional security. The Header name is token and the value for this header should be the key copied above.

Whitelist IP address(es)

You will need to add the IP address(es) to the whitelist to allow access to make API requests to your PBX. If you attempt to send an API request from an IP, not in the Whitelist, you will get the following response.

To add an IP to the whitelist, from the PBX tab, click on Settings, then the Integrations tab, select API on the left menu and scroll down to the Whitelisted IPs section. Click the Add IP button.

Add the IP address(es) you require to have access to make API requests to your PBX. Each IP address should be added on its own line. Click the Add button once done.

Click Save on the Settings window, and then apply the configuration. You can now start to send API requests as detailed below.

[GET] /api/integration/v1/get-user-calls

This request will retrieve a list of calls for the user(s) specified. Calls will be sorted from newest to oldest.

Headers:

Header Name: token - required Value should be your API Key.

Parameters:

(string) api_key - required This method of authentication will be deprecated on 4/12/2020
(string) from_date - optional (default: '' - any time), in the format Y-m-d
(string) to_date - optional (default: '' - any time), in the format Y-m-d
(int) limit - optional (default: 100), the limit value should be in the range from 1 to 10000
(int) offset - optional (default: 0), element number to get data from
(string) users_names - optional (default: '' - all users), a comma-separated list of users names

Response Data:

(string) from_number - number of caller
(string) to_number - number the call was received on
(string) user_name - name of User object who answered the call
(int) is_inbound - is the call inbound or not
(string) call_start_at - date and time when the call was started, in the format ISO 8601
(int) call_duration - call duration is seconds
(string|null) call_finished_at - null or date and time when the call was finished, in the format ISO 8601
(int) conversation_duration - conversation duration is seconds

[GET] /api/integration/v1/get-queue-calls

This request will retrieve a list of calls to queues. Calls will be sorted from newest to oldest.

Parameters:

(string) api_key - required
(string) from_date - optional (default: '' - any time), in the format Y-m-d
(string) to_date - optional (default: '' - any time), in the format Y-m-d
(int) limit - optional (default: 100), the limit value should be in the range from 1 to 10000
(int) offset - optional (default: 0), element number to get data from
(string) queues_names - optional (default: '' - all users), a comma-separated list of queue names

Response Data:

(string) queue_name - name of Queue object
(string) callerid - number of caller
(string) inbound_number - number the call was received on
(string) call_start_at - date and time when the call was started, in the format ISO 8601
(string|null) call_answered_at - null or date and time when the call was finished, in the format ISO 8601
(string) call_finished_at - date and time when the call was finished, in the format ISO 8601
(string) answered_by_user_name - name of User object who answered the call if exists
(string) status - status of the call (answered|abandoned|timedout)

[GET] /api/integration/v1/get-ringgroup-calls

This request will retrieve a list of calls to Ring-groups. Calls will be sorted from newest to oldest.

Parameters:

(string) api_key - required
(string) from_date - optional (default: '' - any time), in the format Y-m-d
(string) to_date - optional (default: '' - any time), in the format Y-m-d
(int) limit - optional (default: 100), the limit value should be in the range from 1 to 10000
(int) offset - optional (default: 0), element number to get data from
(string) ringgroups_names - optional (default: '' - all users), a comma-separated list of ring group names

Response Data:

(string) ring_group_name - name of Ring Group object
(string) callerid - number of caller
(string) inbound_number - number the call was received on
(string) call_start_at - date and time when the call was started, in the format ISO 8601
(string|null) call_answered_at - null or date and time when the call was finished, in the format ISO 8601
(string) call_finished_at - date and time when the call was finished, in the format ISO 8601
(string) answered_by_user_name - name of User object who answered the call if exists
(string) status - status of the call (answered|abandoned|timedout)