Reports API

Use the Reports API to run a report for your organization and return the data in a variety of formats. You can run the following reports:

  • App Usage
  • Device Details
  • Download Inventory
  • Inspection
  • Installed Apps
  • Location Services Status
  • Most Popular Apps
  • User Details
  • User by Groups

For a description of each report, see Running Reports.

To limit the data returned, you can filter on the value of one or more columns, specify a start and end date, and search for specific values.

Resources

GET /v2/reports/(report_name)/

Return Report Data

Requires administrator privileges. Authenticate as an Apperian administrator.

Returns the data for a specified report.

You can use additional URL parameters to filter the results, search for specific values, limit the number of results, and specify the output format.

Each report returns a fixed amount of data in blocks, so to retrieve the entire data set for a particular report you may need to send multiple requests. Every response includes a next_block_token which you can use in subsequent requests to continue retrieving data at the exact point where the previous response ended, and a prev_block_token to indicate the previous page of data when you had already used next_block_token.

URLs

Environment URL
North America https://na01ws.apperian.com/v2/reports/<report_name>
Europe https://eu01ws.apperian.eu/v2/reports/<report_name>

URL Parameters

report_name

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

  • app_usage
  • device_details
  • download_inventory
  • inspections
  • installed_apps
  • location_services_status
  • most_popular_apps
  • user_details
  • users_by_groups

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 if you want to go to the next page, or prev_block_token if you want to go to the previous page.
format

(Optional) Use this parameter to specify the report output format. If this parameter is not included, then the output is returned as JSON format by default. To return the results in other formats, use one of the following values:

  • csv: Returns the data as a CSV file.
<additional filter parameters>

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

