NAV Navbar
cURL node.js
  • Introduction
  • Authentication
  • Accounts
  • People
  • Activities
  • AccountLists
  • API Schema Definitions
  • 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:

    1. Get Accounts
    2. Get People
    3. Get Activites
    4. Get Account Lists

    Getting a Token

    Email support@engagio.com to receive a token

    Authentication

    For authentication, there are two choices:

    1. Use basic authentication with your Engagio API token as the username and an empty password.

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