Feeds API

Use the Feeds API to retrieve raw data about app usage, users, and access within your organization; the data is returned in JSON format. Feeds are similar to the reports available in the Admin Portal, but can be consumed by automated tasks.

Each feed returns a fixed amount of data in blocks, so to retrieve the entire data set for a particular feed you may need to send multiple requests. The size of each block may be different for different feeds. To limit the data returned, you can filter on the value of one or more columns. You can also specify a start and end date to return data within a certain date range only.

The following feeds are available:

  • App Usage Activity
  • Download Activity
  • Login Activity
  • Signing Activity
  • Password Change Activity
  • Direct Install Activity

Resources

GET /v1/feeds/

Return a List of Available Data Feeds

Requires administrator privileges. Authenticate as an EASE administrator.

Returns a list of all feed names and detailed information about each feed, including columns and any additional parameters that can be included in the feed.

URLs

Environment URL
North America https://na01ws.apperian.com/v1/feeds
Europe https://eu01ws.apperian.eu/v1/feeds

URL Parameters

None

Header Parameter

X-TOKEN
(Required) API token or User token (POST /users/authenticate). For more information, see Authentication.

Data Parameters

None

Example

Request

The following request returns a list of all available feeds and associated information.

curl -X GET https://na01ws.apperian.com/v1/feeds --header "X-TOKEN: kEqMb_-2RlG6KmGaK-CZ_w"

Response

{
    "app_usage_activity": {
        "description": "Provides tracked usage information for apps with the App Usage policy applied.",
        "fields": [
            {
                "description": "App Name",
                "type": "string",
                "name": "app_name"
            },
            {
                "description": "App ID",
                "type": "string",
                "name": "app_id"
            },
            {
                "description": "Version",
                "type": "string",
                "name": "version"
            },
            {
                "description": "Email",
                "type": "string",
                "name": "email"
            },
            {
                "description": "First Name",
                "type": "string",
                "name": "first_name"
            },
            {
                "description": "Last Name",
                "type": "string",
                "name": "last_name"
            },
            {
                "description": "User ID",
                "type": "string",
                "name": "user_id"
            },
            {
                "description": "Date",
                "type": "date",
                "name": "date"
            },
            {
                "description": "Device ID",
                "type": "string",
                "name": "device_id"
            },
            {
                "description": "IP address",
                "type": "string",
                "name": "ip_address"
            },
            {
                "description": "Device name",
                "type": "string",
                "name": "device_name"
            }
        ],
        "path": "/v1/feeds/app_usage_activity",
        "filter_params": [
            {
                "name": "start_date"
                "required": false,
                "type": "date",
                "description": "Start Date"
            }
        ]
    },
    ...
}
GET /v1/feeds/(feed_name)/field_info

Return Feed Information

Requires administrator privileges. Authenticate as an EASE administrator.

Returns information about the columns and additional parameters that can be included in the feed (but no actual data). Depending on the particular feed, additional parameters may be included; see filter_params in the response to determine which parameters can be used (they are also documented below).

URLs

Environment URL
North America https://na01ws.apperian.com/v1/feeds/<feed_name>/field_info
Europe https://eu01ws.apperian.eu/v1/feeds/<feed_name>/field_info

URL Parameters

feed_name

(Required) Name of the data feed. Enter the name exactly as it appears in this list:

  • app_usage_activity
  • download_activity
  • login_activity
  • signing_activity
  • password_change_activity
  • direct_install_activity

Header Parameter

X-TOKEN
(Required) API token or User token (POST /users/authenticate). For more information, see Authentication.

Data Parameters

None

Example

Request

The following request returns detailed information about the app_usage_activity feed, which includes a list of data columns and additional filter parameters.

curl -X GET "https://na01ws.apperian.com/v1/feeds/app_usage_activity/field_info \
     --header "X-TOKEN: eTg8ktZXRqKIBJTHunwP6A"

Response

{
  "app_usage_activity": {
      "fields": {
          "first_name": {
              "type": "string",
              "description": "First Name"
          },
          "last_name": {
              "type": "string",
              "description": "Last Name"
          },
          "user_id": {
              "type": "string",
              "description": "User ID"
          },
          "app_name": {
              "type": "string",
              "description": "App Name"
          },
          "app_id": {
              "type": "string",
              "description": "App ID"
          },
          "device_name": {
              "type": "string",
              "description": "Device name"
          },
          "version": {
              "type": "string",
              "description": "Version"
          },
          "date": {
              "type": "date",
              "description": "Date"
          },
          "ip_address": {
              "type": "string",
              "description": "IP address"
          },
          "email": {
              "type": "string",
              "description": "Email"
          },
          "device_id": {
              "type": "string",
              "description": "Device ID"
          }
      },
      "path": "/v1/feeds/app_usage_activity",
      "filter_params": [
          {
              "name": "start_date",
              "required": false,
              "type": "date",
              "description": "Start Date"
          }
      ],
      "description": "App launch events, for apps wrapped with the App Usage policy"
  }
}
GET /v1/feeds/(feed_name)/

