Reports API Version 2 Basics

Introduction

The Version 2 Reports API is available on the following secure URL:

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

Input Format

Output Format

{"orgId":101,"orgTitle":"Organisation One","orgCreated":"2012-02-29 15:20:13"}
{"orgId":102,"orgTitle":"Organisation Two","orgCreated":"2012-02-29 15:20:13"}
{"orgId":103,"orgTitle":"Organisation Three","orgCreated":"2012-02-29 15:20:13"}

The format parameter can be used to change the output to one of the following formats:

Display param

The display param defines what fields will be output via the API, if excluded all fields will be will be returned.

The display param is required for the following output formats

Fields can be aliased by supplying an alias with the field in the format of {field}-{alias}.

E.g.

 ?display[]=triggerDatetime&display[]=act&display[]=vid-visitorId
{"triggerDatetime":"2014-01-01 00:00:00","act":"land","visitorId":"b5bb14cc-7cf6-49ff-a131-538d85bd143d"}
{"triggerDatetime":"2014-01-02 00:00:00","act":"page","visitorId":"b5bb14cc-7cf6-49ff-a131-538d85bd143d"}
{"triggerDatetime":"2014-01-03 00:00:00","act":"page","visitorId":"b5bb14cc-7cf6-49ff-a131-538d85bd143d"}

Filtering

Many of our API routes allow the result set to be filtered by certain fields.

We have a standard filter definition format of:

 {fieldName}-{operandCode}-value-{comparisonValue}

Each filter is added to the URL using an array. Multiple filters are ANDed.

E.g.

 ?filter[]=srcPhoneNumber-eq-value-1234&filter[]=bandName-eq-value-bronze

The following operands are available:

rootOrgId

rootOrgId can be used to restrict the result set to a ‘parent’ organisation and any organisations that fall under it.

E.g.

 ?rootOrgId=1234

Dates and Timezones

A custom timezone can be applied to any report with the “tz” as an optional parameter. The default timezone is UTC, unless otherwise specified.

Timezones can be supplied in the following format Country/Town, E.g.

 &tz=Europe/London

A list of timezones can be found here: Valid Timezones

Many reports also support Date selectors, and these are provided using two standard parameters; startDate and endDate. The date range is inclusive of the end date and is required in the format YYYY-MM-DD.

E.g.

 &startDate=2011-01-01&endDate=2011-01-31

Grouping

Many of our API routes allow the result set to be grouped by certain fields.

We have a standard group definition format of:

 {fieldName}

Multiple fields can be grouped at once.

E.g.

 ?group[]=srcPhoneNumber&group[]=bandName

Sorting

Many of our API routes allow the result set to be sorted by certain fields.

We have a standard sort definition format of:

 {fieldName}-{order}

Order can be either ‘asc’ or ‘desc’, representing ascending and descending order respectively.

Multiple fields can be sorted at once.

E.g.

 ?sort[]=srcPhoneNumber-asc&sort[]=bandName-desc

Pagination

Any reports with “limit” and “offset” as option parameters support pagination. Some reports will only support limit.

To paginate a report:

 &limit=10&offset=5

Success Response Codes

Error Response Codes

Errors are returned with an HTTP error code in the response header, E.g.

The body of an error response is a JSON string that gives the message, E.g.

"Resource not found"

Access

Access to this API requires an Infinity login and the necessary access permissions.

Usernames and passwords must be provided as HTTP headers, e.g. if using cURL on the command line you would send a request in the following format:

curl -u user.name@example.com "https://api.infinitycloud.com/reports/v2/..."

Cross-origin resource sharing requests (CORS)

The reports API is compatible with CORS requests. However we recommend only making these requests inside internal or private applications as there is a risk of exsposing your API credentials.

The request must be sent with the “withCredentials” XHR flag for authentication

An example using jQuery’s XHR object

$.ajax({
    xhrFields: {
        withCredentials: true
    }
});

Custom Metrics

Some reports support Custom Metrics. These allow you to add extra metric columns to your report, where each column is filtered by one or more of the report’s dimensions.

Custom metrics fields can be specified in the format:

customMetrics[{reference}]={metricField}_{conditionFieldN}_{conditionValueN}

Each custom metric is based on a metric field (e.g. goalCount), and a condition field and value. They should each have a simple reference, to identify them in sort and display parameters.

