Billing API Guide

Overview

AVOXI's Billing API provides access to system usage records needed for generating invoices for customers.  This information can then be integrated into billing systems for accounting purposes and support metadata querying for calls that customers have placed within the AVOXI Core environment.

How to Get Access

Send your access request to api@avoxi.com to have your IP address whitelisted and allow you to begin using the API.

Structure

The AVOXI API provides access using authenticated JSON RPC over HTTPS.  

All values are passed as strings in the API, including numeric and time values.  The table below illustrates.

TypeAs String
int"1"
float"1.0"
dateTimeYYYY-MM-DD HH24:MI:SS

All requests use the HTTP POST method and follow the request payload below:

{

“auth_info”: {

“session_id”: “Value from Login API”

},

“params”: {

Structure described in the API sections below

}

}

 

If the request results in an error, the API will respond with a HTTP 500 status code and a response body

{

“faultcode”: “API and problem specific code”,

“faultstring”: “Description of the problem”

}

 

The base URL for the table can be found for each of AVOXI’s operating environments below

Web Admin URLAPI URL
https://core.avoxi.com/https://api.avoxi.com/rest/
https://core.avoxi.co.za/https://api.avoxi.com/coza/rest

Concepts

Accounts

An account is a single virtual phone number, extension or SIP Trunk within the AVOXI Core platform.

Customers

A customer is referred to the organization within AVOXI Core.

Call Legs versus Calls

Call legs are represented as "Originating" and "Terminating" sections of a single phone call. In order to properly rate a call, the originating section must be added to the termination section of the call. For this reason, queries to get call information may result in 2 records with almost identical information. However, one of the records will represent the originating leg and the other will represent the terminating leg of the call.

For instance, to properly get the information of a call from Australia to the US, the origination leg of the call (Australia) must be added to the termination leg of the call (US). Once the two legs are added, the overall call record can be determined.

Authentication

Access to the Billing API is protected to prevent unauthorized access.  All requests except the Login request must be within a valid session and include the auth_info field in the request payload.

The sequence diagram below shows a typical session.

Billing API - AVOXI

API Details

Authentication

Login

METHOD: POST

URL:  BaseUrl/rest/Session/Login

The Login API begins a new session with the server, returning the session identifier needed for subsequent API calls.

The request structure of the Login API is slightly different from other APIs, the auth_info field is omitted.

Request Payload Parameters

FieldTypeDescription
loginstringAVOXI Core Admin UI Login
passwordstringPassword for provided login

Response Structure

FieldTypeDescription
session_idstringNewly created session id


Try It:

curl -ki -D POST https://api.avoxi.com/rest/Session/login --form params='{"login":<username>,"password":<password>}

 

Logout

URL: BaseURL/rest/Session/Logout

The Logout API ends a session and frees all server-held resources associated with it.

Request Payload Parameters

FieldTypeDescription
session_idstring Session id to be terminated


The response body is empty for the Logout API.

Call Records

Get Customer XDRs

METHOD: POST

URL: BaseURL/rest/Customer/get_customer_xdrs

This API allows the retrieval of xDRs for customers or accounts.

NOTE: This method has a 40-second time limit. To avoid the 500 Internal Server Error, please use the “offset”, “limit” and “get_total” properties when you need to retrieve large amounts of data.

Request Payload Parameters

PropertyTypeDescription
cdr_entitystringFlag that selects which
xDRs should be returned:

  • A – Account xDRs.
  • C – Customer xDRs.
  • Empty – Return
    account and
    customer xDRs.
for_current_periodintSpecifies whether to show xDRs for the current billing period
from_datedateTimeGet xDRs with bill_time starting from this date
get_totalintGet the total number of the retrieved xDRs
i_customerintThe unique ID of the customer record
i_invoiceintIndicates what xDRs will be shown:

  • nill – Midterm xDRs and out-of-
    turn xDRs
  • 0 – Out Of Turn xDRs
  • Not set – xDRs of all types
