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
- 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_tokenwhich you can use in subsequent requests to continue retrieving data at the exact point where the previous response ended, and aprev_block_tokento indicate the previous page of data when you had already usednext_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_usagedevice_detailsdownload_inventoryinspectionslocation_services_statusterms_and_conditions_responsesmost_popular_appsuser_detailsusers_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) 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.comtojsmith%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
searchablefield is true in the response of /reports/<report_name>/field_info). The search matches an exact term ifexact termis 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_tokenvalue 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 theprev_block_tokenvalue.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_tokenURL parameter includes the value returned bynext_block_tokenfrom 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 theprev_block_tokenif 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_usagedevice_detailsdownload_inventoryinspectionslocation_services_statusterms_and_conditions_responsesmost_popular_appsuser_detailsusers_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/v2/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" } ] } }