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).

Accountlists

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"]}