Calltracking API

1 Introduction

Axialys provides three call tracking services :

  1. a static system, where numbers are configured once for all, and calls are routed according to desired configuration
  2. a fully dynamic system where our system gets routing information from your system on every inbound call
  3. a hybrid system, where Axialys manages a pool of numbers which are setup on-demand for a limited timespan, usually when they are displayed on a web page.

This document currently details the API for the third system below. Other APIs should be requested to your Axialys representative.

2 Static call tracking

This API is currently not available online, and can be obtained from your Axialys representative.

3 Dynamic call tracking/routing

This API is currently not available online, and can be obtained from your Axialys representative.

4 Hybrid dynamic call tracking

4.1 Principles

This service is designed so that you can display on your website (or other medium, like a mobile app) Axialys-provided numbers that are temporarily routed towards a specific destination.

Typical use cases include :

  1. call tracking connecting web site visits to phone calls
  2. call tracking a large number of end users with a small number of tracking numbers (typically much cheaper than setting up one number per end user)
  3. monetization of phone contacts, by displaying special cost numbers instead of regular numbers

In order to use this service & API, you will need your account to be set up with an appropriate inventory of numbers matching your requirements in terms of type of number, which are defined by their prefix (for instance 3389 for french VAS numbers) and their cost for end user, when applicable. Please contact your Axialys representative for that purpose.

Once your account is set up, the API offers the following features :

  1. setting up a new number : number
  2. getting your inventory status : inventory
  3. getting CDRs (Call Detail Records) for your traffic : cdrs

4.2 API basics

API calls are performed over HTTPS exclusively.

The base URL is : https://api.axialys.com/dynacall/<function>

Every API call requires an authentication; Axialys supports Basic HTTP Auth over HTTPS according to RFC 2617.

This authentication scheme requires the client to store its credentials. Great care should be taken by client software so that no credential leak/theft may occur. This is particularly important in case of mobile-app API usage

The following general rules apply :

  • functions must be called with GET HTTP method, unless stated otherwise
  • parameters can be passed a a query string for GET requests and in request body for POST requests
  • responses are provided in JSON format, unless stated otherwise. When an error occurs, the JSON response will include at least two fields : _err_code which is a 32 chars max alphanum code and err_msg which is human readable
  • when applicable, non US ASCII data must be UTF-8 encoded (and will be in responses)

4.3 API details

4.3.1 number

Request

This function allocates a new number from the pool of available numbers. The number is chosen according to its characteristics, and may be set up with various options.

https://api.axialys.com/dynacall/number
Parameters Mandatory Syntax Meaning
dest_numberYNumeric 16The phone number to forward the inbound call to.
number_prefixNNumericThe first digits of the number to allocate. Can be the full number.
number_rateNAlphanum 8The rate code for specific rate numbers; please contact Axialys for available rates. Example : A300 for 3,00 EUR/call
user_uidNAlphanum 16A unique ID specified by the client, used in order to uniquely track the user (web session, for instance). This data is made available in CDRs.
destination_uidNAlphanum 16A unique ID specified by the client, used in order to uniquely track the destination of the call; used to produce statistics. This data is made available in CDRs.
categoryNAlphanum 8A category defined by the client in order to differentiate various requests origins, such as mobile, web, app, etc. This data is made available in CDRs as well as service statistics.
max_durationNNumericThe maximum call duration in seconds.
caller_promptNAlphanum 16Filename of the message to play to the caller party before the call out occurs. The file must have been uploaded in Axialys management inteface.
called_promptNAlphanum 16Filename of the message to play to the called party when he picks the call up, before being connected to the caller. The file must have been uploaded in Axialys management inteface.
min_alloc_durationNNumericMinimum of seconds that the number should be allocated. Before that time, the allocation will not be cancelled and a subsequent request may fail because no more resource is available.
max_alloc_durationNNumericMaximum of seconds that the number should be allocated. After that time, the number will not perform any further call routing.
Response

The server will reply with a 200 OK and a JSON body when the operation is successful and with a 4xx or 5xx response otherwise.

Response fieldValue
numberThe E164 number which has been allocated for that request
idThe unique ID for this specific number allocation
unalloc_dtThe timestamp at which the number will be un-allocated. May be useful to hide the phone number from display after that time.
Err code HTTP status Meaning
ERR_INVALID_REQUEST 400 The request is incorrect
ERR_NO_RESOURCE 404 There is no inventory available for that kind of resource

4.3.2 inventory

Request

This function returns the current numbers inventory, including the status of each number.

https://api.axialys.com/dynacall/inventory
Parameters Mandatory Syntax Meaning
number_prefixNNumeric 16A phone number prefix might be specified in order to limit the scope of the request.
status_filterNAlphanumFilter on status; can be either FREE or ALLOCATED.
limitNNumericMax number of items to return.
acceptNAlphanumOutput format : application/json (default) or text/csv
Response

The server will reply with a 200 OK and a JSON or CSV body when the operation is successful and with a 4xx or 5xx response otherwise.

Response fieldValue
numberNumber in E164 format
statusFREE or ALLOCATED
last_alloc_dtTimestamp the number was last allocated (not including the current one, if any)
last_unalloc_dtTimestamp the number as last unallocated
The following fields are empty (or absent) for non allocated numbers:
dest_numberDestination number to call when the number below is called
alloc_dtTimestamp the number was allocated
user_uidUser/session UID specified when the number was requested
destination_uidDestination UID specified when the number was requested
categorycategory specified when the number was requested
request IPIP from which this number was requested
calls_receivedNumber of calls received on this allocation. Note that this data may not include a call still in progress
Err code HTTP status Meaning
ERR_INVALID_REQUEST 400 The request is incorrect

4.3.3 CDRs

Request

This function returns the call details records (CDRs) for the calls received on the service.

https://api.axialys.com/dynacall/cdrs
Parameters Mandatory Syntax Meaning
number_prefixNNumeric 16A phone number prefix might be specified in order to limit the scope of the request.
begin_dtNAlphanumThe date/time for the beginning of the period of interest, format shall be YYYY-MM-DD [HH:MM:SS]
end_dtNAlphanumThe date/time for the end of the period of interest, format shall be YYYY-MM-DD [HH:MM:SS]
status_filterNAlphanumFilter on call status; can be any call status such as ANSWER, BUSY, CANCEL…
limitNNumericMax number of items to return.
acceptNAlphanumOutput format : application/json (default) or text/csv
Response

The server will reply with a 200 OK and a JSON or CSV body when the operation is successful and with a 4xx or 5xx response otherwise.

Response fieldValue
numberService number in E164 format
calling_numberCalling party number in E164 format
statusOutcome of the call : ANSWER for calls that have been answered, or various error conditions, such as BUSY, CANCEL (cancelled by caller), etc.
durationCall duration in seconds
user_uidUser/session UID specified at request creation
destination_uidDestination UID specified at request creation
categorycategory specified at request creation
geo_originIf available, geographical origin; please contact Axialys for further details
Err code HTTP status Meaning
ERR_INVALID_REQUEST 400 The request is incorrect