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:

https://{{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, 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")"<br>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}}/environments/{{envID}}/dataExplorations?expand=entries

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

  • 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}}/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, ordering, and filtering 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}}/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}}/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}}/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.