Introduction
Welcome to Engagio's API!
What can our API do?
Today, our API allows read-only access to your Analytics data. Specifically, you can:
- Get Accounts
- Get People
- Get Activites
- Get Account Lists
Getting a Token
Email support@engagio.com to receive a token
Authentication
For authentication, there are two choices:
Use basic authentication with your Engagio API token as the username and an empty password.
Pass a header like: Authorization: Bearer engagio_v334asfsdfo3241ERqwefe
- The part after "Bearer" is your API token.
Accounts
GET /accounts/fields
curl \
"https://api.engagio.com/api/v1/accounts/fields" \
-H "Authorization: Bearer engagio_v334asfsdfo3241ERqwefe"
var request = require('request');
request({
headers: {
'Authorization': 'Bearer engagio_v334asfsdfo3241ERqwefe',
'Content-Type': 'application/json'
},
uri: 'https://api.engagio.com/api/v1/accounts/fields',
method: 'GET'
}, function (err, res, body) {
var pJSON = JSON.parse(body);
console.log(pJSON)
})
The above command returns JSON structured like this:
[
{
"name": "{Account}.engagementMinutesLast7Day",
"label": "# Play Steps Resolved (all time)",
"dataType": "Long",
"pickListValues": [],
"cardinality": -1,
"status": "Normal",
"referenceTo": []
}
]
HTTP Request
GET https://api.engagio.com/api/v1/accounts/fields
The Account Fields endpoint returns a list of all fields that are available to be returned via the /accounts endpoint.
GET /accounts
curl \
-G "https://api.engagio.com/api/v1/accounts" \
-d "accountList=39&fields={Account}.engagementMinutesLast7Day&filters={"field": "{Account}.sfdcId", "operator": "Equals", "values":["0011a00000DpxW3AAJ", "0011a00000DpxbJAAR"]}&format=json" \
-H "Authorization: Bearer engagio_v334asfsdfo3241ERqwefe"
var request = require('request');
request({
headers: {
'Authorization': 'Bearer engagio_v334asfsdfo3241ERqwefe',
'Content-Type': 'application/json'
},
uri: 'https://api.engagio.com/api/v1/accounts?accountList=39&fields={Account}.engagementMinutesLast7Day&filters={"field": "{Account}.sfdcId", "operator": "Equals", "values":["0011a00000DpxW3AAJ", "0011a00000DpxbJAAR"]}&format=json',
method: 'GET'
}, function (err, res, body) {
var pJSON = JSON.parse(body);
console.log(pJSON)
})
The above command returns JSON structured like this:
[
{
"{Account}.engagementMinutesLast7Days": 216.54,
"{Account}.id": 6
},
{
"{Account}.engagementMinutesLast7Days": 122.24199999999998,
"{Account}.id": 8
}
]
The Accounts endpoint returns a CSV file or JSON blob that contains details about accounts in an Engagio account list. Use the fields parameter to specify the desired fields to return.
❗ Either accountList or account parameter must be provided as well as at least one of the fields you want.
HTTP Request
GET https://api.engagio.com/api/v1/accounts
Query Parameters
Parameter | Type | Description |
---|---|---|
fields | query string[], multiple parameters (fields=aaa&fields=bbb) | Names of fields to return. Call /accounts/fields to learn available fields. |
accountList | query integer | Description: ID of the Engagio account list whose accounts should be returned. |
filters | query object[], multiple parameters (filters=aaa&filters=bbb) | Description: Filters to apply to limit the data returned. |
format | query string (i.e. &format=json) | Description: Specify JSON to receive output as a JSON object as opposed to the .csv file output. |
from | Type of Param: query string (ISO date) | Description: The start date for the date range used for engagement-related fields, in ISO format. |
to | Type of Param: query string (ISO date) | Description: The end date for the date range used for engagement-related fields, in ISO format. |
Responses
A CSV file with one row per account and one column per requested field, unless "format=json" was specified
Invalid request
Server error occurred
People
GET /people/fields
curl \
"https://api.engagio.com/api/v1/people/fields" \
-H "Authorization: Bearer engagio_v334asfsdfo3241ERqwefe"
var request = require('request');
request({
headers: {
'Authorization': 'Bearer engagio_v334asfsdfo3241ERqwefe',
'Content-Type': 'application/json'
},
uri: 'https://api.engagio.com/api/v1/people/fields',
method: 'GET'
}, function (err, res, body) {
var pJSON = JSON.parse(body);
console.log(pJSON)
})
The above command returns JSON structured like this:
[
{
"name": "{Person}.company",
"label": "Company",
"dataType": "String",
"pickListValues": [],
"cardinality": -1,
"status": "Normal",
"referenceTo": []
}
]
HTTP Request
GET https://api.engagio.com/api/v1/people/fields
The People Fields endpoint returns a list of all fields that are available to be returned via the /people endpoint. This will return not only available people fields but also related account fields (just like in our application).
GET /people
curl \
-G "https://api.engagio.com/api/v1/people" \
-d "accountList=39&fields={Person}.company&format=json" \
-H "Authorization: Bearer engagio_v334asfsdfo3241ERqwefe"
var request = require('request');
request({
headers: {
'Authorization': 'Bearer engagio_v334asfsdfo3241ERqwefe',
'Content-Type': 'application/json'
},
uri: 'https://api.engagio.com/api/v1/people?accountList=39&fields={Person}.company&format=json',
method: 'GET'
}, function (err, res, body) {
var pJSON = JSON.parse(body);
console.log(pJSON)
})
The above command returns JSON structured like this:
[
{
"{Person}.company": "BloomReach",
"{Person}.id": 21812
},
{
"{Person}.company": "BloomReach",
"{Person}.id": 21748
}
]
The People endpoint returns a CSV file or JSON blob that contains details about people in an Engagio account list. Use the fields parameter to specify the desired fields to return.
❗ Either accountList or account parameter must be provided as well as at least one of the fields you want.
HTTP Request
GET https://api.engagio.com/api/v1/people
Query Parameters
Parameter | Type | Description |
---|---|---|
fields | query string[] , multiple parameters (fields=aaa&fields=bbb) | Names of fields to return. Call /accounts/fields to learn available fields. |
accountList | query integer | ID of the Engagio account list whose people should be returned. |
account | query integer | ID of the Engagio account to return data for. |
filters | query object[] , multiple parameters (filters=aaa&filters=bbb) | Filters to apply to limit the data returned. |
format | query string (i.e. &format=json) | Specify JSON to receive output as a JSON object as opposed to the .csv file output. |
from | query string (ISO date) | The start date for the date range used for engagement-related fields, in ISO format. |
to | query string (ISO date) | The end date for the date range used for engagement-related fields, in ISO format. |
Responses
A CSV file with one row per person and one column per requested field, unless "format=json" was specified
Invalid request
Server error occurred
Activities
GET /activities/fields
curl \
"https://api.engagio.com/api/v1/activities/fields" \
-H "Authorization: Bearer engagio_v334asfsdfo3241ERqwefe"
var request = require('request');
request({
headers: {
'Authorization': 'Bearer engagio_v334asfsdfo3241ERqwefe',
'Content-Type': 'application/json'
},
uri: 'https://api.engagio.com/api/v1/activities/fields',
method: 'GET'
}, function (err, res, body) {
var pJSON = JSON.parse(body);
console.log(pJSON)
})
The above command returns JSON structured like this:
[
{
"name": "{Activity}.category___e",
"label": "Category",
"dataType": "String",
"pickListValues": [],
"cardinality": -1,
"status": "Normal",
"referenceTo": []
}
]
HTTP Request
GET https://api.engagio.com/api/v1/activities/fields
The Activities Fields endpoint returns a list of all fields that are available to be returned via the /activities endpoint. This will return not only available activity fields but also related people and account fields (just like in our application).
GET /activities
curl \
-G "https://api.engagio.com/api/v1/activities" \
-d "accountList=39&fields={Activity}.category___e&format=json" \
-H "Authorization: Bearer engagio_v334asfsdfo3241ERqwefe"
var request = require('request');
request({
headers: {
'Authorization': 'Bearer engagio_v334asfsdfo3241ERqwefe',
'Content-Type': 'application/json'
},
uri: 'https://api.engagio.com/api/v1/activities?accountList=39&fields={Activity}.category___e&format=json',
method: 'GET'
}, function (err, res, body) {
var pJSON = JSON.parse(body);
console.log(pJSON)
})
The above command returns JSON structured like this:
[
{
"{Activity}.category___e": "Marketing Email Open",
"{Activity}.id":3593215
},
{
"{Activity}.category___e": "Marketing Email Open",
"{Activity}.id":3769345
}
]
The Activities endpoint returns a CSV file or JSON blob that contains details about activities in an Engagio account list. Use the fields parameter to specify the desired fields to return.
❗ Either accountList or account parameter must be provided as well as at least one of the fields you want.
HTTP Request
GET https://api.engagio.com/api/v1/activities
Query Parameters
Parameter | Type | Description |
---|---|---|
fields | query integer | Names of fields to return. Call /activities/fields to learn available fields. |
accountList | query integer | ID of the Engagio account list whose activities should be returned. |
account | query integer | ID of the Engagio account to return data for. |
filters | query object[], multiple parameters (filters=aaa&filters=bbb) | Filters to apply to limit the data returned. |
format | query string (i.e. &format=json) | Specify JSON to receive output as a JSON object as opposed to the .csv file output. |
from | query string (ISO date) | The start date for the date range used for engagement-related fields, in ISO format. |
to | query string (ISO date) | The end date for the date range used for engagement-related fields, in ISO format. |
Note: if you want to get activities for certain people/accounts, all activities have an {Account}.id and {People}.id. Find the accounts/people you need by making a request to the corresponding endpoint and pass in the ids to the filter in your activity request.
Responses
A CSV file with one row per activity and one column per requested field, unless "format=json" was specified
Invalid request
Server error occurred
AccountLists
GET /accountlists
curl \
"https://api.engagio.com/api/v1/accountLists" \
-H "Authorization: Bearer engagio_v334asfsdfo3241ERqwefe"
var request = require('request');
request({
headers: {
'Authorization': 'Bearer engagio_v334asfsdfo3241ERqwefe',
'Content-Type': 'application/json'
},
uri: 'https://api.engagio.com/api/v1/accountLists',
method: 'GET'
}, function (err, res, body) {
var pJSON = JSON.parse(body);
console.log(pJSON)
})
The above command returns JSON structured like this:
[
{
"id": 213,
"name": "Accounts with Opps - Presentation/Demo Stage"
}
]
HTTP Request
GET https://api.engagio.com/api/v1/accountLists
The AccountLists endpoint returns a JSON blob that contains a list of account lists in Engagio.
Responses
A JSON blob with the name and id of each account list
Invalid request
Server error occurred
How to find an AccountList id outside of the API
While the new accountLists API may be the easiest way to access the list ID, the other way to get the list ID is through the Engagio web application UI -- if you select the account list from the box in the top left, then the account list ID shows up as a path component in the URL (see screenshot below).
API Schema Definitions
Field: Object
name: string
Name of the field - pass this to the endpoints that expect a field list.
label: string
Human-friendly label for the field
dataType: string
Data type of the field
pickListValues: object
cardinality: number
status: string
Is this a hidden, normal, or preferred field in the Engagio web application?
Filter: Object
field: string
operator: string
Possible Values: Equals, Does Not Equal, Contains, Does Not Contain, Begins With, Does Not Begin With, Ends With, Does Not End With, Greater Than, Greater Than or Equal To, Less Than, Less Than or Equal To, Between
values: string[], string
Example Filter {"field": "{Account}.sfdcId", "operator": "Equals", "values": ["0011a00000DpxW3AAJ"]}