Config API Version 2 Basics
Introduction
The Version 2 Config API is available on the following secure URL:
Input Format
- Input data needs to be supplied using standard HTTP POST arguments.
- Sending an empty string against a key removes this value
- Not sending a key will not change its value if it is already set.
- Updates can succeed or fail, there are no partial completions.
Output Format
- All output is in JSON.
- Simple error and information messages will be encoded as a JSON string.
- Complex data will be encoded as a JSON object. Response will return output data as one JSON object per line. A line-break will mark the end of the response.
The format parameter can be used to change the output to one of the following formats:
- csv - Outputs results in a standard CSV format, requires a “display” (see below) parameter to define the CSV headings.
- debug - Outputs results in a more human-readable format that JSON.
- json - Outputs results as JSON encoded objects, separated by newlines (this is the default format).
- jsonarray - Outputs results as a single parseable JSON array.
- xml - Outputs results in basic XML format.
- xhtml - Outputs results in basic XML format with an HTML-style table markup, requires a “display” (see below) parameter to define the table headings.
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
- csv
- xhtml
Fields can be aliased by supplying an alias with the field in the format of {field}-{alias}.
E.g.
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:
The direction must be either
- asc - Sort ascending, i.e. smallest first, a to z, or oldest date first.
- desc - Sort descending, i.e. largest first, z to a, or newest date first.
Each sort is added to the URL using an array. Multiple sorts are applied sequentially.
E.g.
Filtering
Many of our API routes allow the result set to be filtered by certain fields.
We have a standard filter definition format of:
Each filter is added to the URL using an array. Multiple filters are ANDed.
E.g.
The following operands are available:
- bool - Boolean comparison, e.g. true or false.
- eq - Equals comparison (case sensitive).
- eqi - Equals comparison (case insensitive).
- ne - Not equals comparison (case sensitive).
- nei - Not equals comparison (case insensitive).
- lt - Less than comparison.
- gt - Greater than comparison.
- ge - Greater than or equal to comparison.
- le - Less than or equal to comparison.
- inc - Includes (case sensitive).
- inci - Includes (case insensitive).
- ninc - Not includes (case sensitive).
- ninci - Not includes (case insensitive).
- re - Regular expression.
- begins - Begins (case sensitive).
- beginsi - Begins (case insensitive).
- in - Comma delimited list of values to match (case sensitive).
- nin - Comma delimited list of values to not match (case sensitive).
- ini - Comma delimited list of values to match (case insensitive).
- nini - Comma delimited list of values to not match (case insensitive).
rootOrgId
rootOrgId can be used to restrict the result set to a ‘parent’ organisation and any organisations that fall under it.
E.g.
Success Response Codes
- 200 - OK, this request was processed successfully.
- 201 - Created, the request created a new resource.
- 204 - No Content, the request updated an existing resource.
Error Response Codes
Errors are returned with an HTTP error code in the response header, E.g.
- 400 - Bad Request, E.g. invalid parameters supplied.
- 401 - Authentication required to access resource.
- 403 - Access denied to resource.
- 404 - Resource not found.
- 500 - Internal Error, something has gone wrong internally (will alert us).
The body of an error response is a JSON string that gives the message, E.g.
Access
Access to this API requires an Infinity login and the necessary access permissions.
- All routes require a username and password in the HTTP auth headers.
- If a username is not provided you will get a 401 “auth required” response code.
- If the username provided is not allowed to perform the requested action you will get a 403 “access denied” response code.
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:
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.
is a resource that contains an array of pass-through tags, POSTed as:
and returned as:
Common Fields
- status (int) - Infinity Status code indicating status of an object (E.g. 200)
- criteria (array) - The criteria to use when matching a rule (such as a visitor, goal, or segment). An array of objects, each with the following properties: field (the field to check), op (the operand to use when checking), and value (the value to check for).
Status Values
Status values are similar to the success and error response codes described above. The most common status values are:
- 200 - OK, this object is active and behaving normally.
- 401 - Unauthorised, e.g. for integrations that require third party logins when the login fails.
- 403 - Forbidden, e.g. for authenticated integrations where the login does not have access to the requested account.
- 409 - Conflict, request conflicts with existing data
- 410 - Gone, this object is archived, deleted or otherwise inactive.
- 423 - Locked, this object is disabled, usually by user action.
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”:
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).