i_serviceintID of the service; refers to the Services table
i_service_typeintThe unique ID of the related service type
limitintThe number of rows to retrieve
offsetintThe number of rows to skip at the beginning of the list
show_unsuccessfulintShow xDRs of unsuccessful attempts
to_datedateTimeGet xDRs with bill_time before this date
with_cr_download_linksintIf set, then each xDR will contain download links to the recorded files if any


Response Structure

The response structure has two top-level fields, total and xdr_list.  The total is the number of retrieved xDRs if the get_total field was set.  The xdr_list is an array of XDR records whose structure is described below.

PropertyTypeDescription
i_xdrintThe unique ID of the xdr record
i_serviceintThe unique ID of the service record
i_destintThe unique ID of the destination record
account_idstringThe unique ID of the account database record (used only for accounts)
CLIstringCalling Line Identification
CLDstringCalled Line Identification
charged_amountfloatAmount charged
charged_quantitystringUnits charged
countrystringCountry
subdivisionstringCountry subdivision
descriptionstringDestination description
disconnect_causestringThe code of tdisconnect cause
bill_statusstringCall bill status
disconnect_reasonstringCall disconnect reason
connect_timedateTimeCall connect time
unix_connect_timeintCall connect time (expressed in Unix time format - seconds since epoch)
disconnect_timedateTimeCall disconnect time
unix_disconnect_timeintCall disconnect time (expressed in Unix time format - seconds since epoch)
bill_timedateTimeCall bill time
bit_flagsintExtended information how the service was used; the integer field that should be treated as a bit-map. Each currently used bit is listed in the Transaction_Flag_Types table (bit_offset indicates position).
call_recording_urlstringPath to recorded .wav files
call_recording_server_urlstringURL to the recording server
cr_download_linksArray of stringsA list of direct download links to the recorded files
h323_conf_idstringThe unique session ID
h323_incoming_conf_idstringThe unique ID of the incoming session (if exists) used for interrelating xDRs, when the charged session is established as a result of a previous session (possibly having its own xDR)
xdr_typestringThe type of xDR.
Possible values:

  • customer
  • account
servicestringThe service name
destinationstringThe destination name

Try It:

curl -ki -D POST https://api.avoxi.com/rest/Customer/get_customer_xdrs --form auth_info='{"session_id":<session_id>}' --form params='{"i_customer":<i_customer>,"from_date":"2018-01-01 00:00:00","to_date":"2018-07-25 23:59:59"}'

Get xDRs

URL: BaseURL/rest/Account/get_xdr_list

This API allows the retrieval of xDRs for customers or accounts.

NOTE: This method has a 40-second time limit. To avoid the 500 Internal Server Error, please use the “offset”, “limit” and “get_total” properties when you need to retrieve large amounts of data

Request Payload Structure

PropertyTypeDescription
i_accountintThe unique ID of the account
i_service nintID of Service; refers to Services table
limitnintThe number of rows to retrieve
offsetnstringThis parameter allows API user to get xDRs in other formats via SOAP attachment. Currently only the “.csv” format is supported
from_datedateTimeGet xDRs with bill_time starting from this date
to_datedateTimeGet xDRs with bill_time before this date
formatstringThis parameter allows to get xDRs in other formats via SOAP attachment. Currently only the “csv” format is supported
get_totalnintGet the total number of the retrieved xDRs
show_unsuccessfulintShow xDRs of unsuccessful attempts
with_cr_download_linksintIf set, then each xDR will contain download links to the recorded files if any

 

Response Structure

The response structure has two top-level fields, total and xdr_list.  The total is the number of retrieved xDRs if the get_total field was set.  The xdr_list is an array of XDR records whose structure is described below.

