PingOne Platform APIs

Reporting

You can use the reporting capability to generate reports containing user and MFA device details, using a number of device-related filters.

For example, you can generate a report listing all email devices or a report containing all of the devices whose phone number starts with a certain country code.

You can use synchronous requests to get back the matching data as entries in the JSON response or use asynchronous requests to have the data provided in a CSV or JSON file. Note that when using the synchronous approach, you may have to make multiple requests if there is a large amount of data.

The request for generating reports uses the dataExplorations endpoint:

{{apiPath}}/v1/environments/{{envID}}/dataExplorations

  • The data exploration objects created with the dataExplorations endpoint are saved only for a short time so you must send a POST request each time you want to generate a report.

  • You cannot call the dataExplorations endpoint more than once per 5 seconds for the same environment.

  • The database that serves as the source of the reports is updated once every fifteen minutes. So the content of a report may not reflect the exact device data at the time of generation.

  • When results are returned in files, the generated files are cached for two hours. During this period, if the results are requested again, the cached file is returned, rather than generating the report again. This applies both to the results for an existing dataExploration object and the results for any additional dataExploration object created with the exact same settings within this period.

MFA reports data model

Property Type Required Mutable Description

dataExplorationTemplate.id

String

Required

Immutable

The ID of the report template that should serve as the base for the report. Currently, the only supported value is db632bfd-7054-4bde-b108-a384aac2d513

deliverAs

String

Optional

Immutable

How the results should be returned. The valid values are ENTRIES (get the results as a collection of entries in the response) and ASYNC_FILE (get the results in a CSV or JSON file). If the parameter is not included, ENTRIES is used.

fields[]

Array

Optional

Immutable

The fields you want to include in the report. Array of name-value objects, where the name is always "name", for example, "fields":[{"name":"username"},{"name":"phone"}]. The values that can be included are: userId, environmentId, populationId, username, givenName, familyName, mfaEnabled, bypassUntil, userCreatedAt, userUpdatedAt, deviceId, deviceOrder, deviceNickname, deviceType, deviceStatus, deviceIntegrityStateCompromised, deviceIntegrityStateReason, deviceIntegrityStateTimestamp, deviceIntegrityStateAdvice, phone, extension, email, deviceBlocked, blockedAt, deviceLocked, lockExpiration, fidoBackupEligibility, fidoBackupState, fidoUserVerification,fidoMinPinLength, sdkVersion, manufacturer, deviceName, modelName, osType, osVersion, appId, appVersion, mobileUnitId, installedApplicationId, rpId, deviceCreatedAt, deviceUpdatedAt, lastDeviceTrxTime, serialNumber
Note that if you do not include the fields parameter, the report will include all of the fields available.

filter

String

Optional

Immutable

You can filter the results by: email, phone, deviceType, userId, or mfaEnabled. The filters are used with the operators eq and sw. eq requires an exact match (including case-sensitivity). sw ("starts with") provides greater flexibility by matching only part of the string and performing a check that is not case-sensitive. The sw option can ony be used with the filters email and phone. When using the deviceType filter, you can use any of the values listed for type in the "Device properties" table under MFA devices.
Examples: "filter": "(deviceType eq EMAIL)", "filter": "(phone sw 972)", "filter": "(mfaEnabled eq true)". If you do not include the filter parameter, the report will include all users and their devices.

sync

String

Optional

Immutable

Set to "true" if you are using the expand query parameter.

Getting the report results

You can receive the report data as entries in the JSON response or as a file (CSV or JSON).

