Overview

The configuration application programming interface provides a phone system API. You can programmatically configure the PBX to make changes to callflows, voicemail, IVRs etc. Additionally you can interact with phone calls and receive telephony events via this API.

 

Meaning

Not all methods are applicable for all requests, please consult the API documentation for details.

  • GET - Retrieves either a collection of resources or a single resource
  • POST - Updates a resource by completely replacing it with the provided data
  • PUT - Creates a new resource with the provided data
  • DELETE - Deletes a resource

 

Method Overloading

If your client can not support the necessary HTTP methods (verbs) to interface with the REST API you can provide the necessary action (PUT and DELETE) in a POST. To override the typical behaviour of such verbs, provide a request body parameter called 'verb' with the required method (a query string parameter can be used too).

  

Example:
POST https://c-api.conversanthq.com/v1/accounts/ef7c445e-ff15-11df-8083-43f718c1973c?verb=DELETE

The verb parameter can also be provided in the API envelope during POST requests. If the the first occurrence of verb (in order of precedence) is found invalid then processing will terminate.

The order of precedence when both are present is as follows:

  1. API envelope 'verb' parameter, in the HTTP content of the request
  2. HTTP query parameter called 'verb', ie: /accounts?verb=PUT

Base URL

https://c-api.conversanthq.com/v1

  

Specifying the Account

Following the base URL most requests will then specify the account that they should operate on.

https://c-api.conversanthq.com/v1/accounts/{account_id}

accounts, This specifies the accounts module, and is the base module for all requests except for authorisation.

{account_id}, In a request this should be replaced with the complete account_id that the request should be applied to. A typical account id would look like: '04152ed2b428922e99ac66f3a71b0215'

 

Making Request

Typically requests will be made to modules within the account, for example devices. This is done by appending the URL with the module name followed by any resource identifiers.

https://c-api.conversanthq.com/v1/accounts/{account_id}/servers/
https://c-api.conversanthq.com/v1/accounts/{account_id}/servers/{server_id}
https://c-api.conversanthq.com/v1/accounts/{account_id}/servers/{server_id}/deploy

servers, This specifies the server module within the account identified by {account_id}. If nothing follows it then it refers to all servers within the account.

{server_id}, In a request this indicates that the request pertains to a specific server. A typical server id would look like: 'b2e58f9815e3db4bcc6bf46afee4738b'

deploy, This is a module specific resource component that indicates the request pertains to a parameter of a specific server. Not all modules expose additional access to resources such as this nor are they all the same, see the API documentation for details.

When sending requests via PUT or POST the following envelope is expected:
NameOptionalDescription

auth_token

yes

Used to provide the auth token when required, and not present in another mechanism

verb

yes

Used to override the HTTP method

data

no

The request data, provided to the resource

In the event that a parameter is provided in both the request body envelope and the URL query parameters, the request body will be used.

 

When receiving responses the following envelope parameters are provided for the client:
NameOptionalDescription

auth_token

yes

The auth_token will be returned in any envelope if the client provided an authorisation token

status

no

The status of the request, valid values are 'success', 'fatal', and 'error'

error

yes

If an error has occurred this parameter will be the error code, valid values are any integer less than 1000

message

yes

If an error has occurred this parameter will be a description of the error

data

no

The response data, from the resource

The standard Content-Type header should be used to identify the format of the request body. If the content can not be properly parsed as JSON then the client will receive a 400 Bad Request.

Since some clients will not be able to influence the content type headers the following table indicates both the acceptable content types and the assumed format. In the event that a content type is specified other than JSON, the API will attempt to automatically determine the format.

Content-TypeFormat
text/plain Automatic Determination
text/html Automatic Determination
application/json JSON
application/x-json JSON

   

Response

The response format can be specified in requests using either the Accept header or by extension of the URL. Any extension specified in the URL takes precedence over the Accept header, and if neither is present then JSON is assumed.

Accept HeaderURL ExtensionFormatDefault
application/json or application/x-json .json JSON yes

      

JSONP

JSONP can be used when JSON is the response type, and a 'jsonp' parameter is in the query string or request body.

For example GET https://c-api.conversanthq.com/v1/accounts/\{account_id}?jsonp=yourJS will return:

"yourJS({'data': { 'accounts': [...]} });".

 

CORS

The API server is Cross-Origin Resource Sharing enabled enabled. This functionality lets JavaScript in the browser make requests to servers located in a different domain then the JavaScript was fetched from. This is typically forbidden within web browsers by the same origin policy. Modern browsers will all be CORS enabled as well requiring no changes to the JavaScript code.

Resources can be filtered based on the value or the range of some of its properties. You can accumulate filters on the same resource in order to refine your search.

https://c-api.conversanthq.com/v1/accounts/{account_id}/{resource}?{filter1}={value1}&{filter2}={value2}

  

Available filters

Some filters are prepended to the name of the property they act upon. For example, the call_id property filter name would be filter_call_id. Other filters are designed to be used as they are, like created_from.

FilterValueNotes
filter_{property} Property you are looking for
created_from timestamp (Gregorian seconds) Resource created from
created_to timestamp (Gregorian seconds) Resource created to
modified_from timestamp (Gregorian seconds) Resource modified from
modified_to timestamp (Gregorian seconds) Resource modified to

Authorisation Token

All requests to the Configuration API must contain a valid authorisation token, which can be located in a request dependent manner or as a HTTP header. Failure of the first located token will trigger authentication failure of the request.

For GET AND DELETE requests the order of precedent is as follows:

  1. HTTP X-Auth-Token header
  2. HTTP query parameter called 'auth_token', e.g.: https://c-api.conversanthq.com/v1/accounts/{account_id}?auth_token=123456

For PUT AND POST requests the order of precedent is as follows:

  1. HTTP 'X-Auth-Token' header
  2. Envelope 'auth_token' parameter, in the HTTP body of the request

   

Exceptions

The authenticate modules will allow you to retrieve an authorisation token using one of the available methods, such as by user credentials.

Some modules can be used without valid credentials, these modules are:

user_auth, This module validates user credential hashes (username and password), returning an authorisation token if valid.

https://c-api.conversanthq.com/nz/v1/user_auth

api_auth, This module validates an accounts api_key, returning an authorisation token if valid.

https://c-api.conversanthq.com/v1/api_auth