Jump to Table of Contents

API Reports

This article provides some useful reports that you may want to use. This includes some operational reports that are not available via our Portal.

Logging into the API

You can access the API at the following endpoint:

https://api.infinitycloud.com/reports/v2

You'll need to include your username and password in your requests to the API.

Outputting API results in csv format

If you wish to export results from the API in csv format you can do so by following the steps below. These results can then also be used in excel.

Start by adding the format=csv argument to our URL. We add this with the “&” operator. Note that for this to work we also have to add the IGRP number again after a “?” operator.

You must also supply display parameters. These parameters tell the API which columns to insert into the csv file and in what order. Display parameters have the following form “display[]={parameter}”. For example you may use the parameters of “dgrpName”, “dgrp” and “startDate”, in that order:

https://api.infinitycloud.com/reports/v2/igrps/XXX/dgrps?igrp=XXX&format=csv&display[]=dgrpName&display[]=dgrp&display[]=startDate

If you wish to sort these results by date you will need to add a sort parameter. Sort parameters look very much like display parameters, except that you add –asc or –desc to the end. So to sort the previous sheet in ascending date order you would use:

https://api.infinitycloud.com/reports/v2/igrps/XXX/dgrps?igrp=XXX&format=csv&display[]=dgrpName&display[]=dgrp&display[]=startDate&sort[]=startDate-asc

Please update XXX with your installation ID (IGRP ID)

Exporting more than 50K Rows

We have added a restriction to stop more than 50,000 rows of data being pulled to ensure efficient use of the system on a day to day basis.

However should you wish to pull over 50,000 rows of data the way we recommend doing this is paginating large reports (getting 'pages' of data) is by filtering on the rowId property rather than using the offset.

Start by requesting 50,000 rows, sorted by ascending rowId. You should not sort by any other field in the API request, or else the batched export will not work as expected.

Replace XXX with your installation ID (IGRP ID) in the examples below.

https://api.infinitycloud.com/reports/v2/triggers/all?igrp=XXX&limit=50000&sort[]=rowId-asc

That request will return the first page of results, e.g.:

{"rowId":1,"triggerDatetime":"2016-01-01:00:00:00",...}
{"rowId":2,"triggerDatetime":"2016-01-01:00:00:00",...}
{"rowId":3,"triggerDatetime":"2016-01-01:00:00:00",...}
...
{"rowId":76529,"triggerDatetime":"2016-01-01:00:00:00",...}
{"rowId":76532,"triggerDatetime":"2016-01-01:00:00:00",...}

Make a note of the last rowId to be returned in that result set (e.g. 76532 in this example). Note that for various reasons, the rowId values might not start at 1, and might not be continuous.

Make the next request with the same parameters, but include a filter for rowId greater than that value, e.g.:

https://api.infinitycloud.com/reports/v2/triggers/all?igrp=XXX&limit=50000&sort[]=rowId-asc&filter[]=rowId-gt-value-76532

That request will return the next page of results, up to your pagination limit, e.g.:

{"rowId":76533,"triggerDatetime":"2016-01-01:00:00:00",...}
{"rowId":76538,"triggerDatetime":"2016-01-01:00:00:00",...}
{"rowId":76539,"triggerDatetime":"2016-01-01:00:00:00",...}
...
{"rowId":145327,"triggerDatetime":"2016-01-01:00:00:00",...}
{"rowId":145328,"triggerDatetime":"2016-01-01:00:00:00",...}

Continue in this way, replacing the rowId filter with the last value from each batch, until you get a result with fewer rows than your limit.

Once you reach the last page of data, you could persist the last rowId somewhere, and make periodic requests over time. By doing so, you can import data continuously into your own data warehouse for analysis.

Basic API Calls

Below are some basic API calls that can be used:

