API Conventions

Our REST API follows the traditional API conventions used by most RESTful APIs.

HTTP Request Types

  • GET – query either a single or multiple objects
  • POST – create a new object
  • PUT – update a existing object
  • PATCH – partially update a existing object
  • DELETE – delete a object

URLs & Silos

Call Tools platform is a horizontally scaled out platform that utilizes multiple silos each with its own sub domain of calltools.io. If working with a single client simply get the silo domain from them or login as them to see the sub domain in use.

If developing a general use integration then you may use the following API endpoint without authentication to query all currently live silo sub domains for your authentication form:

https://app.calltools.io/api/silos/

Trailing backslash will typically be needed in the URL ie. api/contacts/

Data & Time Formats

Dates must be formatted as YYYY-MM-DD and datetimes must be formatted as YYYY-MM-DD HH:MM:SS. Dates and times are always in UTC, except for user entered dates and times in custom contact fields. User entered dates are regarded as naive/local, meaning they are not timezone aware.

Time Zones

All system datetime fields are UTC across the API. Dates and times are always in UTC, except for user entered dates and times in custom contact fields. User entered dates are regarded as naive/local, meaning they are not timezone aware.

Most of the Olson Tz Database timezones are support. See Pyst timezone list.

SSL

SSL is required for all HTTPS requests.

Data Format

JSON format is used for request body data.

Multipart Form Data is used when sending or receiving files over the REST API.

Filtering Results

URL query params are used for filtering results ie. GET /api/contacts/?first_name=bob

Paging Results

All API endpoints utilize paging of results when a multiple object GET request is received. The current default is 25 results per page with a default max page size of 250 results.

Some API endpoints have a higher max where needed.

Example URL query params for paging:

/api/contacts/?page=1&page_size=25
/api/contacts/?page=1&page_size=max

Authentication

API authentication is done using API keys which can be obtained in the Call Tools web interface. API authentication is done by API Key passed in the HTTP request headers as follows:

“Authorization”: “Token {INSERT YOUR TOKEN}”

We also offer JWT authentication for app developers.

More on Authentication

Authorization (Permissions)

Each API key is associated with a specific user and will assume the same application permissions (authorization) as that user.

Each user can only have 1 API key associated with them.

Attempting to access a permission protected API endpoint that you lack the permissions for will return a 403 forbidden status code.

Rate Limits

The generate rate limit for the REST API is 1000 requests per hour.

Bulk Delete

Caution: submitting a bulk delete HTTP DELETE request without any filtering in place will delete all objects on that endpoint.

Bulk delete is offered on a few select API endpoints such as the Contacts and CallerIDs API. Apply filters using query params like you would for a GET request but submit it with as a DELETE to the bulk delete API endpoint to delete objects in bulk.

Response Codes & Error Codes

500 or 5xx error – a server error has occurred on our end and we’ve been notified. Please try again later.

400 or 4xx error – there is a problem with your HTTP request. Any details about the problem will be included in the response body.
403 – you lack the permissions to access this API endpoint
200 or 2xx response code – request was successful
204 – delete was successful

Synchronous & Asynchronous API

Most of our API endpoints are synchronous API endpoints. This means the task is completed before the API response is sent back to you.

A handful of APIs may sometimes process a slower task behind the scenes and respond to you immediately to prevent timeout errors.

Several of the bulk delete APIs will do this on larger requests. If you issue a bulk delete request and get a 200, 201, or 202 status code response then a task has been queued to execute asynchronously. Deletes that return a 204 status code “no content” mean the delete was completed synchronously.

Ordering

Order of data ascending or descending is done with a query param.

Ordering by Primary Key Ascending

/api/calls/?ordering=pk

Ordering by Primary Key Ascending

/api/calls/?ordering=-pk

Not all fields are orderable. By default the primary key field will enabled for ordering. Order by primary key descending will give you the newest items first.

Bulk Delete

Caution: Submitting a bulk delete HTTP DELETE request without any filtering in place will delete all objects on that endpoint.

Bulk delete is offered on a few select API endpoints such as the Contacts and CallerIDs API. Apply filters using query params like you would for a GET request but submit it with as a DELETE to the bulk delete API endpoint to delete objects in bulk.