PropertyTypeDescription
i_xdrintID of XDR record
i_serviceintThe unique ID of the service record
i_destintThe unique ID of the destination record
CLIstringCalling Line Identification
CLDintCalled Line Identification
charged_amountfloatAmount charged
charged_quantityintUnits charged
countrystringCountry
subdivisionstringCountry Subdivision
descriptionstringDestination description
disconnect_causestringThe code of disconnect cause
disconnect_reasonstringThe unique ID of the service record
bill_statusstringCall bill status
connect_timedateTimeCall connect time
unix_connect_timeintCall connect time (expressed in: Unix time format – seconds since epoch)
disconnect_timedateTimeCall disconnect time
unix_disconnect_timeintCall disconnect time (expressed in: Unix time format – seconds since epoch)
bill_timedateTimeCall bill time
bit_flagsintExtended information how the service was used; the integer field that should be treated as a bit-map. Each currently used bit is listed in the Transaction_Flag_Types table (bit_offset indicates position).

To learn more about bit flags
values, please see the How to
Use Bit Flags chapter in this
guide.

call_recording_urlstringPath to recorded .wav files
call_recording_server_urlstringURL to the recording server
cr_download_linksArray of stringsA list of direct download links to the recorded files

How to Use Bit Flags

Bit flags help to determine the type of an xDR.
The common formula for calculation of the type of the call record is:

type = ( bit_flags & bit_mask ) >> bit_offset

where & is a binary ADD and >> is a binary right shift, and the bit_mask and offset values are taken from the Transaction_Flag_Types in the database and correspond to the particular xDR type.

The following table represents the Transaction_Flag_Types table from the database with descriptions added.

namebit_maskbit_offsetDescription
acc10Specifies whether there is a debit overdraft.

Possible values:

  • 1 – There is a debit
    overdraft.
  • 0 – There is no debit
    overdraft.
time21Specifies whether the connect or disconnect time is adjusted to the request time, because the original timestamps were unclear or suspiciously old.

Possible values:

  • 1 – The connect or
    disconnect time is
    adjusted
  • 0 – The connect or
    disconnect time is not
    adjusted
calltype122Distinguishes the following

call types:

  • 0 – Unknown
  • 1 – Outbound
  • 2 – Inbound
  • 3 – Forwarded
refeed164Specifies whether the xDR is created as a result of a refeed process.

Possible values:

  • 1 – The xDR is created as a result of the refeed process.
  • 0 – The xDR has not been erased by the refeed process.
privacy325Specifies whether the call is

private:
Possible values:

  • 1 – The call is private.
  • 0 – The call is not
    private.
call_recording646The unique ID of the account
is_hidden1287Specifies whether the xDR is

hidden:

  • 1 – The xDR is hidden.
  • 0 – The xDR is not
    hidden.

 

For example, you have a bit_blag 108 (01101100 in the binary format) and you look for whether the call was recorded.

In the Transaction_Flag_Types table, you can find a bit_mask for
call_recording. Its value is 64, which is 01000000 in the binary format.

You perform the binary AND operation over the bit_flag and the found
bit_mask values:

01101100 & 01000000 = 01000000 (1)

Then you take the offset value from the Transaction_Flag_Types.
For call_recording, the offset is 6. So you need to shift the (1) to the right
by the number of 6 positions:

01000000 >> 6 = 00000001

That is, as a result of the operations with the bit flag for call recording you
receive the value ‘1’ or ‘true’, which means that the call is really recorded.

In the following tables, you can find the list of some bit flags and their
transcriptions.

Bit flagBit flag's binary valueDescription
00000000Unknown event, i.e. no match is found
10000001Debit overdraft
400000100Outgoing call
500000101Outgoing call with debit overdraft
800001000Incoming call
1200001100Forwarded call (outgoing call + incoming call)
3600100100Outgoing private call
4000101000Incoming private call
4400101100Forwarded private call
6801000100Outgoing recorded call
7201001000Incoming recorded call
7601001100Forwarded recorded call
10001100100Outgoing private recorded call
10401000100Incoming private recorded call
10801101100Forwarded private recorded call