This call provides: date&time, DGRP ID, tracking number, caller ID, destination number, channel, call duration, channel type & match ref (triggerDatetime, dgrp&display, dialledPhoneNumber&display, srcPhoneNumber&display, destPhoneNumber&display, chName&display, callDuration&display, chType&display, matchRef)

https://api.infinitycloud.com/reports/v2/triggers/calls?igrp=XXX&limit=50000&startDate=YYYY-MM-MM&endDate=2016-05-01&format=csv&display[]=triggerDatetime&display[]=dgrp
&display[]=dialledPhoneNumber&display[]=srcPhoneNumber&display[]=destPhoneNumber&display[]=chName&display[]=callDuration&display[]=chType&display[]=matchRef

Be sure to update the igrp ID (XXXs), Year (YYYYs), Month (MMs) & Day (DDs)

This report provides a list of auto discovery numbers within an installation:

https://api.infinitycloud.com/config/v2/igrps/2139/dgrps?&limit=1000&format=debug&display[]=dgrpName&display[]=dgrp&display[]=autoDiscoveryNumber

Call State Report

If you are experiencing Call Fails within your Portal or unusual call behaviour, the call state report is a good report to start with to attempt to determine the cause of this.

Here are two useful report for you to pull:

https://api.infinitycloud.com/reports/v2/triggers/calls?igrp=XXXX&sort[]=triggerDatetime-desc&limit=50000&format=csv&display[]=triggerDatetime&display[]=srcPhoneNumber&display[]=callState 

https://api.infinitycloud.com/reports/v2/triggers/calls?igrp=XXXX&sort[]=triggerDatetime-desc&limit=50000&format=csv&display[]=triggerDatetime&display[]=srcPhoneNumber&display[]
=callState&display[]=txr&display[]=destPhoneNumber&display[]=ringTime

Please update XXX with your installation ID (IGRP ID)

You can also add other parameters to suit your needs. Please take a look at our API documentation article if you would like this to be customized to your own style of report.

Once the report has run you will be presented with call states. Here are the most common call states:

Call State Description
NO_ANSWER This cause is used when the called party has been alerted but does not respond with a connect indication within a prescribed period of time.
NO_USER_RESPONSE This cause is used when a called party does not respond to a call establishment message with either an alerting or connect indication within the prescribed period of time allocated.
UNALLOCATED_NUMBER This cause indicates that the called party cannot be reached because, although the called party number is in a valid format, it is not currently allocated (assigned) - we get this from our carrier, who in turn get it from BT/upstream telcos
USER_BUSY This cause is used to indicate that the called party is unable to accept another call because the user busy condition has been encountered. This cause value may be generated by the called user or by the network. In the case of user determined user busy it is noted that the user equipment is compatible with the call.
ORIGINATOR_CANCEL When the caller hangs up before being connected, this is probably because they have been waiting too long. Occasionally this may be due to Post Dial Delay (PDD)
PROTOCOL_ERROR This cause is used to report a protocol error event only when no other cause in the protocol error class applies. This too may be indicative of an upstream carrier issue or a problem routing calls to the customer, although they do not happen often.
NORMAL_CLEARING_A This is caused when the caller hangs up and is a normal call state
NORMAL_CLEARING_B This is caused when the operator hangs up and it is a normal call state (e.g. The operator rejecting the call before it is being answered on the handset.)
NORMAL_TEMPORARY_FAILURE_B This cause indicates that the network is not functioning correctly and that the condition is not likely to last a long period of time; e.g. the user may wish to try another call attempt almost immediately. The "B" means it is the Bleg of the call that is causing the problem, i.e the leg that is going to the customer's call center, and not the caller.

If there is a call state within your report that has not been listed above, please contact our Support Team

API Number Reports

See below for different Number Reports that can be used:

**This provides all fall back numbers within an IGRP.**

https://api.infinitycloud.com/config/v2/igrps/XXX/dgrps/all/numbers?format=debug&filter[] =usageType-eq-value-fixed&filter[]=ch-eq-value-0&display[]=dgrp&display[]=dgrpName&display[]=phoneNumber&sort[]=dgrp-asc