Report Filter params
app_usage date (optional), platform (optional)
device_details form_factor (optional), platform (optional), jailbreak_status (optional), device_status (optional), disabled_by (optional)
download_inventory date (optional), form_factor (optional), platform (optional)
inspections date (optional)
installed_apps date (optional), platform (optional), download_source (optional)
location_services_status date (optional), status (optional)
most_popular_apps date (optional), platform (optional), download_type (optional)
user_details date (optional), role (optional), invite_status (optional), user_status (optional), disabled_by (optional)
users_by_groups date (optional), role (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.

count
(Optional) An integer value that limits the maximum number of rows the report can return.
search
(Optional) Enter any terms (separated by commas) that you want to search for in the results. The search only runs in fields that are searchable (i.e. the searchable field is true in the response of /reports/<report_name>/field_info). The search matches an exact term if exact term is true (in the previously mentioned response), otherwise it will return for any word that contains the term.

Header Parameter

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

Data Parameters

None

Example for Retrieving Report Data

Request

The following request returns the first page of data for the user_details report between the dates: 2017-11-29 and 2017-12-01, searching for “sm” and limiting the results to 100 at the most. Note the next_block_token value at the end of the request - you will include this in your next response to ensure going to the next page of data starts exactly where this one ended. If you wanted to go to the previous page you would use the prev_block_token value.

curl -X GET https://na01ws.apperian.com/v2/reports/user_details?date=2017-11-29,2017-12-01&search=sm&count=100 \
     --header "X-TOKEN: kEqMb_-2RlG6KmGaK-CZ_w"

Response

{
    "report": {
        "entries_returned": 100,
        "total_available": 150,
        "next_block_token": "acbdefgh1235",
        "report_name": "user_details",
        "end_of_data": false,
        "entries": [
            {
                "last_login": "2017-11-30 13:22:06",
                "user_status": "Disabled",
                "first_name": "John",
                "last_name": "Smith",
                "user_id": "jsmith",
                "disabled_by": "Admin",
                "disabled_on": "2017-12-01 13:22:19",
                "phone": "",
                "role": "User",
                "date": "2017-11-30 11:51:48",
                "invite_status": "Activated",
                "email": null
            },
            {
                "last_login": "N/A",
                "user_status": "Activated",
                "first_name": "Michael",
                "last_name": "Smithers",
                "user_id": "msmithers",
                "disabled_by": "N/A",
                "disabled_on": "N/A",
                "phone": "1111111111",
                "role": "Administrator",
                "date": "2017-11-30 11:36:20",
                "invite_status": "Activated",
                "email": null
            },
            ...
        ],
        "prev_block_token": "zxyvwk9876"
    }
}

Example for Continued Data Retrieval

Request

The following request returns the next page of data for user_details for the previous example, 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 report when navigating to the next page, or use the prev_block_token if navigating to the previous page.

curl -X GET "https://na01ws.apperian.com/v2/reports/user_details?date=2017-11-29,2017-12-01&search=sm&count=100&
     block_token=acbdefgh1235 --header "X-TOKEN: kEqMb_-2RlG6KmGaK-CZ_w"

Response

{
    "report": {
        "entries_returned": 50,
        "total_available": 150,
        "next_block_token": "gjkbdfjgdgg",
        "report_name": "user_details",
        "end_of_data": true,
        "entries": [
            {
                "last_login": "2017-11-30 13:22:06",
                "user_status": "Disabled",
                "first_name": "Rob",
                "last_name": "Smidt",
                "user_id": "rsmidt",
                "disabled_by": "Admin",
                "disabled_on": "2017-12-01 18:22:19",
                "phone": "",
                "role": "User",
                "date": "2017-11-30 11:51:48",
                "invite_status": "Activated",
                "email": null
            },
            {
                "last_login": "N/A",
                "user_status": "Activated",
                "first_name": "Dimitry",
                "last_name": "Smolensky",
                "user_id": "dsmolensky",
                "disabled_by": "N/A",
                "disabled_on": "N/A",
                "phone": "1111111111",
                "role": "Administrator",
                "date": "2017-11-30 19:36:20",
                "invite_status": "Activated",
                "email": null
            },
            ...
        ],
        "prev_block_token": "jkadbkjdgg3erfv"
    }
}
GET /v2/reports/

Return a List of Available Data Reports

Requires administrator privileges. Authenticate as an Apperian administrator.

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

URLs

Environment URL
North America https://na01ws.apperian.com/v2/reports
Europe https://eu01ws.apperian.eu/v2/reports

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 reports and associated information.

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

Response

{
  "app_information": {
      "description": "Lists all app versions uploaded to Apperian with information about the platform, minimum
          supported operating system, version, and architecture.",
      "fields": [
          {
              "sortable": true,
              "name": "app_name",
              "searchable": true,
              "exact_match": false,
              "hidden_by_default": false,
              "type": "string",
              "description": "App Name"
          },
          {
              "sortable": false,
              "name": "platform",
              "searchable": false,
              "exact_match": false,
              "hidden_by_default": false,
              "type": "integer",
              "description": "Platform"
          },
          {
              "sortable": false,
              "name": "min_os_version",
              "searchable": false,
              "exact_match": false,
              "hidden_by_default": false,
              "type": "string",
              "description": "Minimum OS version"
          },
          {
              "sortable": true,
              "name": "version_number",
              "searchable": true,
              "exact_match": false,
              "hidden_by_default": false,
              "type": "string",
              "description": "Version Number"
          },
          {
              "sortable": false,
              "name": "architecture",
              "searchable": false,
              "exact_match": false,
              "hidden_by_default": false,
              "type": "integer",
              "description": "Architecture"
          },
          {
              "sortable": true,
              "name": "date",
              "searchable": false,
              "exact_match": false,
              "hidden_by_default": false,
              "type": "date_time",
              "description": "Installed Date"
          }
      ],
      "default_sort": [
          {
              "field": "date",
              "asc_order": false
          }
      ],
      "path": "/v2/reports/app_information",
      "filter_params": [
          {
              "name": "date",
              "required": false,
              "type": "date_range",
              "description": "Installed Date"
          },
          {
              "name": "platform",
              "required": false,
              "possible_values": [
                  {
                      "value": 2,
                      "label": "Android"
                  },
                  {
                      "value": 1,
                      "label": "iOS"
                  },
                  {
                      "value": 4,
                      "label": "Windows Phone"
                  },
                  {
                      "value": 5,
                      "label": "Windows"
                  }
              ],
              "type": "integer",
              "description": "Platform"
          },
          {
              "name": "architecture",
              "required": false,
              "possible_values": [
                  {
                      "value": 1,
                      "label": "32-bit"
                  },
                  {
                      "value": 0,
                      "label": "64-bit"
                  },
                  {
                      "value": 2,
                      "label": "32-bit, 64-bit"
                  }
              ],
              "type": "integer",
              "description": "Architecture"
          }
      ]
  },
  ...
}
GET /v2/reports/(report_name)/field_info/

Return Report Information

Requires administrator privileges. Authenticate as an Apperian administrator.

Returns information about the columns, default sorting, and additional parameters that can be included in the report (but no actual data). Depending on the particular report, 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/v2/reports/<report_name>/field_info
Europe https://eu01ws.apperian.eu/v2/reports/<report_name>/field_info

URL Parameters

report_name

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

  • app_usage
  • device_details
  • download_inventory
  • inspections
  • installed_apps
  • location_services_status
  • most_popular_apps
  • user_details
  • users_by_groups

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 user_details report, which includes a list of data columns and additional filter parameters.

curl -X GET "https://na01ws.apperian.com/v1/report/user_details/field_info
     --header "X-TOKEN: eTg8ktZXRqKIBJTHunwP6A"

Response

{
    "user_details": {
        "description": "Lists details about all the Apperian users defined for your company",
        "fields": [
            {
                "sortable": true,
                "name": "first_name",
                "searchable": true,
                "exact_match": false,
                "hidden_by_default": false,
                "type": "string",
                "description": "First Name"
            },
            {
                "sortable": true,
                "name": "last_name",
                "searchable": true,
                "exact_match": false,
                "hidden_by_default": false,
                "type": "string",
                "description": "Last Name"
            },
            {
                "sortable": false,
                "name": "user_id",
                "searchable": true,
                "exact_match": true,
                "hidden_by_default": false,
                "type": "string",
                "description": "User ID"
            },
            {
                "sortable": false,
                "name": "email",
                "searchable": true,
                "exact_match": true,
                "hidden_by_default": false,
                "type": "string",
                "description": "Email"
            },
            {
                "sortable": false,
                "name": "role",
                "searchable": false,
                "exact_match": false,
                "hidden_by_default": false,
                "type": "string",
                "description": "Role"
            },
            {
                "sortable": false,
                "name": "phone",
                "searchable": true,
                "exact_match": false,
                "hidden_by_default": false,
                "type": "string",
                "description": "Phone"
            },
            {
                "sortable": true,
                "name": "date",
                "searchable": false,
                "exact_match": false,
                "hidden_by_default": false,
                "type": "date_time",
                "description": "Created"
            },
            {
                "sortable": false,
                "name": "invite_status",
                "searchable": false,
                "exact_match": false,
                "hidden_by_default": false,
                "type": "string",
                "description": "Invite Status"
            },
            {
                "sortable": false,
                "name": "user_status",
                "searchable": false,
                "exact_match": false,
                "hidden_by_default": false,
                "type": "string",
                "description": "User Status"
            },
            {
                "sortable": true,
                "name": "disabled_on",
                "searchable": false,
                "exact_match": false,
                "hidden_by_default": true,
                "type": "date_time",
                "description": "Disabled On"
            },
            {
                "sortable": false,
                "name": "disabled_by",
                "searchable": false,
                "exact_match": false,
                "hidden_by_default": true,
                "type": "string",
                "description": "Disabled By"
            },
            {
                "sortable": true,
                "name": "last_login",
                "searchable": false,
                "exact_match": false,
                "hidden_by_default": false,
                "type": "date_time",
                "description": "Last Login"
            }
        ],
        "default_sort": [
            {
                "field": "last_name",
                "asc_order": true
            },
            {
                "field": "first_name",
                "asc_order": true
            }
        ],
        "path": "/v2/reports/user_details",
        "filter_params": [
            {
                "name": "date",
                "required": false,
                "type": "date_range",
                "description": "Created"
            },
            {
                "name": "role",
                "required": false,
                "possible_values": [
                    {
                        "value": 1,
                        "label": "User"
                    },
                    {
                        "value": 5,
                        "label": "Administrator"
                    },
                    {
                        "value": 7,
                        "label": "User Manager"
                    },
                    {
                        "value": 6,
                        "label": "App Manager"
                    },
                    {
                        "value": 8,
                        "label": "Developer"
                    }
                ],
                "type": "integer",
                "description": "Role"
            },
            {
                "name": "invite_status",
                "required": false,
                "possible_values": [
                    {
                        "value": 0,
                        "label": "Activated"
                    },
                    {
                        "value": 1,
                        "label": "Password not set"
                    },
                    {
                        "value": 2,
                        "label": "Invited"
                    }
                ],
                "type": "integer",
                "description": "Invite Status"
            },
            {
                "name": "user_status",
                "required": false,
                "possible_values": [
                    {
                        "value": 1,
                        "label": "Activated"
                    },
                    {
                        "value": 0,
                        "label": "Disabled"
                    },
                    {
                        "value": 2,
                        "label": "Invited"
                    }
                ],
                "type": "integer",
                "description": "User Status"
            },
            {
                "name": "disabled_by",
                "required": false,
                "possible_values": [
                    {
                        "value": 0,
                        "label": "Admin"
                    },
                    {
                        "value": 1,
                        "label": "System (non compliance)"
                    },
                    {
                        "value": 2,
                        "label": "System (invalid logins)"
                    },
                    {
                        "value": 3,
                        "label": "System (lockout threshold)"
                    }
                ],
                "type": "integer",
                "description": "Disabled By"
            }
        ]
    }
}