For example, in the Channel Metrics report you might want to see goals per channel, with separate columns for certain goal types, and one column for the total goals.

The URL for your report might look like this:

https://api.infinitycloud.com/reports/v2/metrics/channels?igrp=1&startDate=2015-05-01&endDate=2015-05-31&limit=10000&group[]=ch&sort[]=ch-asc&customMetrics[goals246]=goalCount_goal_246&customMetrics[goals543]=goalCount_goal_543

Note the channel goal types (goal) are referenced by their numeric IDs.

Sorting by Custom Metrics

When sorting custom metrics, you treat the reference string as a field name.

For example, to sort operational call metrics by a custom metric based on calls to a queue name of “Sales-Main”, you would need:

... &customMetrics[SalesCalls]=callCount_queueName_Sales-Main&sort[]=SalesCalls-asc ...

Grouping and Filtering by Custom Metrics

Grouping and Filtering by Custom Metric fields is not supported.

Custom Metrics with Multiple Conditions

Custom metrics can be based on multiple conditions.

For example, a goal count column for goal ID 246 and channel ID 625 might look like this:

... &customMetrics[SeoGoals]=goalCount_goal_246_ch_625 ...

Custom Metrics with Multiple Values in one Condition

Custom metrics can combine data for multiple condition values.

For example, to show a combined goal count for goal types with ID 763 or 356 would look like this:

... &customMetrics[CombinedGoals]=goalCount_goal_763,356 ...

Custom Metrics condition values with underscores or commas

Because the custom metric definitions are delimited by underscores and commas, if you have either of these in your condition values you will need to escape them using a backslash.

For example, to show a call count for the queue “My_Queue”, try this:

... &customMetrics[MyCalls]=callCount_queueName_My\_Queue ...

Or to show a call count for either “My_Queue” or “Service, Support”, try this:

... &customMetrics[MyCalls]=callCount_queueName_My\_Queue,Service\,%20Support ...

You will also need to escape any backslashes in your condition values to avoid triggering the scenarios described above. For technical reasons you’ll need to replace each backslash in your condition values with four backslashes.

For example, to show a call count for the queue “My\Queue”, try this:

... &customMetrics[MyCalls]=callCount_queueName_My\\\\Queue ...

Channel Type

Some reports support channel type. This allows you to view the metrics for a specific channel and thereby adding dimensions to the reports.

Channel Types are the marketing channels used for digital marketing necessary in the business.

Channel Type field can be specified in the format:

...&chType=channeltypevalue

Channel Type is a string value (See list below for potential channel types) and is added to the URL.

For example, in the Channel Metrics report you might want to see goal, goalCountTotal per channel, with separate columns for call goal count, online goal count etc.

The URL for your report might look like this:

https://api.infinitycloud.com/reports/v2/metrics/channels?igrp=1&attributionModelId=1003&startDate=2001-01-01&endDate=2018-01-02&group%5B0%5D=goal&sort%5B0%5D=goal-desc&chType=direct

Default Channels

* display - Display
* ppc - Paid Search
* affiliate - Affiliate
* social - Social
* video - Video
* email - Email
* sms - SMS
* offline - Offline
* seo - Organic Search
* ref - Website Referrer
* direct - Website Direct

PBX Channels

* pbxCallTrack - PBX call track
* pbxDdi - PBX direct dial in (Ddi) calls
* pbxInternal - PBX internal calls
* pbxOutbound - PBX outbound calls

Customer Channels

* cust - customer defined channel

PII Data Redaction

Most API endpoints support automatic Personally Identifiable Information (PII) Data Redaction, which will limit values for IP Address and Source Phone Number, and will entirely remove values for host and whois. IP addresses have the last octet set to “X” and the Source Phone Number have the last four digits set to “XXXX”. To see the non-redacted PII data, you will need the piiData permission.

If you have the the correct permission, you may optionally choose to redact PII Data on a per-request basis with this GET parameter:

... &excludePiiData=1

This flag has no effect for users who do not have the piiData permission.

Redacted and non-redacted information looks as follows:

Field Value Redacted
host infinity.co  
whois Infinity Call Tracking, Ltd  
ip 198.51.100.28 198.51.100.X
srcPhoneNumber 07700900461 0770090XXXX

Integrations

To see how to use our integrations with the PII Data redaction, see Integrations which explains how to include or exclude the PII Data.