There are a number of ways you can get the report results. The recommended approaches for the most common scenarios are as follows:

  • For cases where you anticipate a fairly small number of records in the results:

    • Run a POST request using the expand query parameter. This will create the dataExplorations object and also return the results as entries in the response. {{apiPath}}/v1/environments/{{envID}}/dataExplorations?expand=entries

      For more information on the use of the expand query parameter, refer to "Link expansion" under API requests.

  • For cases where you expect a large number of records, but would like to receive them as entries in the body of the response:

    1. Run a POST request to create the dataExplorations object.

    2. Run a GET request with /entries in the URL: {{apiPath}}/v1/environments/{{envID}}/dataExplorations/{{dataExplorationID}}/entries

    3. If there are too many results to include in one response, the _links section in the response will include a next object. Follow the next link, then using the same access token, run another GET request using the the next link as the URL.

    4. Continue until the response no longer includes a next object.

      For more information on pagination, refer to Paging and ordering collections.

  • For cases where you want to receive the results as a file:

    1. Run the request to create a report and get the results as a file: POST {{apiPath}}/v1/environments/{{envID}}/dataExplorations. In the body of the request, make sure that deliverAs is set to ASYNC_FILE.

    2. The response to the report creation request will include a status field whose value is IN_PROGRESS.

    3. Run the polling request GET {{apiPath}}/v1/environments/{{envID}}/dataExplorations/{{dataExplorationID}}, using the ID that was returned when you created the report, until the status field in the response equals SUCCESS.

    4. When the response contains the status SUCCESS, it will also include a link for downloading a zipped csv file, a link for downloading a zipped JSON file, and a password for opening the zip files. Use this information to download and unzip the report.

    5. The report itself is cached for two hours, but the links are good for only five minutes.

    6. If more than five minutes has elapsed from the time of the request that returned the links, get updated links by again running the request GET {{apiPath}}/v1/environments/{{envID}}/dataExplorations/{{dataExplorationID}} using the ID that was returned when you created the report.

    7. If more than two hours has elapsed since the report was created, run the report creation request again.

MFA reports errors

In addition to the general error codes, dataExplorations operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST /dataExplorations request references a report template that does not exist

Details: Could not find specified data exploration template. with target dataExplorationTemplate

400

REQUEST_FAILED or INVALID_REQUEST

INVALID_FILTER or INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request. for an invalid filter attribute, operator, or value; The request could not be completed. The request was malformed or invalid. for an unsupported filter combination

When and details

When: A POST /dataExplorations request supplies a filter attribute that the report template does not support, an unsupported filter operator, an invalid filter value, or a filter that mixes inner and outer filters in an OR clause

Details: The filter attribute was invalid or does not support filtering. with target attribute and a supportedAttributes inner error (detail code INVALID_FILTER), The filter operator was invalid or not supported. with target operator and a supportedOperators inner error when the field supports other operators (detail code INVALID_FILTER), The value provided is invalid. with target value (detail code INVALID_FILTER), or Unsupported filter combination with target filter (detail code INVALID_VALUE)

400

INVALID_REQUEST

INVALID_VALUE

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: A POST /dataExplorations request supplies a fields value whose format does not match the report template field format, or a deliverAs value that the template does not support

Details: Format is invalid with target format, or Unsupported delivery type with target deliverAs

403

ACCESS_FAILED

INSUFFICIENT_PERMISSIONS or None

Message: You do not have permissions or are not licensed to make this request. when the report template’s required permission is missing; The actor attempting to perform the request is not authorized. when the visualization permission for the operation itself is missing

When and details

When: The actor lacks the visualization:create:exploration permission (POST) or the visualization:read:exploration permission (GET), or lacks the permission that the report template requires, such as dir:read:user for the MFA devices report template

Details: You do not have permissions or are not licensed to make this request. (detail code INSUFFICIENT_PERMISSIONS) for a template permission denial. None for an operation permission denial.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: A GET /dataExplorations or GET /dataExplorations/{ID}/entries request references a report or environment that does not exist

Details: None

423

ACCESS_FAILED

INSUFFICIENT_PERMISSIONS

Message: The request could not be completed. You do not have access to this resource.

When and details

When: Access to the reporting resource has been revoked because of excessive usage

Details: Access to this resource has been revoked due to excessive usage. Please contact support to request review.

429

REQUEST_LIMITED

QUOTA_EXCEEDED

Message: The request could not be completed. A rate or quota limit was reached. Please try again later.

When and details

When: The environment has already reached the limit of one dataExplorations request per 5 seconds

Details: A retryAfter inner error giving the number of seconds to wait before retrying, for example retryAfter: 5 seconds