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 - Lists usage information tracked for all apps with the App Usage policy applied. The report includes the name, ID, and version of the app, date and time of use, and details about the user and device. Note: The App Usage report is automatically filtered to display data from the previous week, and includes data from the past 6 months. You can use the Feeds API to view data older than 6 months.
  • Download Activity - Lists an entry for every time a user/device downloaded any version of a native app. For example, if a user downloads the same app 5 times, 5 entries would appear in the list for that user. Note: The report lists downloads of the App Catalog, but the initial download of an App Catalog is not counted until a user has logged into the App Catalog on the device; subsequent downloads of App Catalog updates are counted without requiring the user to log in.
  • Download Activity (Latest Version) - Reports each time the current version of each app is downloaded. The data in this feed may change over time. For example, if a user initially downloads an app, then later downloads a new version of the same app, the feed would only display an event for the new (most recent) version of the app for that user. Additionally, if you then upload another new version of the app, and a different user downloads this new version, the feed would only display an event for the new user downloading the most recent version (the previous event for the other user would disappear).
  • Login Activity - Lists attempts to log in to any app managed by Apperian, including the App Catalog. Use this report to identify login failures or difficulties.
  • Signing Activity - Lists information about apps that were signed using the Admin Portal, including the name, version, and platform of the application, the user who signed it, the date and time it was signed, and the name of the certificate with which it was signed.
  • Password Change Activity - Lists the date and time of any changes to an Apperian administrator’s password. This report logs all administrator password changes, including changes made when an administrator is prompted to reset an expired password, and changes initiated by the administrator on the My Account page in the Admin Portal or through the Forget Password? link in the App Catalog.
  • Direct Install Activity - Lists information about apps that were downloaded via a direct install URL rather than through the App Catalog.

Resources

GET /v1/feeds/

Return a List of Available Data Feeds

Requires administrator privileges. Authenticate as an Apperian 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": "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 Apperian 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
  • download_activity_latest_versions
  • 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"
          },
          "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 Apperian 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
  • download_activity_latest_versions
  • 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.

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",
            "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",
            "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",
            "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",
            "email": null,
            "device_id": "00:00:00:00:00:00"
        }
    ],
    "feed_name": "app_usage_activity",
    "rows_returned": 2,
    "next_block_token": "AU5tck1XbS9WMVNEdXJBM05BZUdwdmc9PQ=="
}