Reports API Version 2 Triggers

Introduction

These trigger routes are deprecated, please use new ones Reports V2 Triggers.

A trigger represents a single tracked event in Infinity. Triggers can be made up of Online and Offline events, such as web site page views or calls. Triggers can be exported from Infinity as a list with various filters applied.

Attribution

Attribution allows you to report on call and goal data in different ways, depending on the marketing channels and sources that bring visitors to your web site. The parameters that control attribution within reports are detailed below but for general information on attribution within the Infinity platform, please refer to our Knowledge Base article.

Attribution Models

Some reports allow you to choose an attributionModelId, which defaults to zero for the “Last Click (Absolute)” model. Using a different attribution model in your reports allows you to see the effect of multiple touchpoints in visitor journeys, by attributing part or all of each goal to one or more of the marketing channels that the visitor engaged with.

Triggers List

Lists the triggers within an IGRP with the following predefined filtered reports:

Get all triggers

GET /reports/v2/triggers/all

Get all call triggers ( where trigger action is call )

GET /reports/v2/triggers/calls

Get all Hosted PBX Call User triggers ( where trigger action is callUser )

GET /reports/v2/triggers/calls/users

Get all goal triggers ( where trigger is marked as a goal )

GET /reports/v2/triggers/goals

Get all transaction triggers ( where trigger has transaction currency or goal currency fields ). callRate triggers are excluded from these reports

GET /reports/v2/triggers/transactions

Get all triggers with any transaction, call or goal details. This is a union of the three routes “calls”, “goals” and “transactions” described above.

GET /reports/v2/triggers/callsGoalsTransactions

Get all touch point triggers. This is a collection of recent land, call and goal triggers. You can only query back as far as your Installation’s trigger retention period on this route.

GET /reports/v2/triggers/touchPoints

Get all visits triggers (where trigger act are lands)

GET /reports/v2/triggers/visits

GET Params

Filter Types

Sort Types

Same fields as Filter Types, see above.

Response:

Returns a list of triggers that match the supplied filters.

Examples

Here are some examples for getting Transactions out of the API.

List the 100 most recent transactions in human readable format

https://api.infinitycloud.com/reports/v2/triggers/transactions?igrp=1&limit=100&sort[]=rowId-desc&format=debug

List the 100 most recent transactions using a specific Attribution Model

https://api.infinitycloud.com/reports/v2/triggers/transactions?igrp=1&limit=100&sort[]=rowId-desc&format=debug&attributionModelId=123

Output in JSON or XML

https://api.infinitycloud.com/reports/v2/triggers/transactions?igrp=1&limit=100&sort[]=rowId-desc&format=json&attributionModelId=123
https://api.infinitycloud.com/reports/v2/triggers/transactions?igrp=1&limit=100&sort[]=rowId-desc&format=xml&attributionModelId=123

Export to CSV

If you wanted to export to Excel via CSV you can use our CSV output format option.

However because each transaction can have multiple keywords associated to it (due to the attribution model), you need to flatten the output by disabling nested attribution data output:

https://api.infinitycloud.com/reports/v2/triggers/transactions?igrp=1&limit=100&sort[]=rowId-desc&format=debug&attributionModelId=123&nestAttributions=0

To convert this output to CSV you need to specific the fields you want in the CSV and specifiy the output format as CSV:

https://api.infinitycloud.com/reports/v2/triggers/transactions?igrp=1&limit=100&sort[]=rowId-desc&format=csv&attributionModelId=123&nestAttributions=0&display[]=act&display[]=txr&display[]=txc&display[]=txv&display[]=value&display[]=vid&display[]=triggerDatetime&display[]=attributionMatchRef&display[]=attributionChName

Retrieve all triggers

For performance reasons, results from the Infinity API are restricted to a maximum of number of rows per request. This maximum number is typically 10,000 and if you specify a higher limit value the API will return an error.

If you want a larger number of triggers then you must make multiple requests, fetching a small batch of triggers in each request. The most efficient way to do this is to sort and filter by rowId.

Start by requesting the first batch ( rowId > 0 ), record the last rowId seen in the response, and then use that to filter the next batch. Continue in this way until no rows are returned from the API.

Request the first batch:

https://api.infinitycloud.com/reports/v2/triggers/all?igrp=1&startDate=2015-05-01&endDate=2015-05-31&tz=Europe%2FLondon&sort[]=rowId-asc&limit=1000&filter[]=rowId-gt-value-0

In this request we have defined the IGRP, the date range and timezone. We have sorted the results by rowId ascending (required) and asked for no more than 1000 results (your batch size could be different but we’ve found 1000 to work well). We also requested only rowId values greater than zero. While this doesn’t actually filter the first batch (rowId is always positive), it highlights the difference in subsequent batch requests.

Check the results, noting the last rowId:

{"rowId":"141247288","triggerDatetime":"2015-05-01 00:00:01",...}
{"rowId":"141247289","triggerDatetime":"2015-05-01 00:00:02",...}
...
{"rowId":"141248744","triggerDatetime":"2015-05-01 00:19:45",...}
{"rowId":"141248745","triggerDatetime":"2015-05-01 00:19:57",...}

Note that the rowId may not start at 1 (some triggers are deleted after a certain time), there may be gaps in the rowId sequence, and that the triggerDatetime may be out of sequence with the rowId, due to the asynchronous nature of our tracking platform. The rowId will always be unique and incremental though, which is why this method works.

Use the last rowId to request the next batch (the only difference between this request and the previous request is the filtered rowId value at the end):

https://api.infinitycloud.com/reports/v2/triggers/all?igrp=1&startDate=2015-05-01&endDate=2015-05-31&tz=Europe%2FLondon&sort[]=rowId-asc&limit=1000&filter[]=rowId-gt-value-141248745

Continue in this way, changing the rowId in each request until you have worked through the whole result set and retrieve no more rows.

It is possible to retrieve all triggers from Infinity over time, e.g. to populate your own data warehouse with Infinity trigger data. To do this you can remove the date range (startDate and endDate parameters). Poll the API periodically to get new data, persisting the last seen rowId between requests so you don’t start from the beginning each time.

This method also works with other routes, e.g. to import all calls (/reports/v2/triggers/calls), or all transactions (/reports/v2/triggers/transactions).

Field Definitions

Here are a list of fields that can be returned in the Trigger List reports.

General Fields

Custom Pass-Through Fields

Triggers can have certain landing tags persisted through a Visitor’s session and stored with every subsequent trigger.

For customers with pass-through tags enabled the following variables will be available.

Custom Fields

You can record non-session persisted variables against a trigger, these are called Custom Variables.

For customers using custom variables the following variables will be available.

Visitors

Attribution

Attributed lands for a trigger are contained in the attributions array field.

Each attributed land can contain these fields:

Marketing Sources

Phone Number Allocation

Goals and Transactions

Calls

For triggers with an action of “call” these are the common custom element names.

Note that Infinity’s unique call reference is stored in the txr field. If you are using post call rating with currency capture, these will be stored in the txv and txc fields.

Hangup States

A hangup state is what caused the call to be ended. It is in the format of {REASON}_{LEG}

E.g.

NORMAL_CLEARING_A - This means that the A-leg (caller) triggered the end of the call normally.

The following reasons are defined: