Config API Version 2 Basics

Introduction

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

    https://api.infinitycloud.com/config/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"}

Sorting

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

We have a standard sort definition format of:

 {fieldName}-{direction}

The direction must be either

Each sort is added to the URL using an array. Multiple sorts are applied sequentially.

E.g.

 ?sort[]=bandName-asc&sort[]=phoneNumber-asc

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[]=phoneNumber-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

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/config/v2/..."

Unique keys and local arrays

Objects that have fully unique IDs, e.g. IGRPs, DGRPs and goals will have their own resource URLs. Anything that is defined relative in JSON fields will be defined within their parent’s resource URL e.g.

/config/v2/igrps/1

is a resource that contains an array of pass-through tags, POSTed as:

passTags[0]=sometag
passTags[1]=ovid

and returned as:

{ "passTags":["sometag","ovid"] }

Common Fields

Status Values

Status values are similar to the success and error response codes described above. The most common status values are:

Criteria Values

Criteria consist of three properties - a field to check, an operand to use then checking and a value to check for. For example the following criteria array will match triggers with an action of “call”:

criteria[0][field]=action&criteria[0][op]=eq&criteria[0][value]=call

The operands are the same as those used for filtering (see Filtering) and the value can be anything appropriate to the operand. The field names that can be checked vary depending on the situation.

Segments are commonly configured using trigger fields such as “href”, dividing activity in different parts of a web site into different segments (see Segments)

Goals configurations are checked after segments. These are commonly configured using trigger fields such as “act”, “href”, or even “segment” (see Goals).

Third party integrations are checked after both segments and goals. The same trigger fields are available to integration criteria, with the addition of the “segment” and “goal” fields, e.g. to send triggers matching an Infinity goal into the third party system (see Integrations).