Return Feed Data

Requires administrator privileges. Authenticate as an EASE administrator.

Returns the raw data contained in a specified feed.

Each feed returns a fixed amount of data in blocks, so to retrieve the entire data set for a particular feed you may need to send multiple requests. Every response includes a block_token which you can use in subsequent requests to continue retrieving data at the exact point where the previous response ended.

URLs

Environment URL
North America https://na01ws.apperian.com/v1/feeds/<feed_name>
Europe https://eu01ws.apperian.eu/v1/feeds/<feed_name>

URL Parameters

feed_name

(Required) Name of the data feed. Enter the name exactly as it appears in this list:

  • app_usage_activity
  • download_activity
  • login_activity
  • signing_activity
  • password_change_activity
  • direct_install_activity

Note

When including more than one of the following parameters in a request, precede the first parameter with ? and subsequent parameters with &.

block_token
(Optional) Include this parameter to retrieve data beginning at the exact point where the previous response ended. The token value can be found in the response under next_block_token.
<additional filter parameters>

(Optional) Some additional parameters may be included. The specific additional parameters appear under filter_params when you return /feeds/<feed_name>/field_info, and they are also documented below.

The start_date parameter is present in every feed. It is a date in ISO 8601 format (e.g. YYYY-MM-DD) which filters out any row of data before that date.

Report Filter params
app_usage_activity
start_date (optional)
download_activity
start_date (optional)
login_activity
start_date (optional)
signing_activity
start_date (optional)
password_change_activity
start_date (optional)
direct_install_activity
start_date (optional)

Note

If column values include any special characters, they need to be URL encoded. For example, change jsmith@example.com to jsmith%40example.com. For an ASCII encoding reference, see HTML URL Encoding Reference.

Header Parameter

X-TOKEN
(Required) API token or User token (POST /users/authenticate). For more information, see Authentication.

Data Parameters

None

Example for Retrieving Feed Data

Request

The following request returns the first block of raw data for the app_usage_activity feed starting on the date: 2017-11-29. Note the next_block_token value at the end of the request - you will include this in your next response to ensure the block of data starts exactly where this one ended.

curl -X GET https://na01ws.apperian.com/v1/feeds/app_usage_activity?start_date=2017-11-29 \
     --header "X-TOKEN: kEqMb_-2RlG6KmGaK-CZ_w"

Response

{
    "end_of_data": true,
    "rows": [
        {
            "first_name": "James",
            "last_name": "Black",
            "user_id": "james_black",
            "app_name": "My app",
            "app_id": "org.my.app",
            "device_name": "nexus",
            "version": "0.3",
            "date": "2017-11-29T09:20:25.774804+00:00",
            "ip_address": "10.40.40.180",
            "email": null,
            "device_id": "00:00:00:00:00:00"
        },
        {
            "first_name": "James",
            "last_name": "Black",
            "user_id": "james_black",
            "app_name": "My app",
            "app_id": "org.my.app",
            "device_name": "nexus",
            "version": "0.3",
            "date": "2017-11-30T10:30:16.225237+00:00",
            "ip_address": "10.40.40.180",
            "email": null,
            "device_id": "00:00:00:00:00:00"
        }
    ],
    "feed_name": "app_usage_activity",
    "rows_returned": 2,
    "next_block_token": "AUxqNUMvN1RPZDRWWXFKUG5NZUY2dEE9PQ=="
}

Example for Continued Data Retrieval

Request

The following request returns the first block of raw data for app_usage_activity from the date 2017-11-29, continuing from the exact point where the previous request ended. Note here that the block_token URL parameter includes the value returned by next_block_token from the end of the previous example. Repeat this request until you have retrieved all data from the feed.

curl -X GET "https://na01ws.apperian.com/v1/feeds/app_usage_activity?start_date=2017-11-29&block_token=AUxqNUMvN1RPZDRWWXFKUG5NZUY2dEE9PQ --header "X-TOKEN: kEqMb_-2RlG6KmGaK-CZ_w"

Response

{
    "end_of_data": true,
    "rows": [
        {
            "first_name": "James",
            "last_name": "Black",
            "user_id": "james_black",
            "app_name": "My app",
            "app_id": "org.my.app",
            "device_name": "nexus",
            "version": "0.3",
            "date": "2017-11-29T09:20:35.774804+00:00",
            "ip_address": "10.40.40.180",
            "email": null,
            "device_id": "00:00:00:00:00:00"
        },
        {
            "first_name": "James",
            "last_name": "Black",
            "user_id": "james_black",
            "app_name": "My app",
            "app_id": "org.my.app",
            "device_name": "nexus",
            "version": "0.3",
            "date": "2017-11-30T10:40:18.156145+00:00",
            "ip_address": "10.40.40.180",
            "email": null,
            "device_id": "00:00:00:00:00:00"
        }
    ],
    "feed_name": "app_usage_activity",
    "rows_returned": 2,
    "next_block_token": "AU5tck1XbS9WMVNEdXJBM05BZUdwdmc9PQ=="
}