Note you need to change the format=debug to format=csv if you want to export the report.

**This will provide DGRP ID, auto-discovery number and DGRP name**

https://api.infinitycloud.com/config/v2/igrps/XXX/dgrps?format=csv&display[]=dgrpName&display[] =autoDiscoveryNumber&display[]=dgrp ~~~ Please update XXX with your installation ID (IGRP ID)

Getting a list of orgs in an IGRP

This call returns a csv list of active Organisations within an IGRP sorted by Name .

https://api.infinitycloud.com/reports/v2/igrps/XXX/organisations/?format=csv&sort[]=orgName-asc&display[]=orgId&display[]=orgName

Please update XXX with your installation ID (IGRP ID)

Google CID Reports

Below is the call for a Google CID Report.

https://api.infinitycloud.com/reports/v2/triggers/calls?igrp=XXX&limit=50000&format=csv&display[]=vid&display[]=dgrp&display[]=dialledPhoneNumber&display[]
=srcPhoneNumber&display[]=destPhoneNumber&display[]=chName&display[]=callDuration&display[]=chType&display[]
=matchRef&display[]=c_gua_cid&sort[]=rowId-desc

Or if you wish to set dates for the Reports use the one below.

https://api.infinitycloud.com/reports/v2/triggers/calls?igrp=XXX&limit=50000&format=csv&display[]=vid&display[]=dgrp&display[]=dialledPhoneNumber&display[]
=srcPhoneNumber&display[]=destPhoneNumber&display[]=chName&display[]=callDuration&display[]
=chType&display[]=matchRef&display[]=c_gua_cid&sort[]
=rowId-desc&startDate=2016-02-21&endDate=2016-06-21&display[]=triggerDatetime

When you get the spreadsheet, you should put a filter on the columns, and filter for Infinity VID (take away the blanks). You should then have a list of all calls with an Infinity VID (calls to dynamic numbers). Then, on the CID column, filter for blanks ONLY. You should be left with how many calls had a VID but NOT a CID, which means that the code wasn't capturing the correct CID with the call.

Please update XXX with your installation ID (IGRP ID)

Goals

In this example, the API will return a list of Goals from a particular date range, the results will show the href and vref and if the goal has any call information.

https://api.infinitycloud.com/reports/v2/triggers/goals?igrp=XXX&limit=50000&startDate=2016-02-08&endDate=2016-07-08&sort[]=rowId-desc&format=debug&display[]=txr&display[]=vid&display[]=triggerDatetime&display[]=href&display[]=vref&display[]=goal&display[]=chName&display[]=campaign&display[]=adGroup&display[]=matchRef&display[]=matchType&display[]=dialledPhoneNumber&display[]=destPhoneNumber&display[]=srcPhoneNumber&display[]=callDuration

To filter by a certain channel:

&filter[]=ch-eq-value-XXX

Replace XXX with the Channel ID to only see goals within this channel.

To filter by certain segments:

&filter[]=segment-eq-value-xxx

Please update XXX with your installation ID (IGRP ID)

Call Recording Download

You can download a single call recording by using the IGRP and rowId

https://api.infinitycloud.com/reports/v2/igrps/XXX/callRecording/YYYYYY

Please update XXX with your installation ID (IGRP ID) and YYYYYY with the RowId

Please login to rate this article

API Reports

  1. Logging into the API
  2. Outputting API results in csv format
  3. Exporting more than 50K Rows
  4. Basic API Calls
  5. Call State Report
  6. API Number Reports
  7. Removing Voids from queries
  8. Getting a list of orgs in an IGRP
  9. Google CID Reports
  10. Goals
  11. Call Recording Download
  1. Getting Started
  2. Enhancing your Installation
  3. Frequently asked questions
  4. Call Management
  5. Number Management
  6. Infinity API