Generating Biometric Reports with the Reporting API

Voice biometrics is a regulated, auditable activity. When a speaker is rejected, a fraud team needs to know what happened; when a regulator asks for evidence, you need the record of every enrollment and verification; and when an operations team tunes thresholds, it needs the outcomes to tune against. The Reporting API is how you get that data. It works the same way for every report: find out which reports exist, learn what fields and filters a report offers, then generate it with the filters, sort order, and page you want. This article walks through that workflow with a worked example.

Scope. This article covers the Voice Biometrics reports, served by the Biometric Reporting REST API. Usage reports for the speech services use a different API, described in Licensing & Usage Reporting. For the voice biometrics operations that these reports describe, see Voice Biometrics Concepts and Integration Flows. The headers every request needs are in API Access, Authentication and Required Headers.

The three calls

Before you start

Biometric reports are served by the Biometric Reporting API, which is exposed on its own hostname: reporting-bio-api followed by your hostnameSuffix, for example reporting-bio-api.example.com. If DNS is not configured, add a hosts file entry for it. See Setting Up a Deployment.

Every request needs the x-deployment-id, x-operator-id, and x-scopes headers, and can carry an x-correlation-id. For the Reporting API, the scope is REPO. If you give each call your own correlation ID, you can match the results to your own transactions.

Step 1: Find the report you need

Call GetReportList to see what is available:

The response lists each report with its category:

Reports fall into categories such as Transaction (what happened) and Identity (the state of enrolled identities). Each entry can also carry a ReportDescription. The rest of this article uses BiometricOperation, which records the individual biometric operations such as enrollment and verification calls.

Step 2: Learn the fields and filters

Call GetReportDetails with the report name:

The response has two parts. reportFieldMetadatas lists the fields in each row of the report, with their types. reportFieldFilterMetadatas lists the fields you can filter on and the attributes each filter takes.

The list is abridged here. Read it as follows: the report has the fields shown, and you can filter by a time range (From and To) on StartTime and EndTime, or by identity (Value with an optional LogicalOperator of Equal or NotEqual). In other words, you can ask for the biometric operations of one identity within a time range. The field name AssureIdentitySymbol is the identity symbol of the identity that the operation was performed for.

Step 3: Generate the report

Post a JSON body to GenerateReport. Only ReportName is required.

Example: one identity, newest first

The response contains the report name, a timestamp, how long generation took, the rows in ReportDataJson, and the sort and pagination that were applied:

The generation time is a duration object with many equivalent representations; the totalMilliseconds and totalSeconds values are the easiest to use. The rows are abridged.

Example: a time range and a different sort

Filters combine: every filter you list is applied. This body returns the operations of one identity that ended within a time window, sorted by status:

The same approach works for every report: call GetReportDetails, read the filters it offers, and build the ReportFieldFilters object from them.

Filters that take several values

Some filters accept a list of values with a logical operator. The API reference shows a BiometricSession report filtered to sessions that ended in one of several statuses:

Always confirm the attribute names and valid values for the report you are using with GetReportDetails.

Paging through large results

Pagination splits a result into virtual pages. Set perPage to the number of rows you want in each page, request page 0 first, then increase page by one for each following request. The response repeats the pagination that was applied, so you can confirm the page size the platform used.

Using reports well

• Audit one person. Filter BiometricOperation on the identity symbol and sort by StartTime to see every enrollment and verification attempt, newest first.
• Investigate a failure. Look at OperationStatus, OperationErrorCode, and OperationInfo for the operation, and match it to your own logs with the CorrelationId you supplied.
• Tune thresholds. Report on outcomes over a period, then review the thresholds with the Voice Biometrics Configuration Reference.
• Keep windows bounded. Use a time range and pagination, instead of requesting everything at once.

Errors

The API specification declares the HTTP status codes 400, 401, 404, and 500. Errors are returned as a JSON object with the fields Error, ErrorCode, HttpStatusCode, HttpErrorCode, Message, and MessageData. Read Message first.

Troubleshooting

Related Articles

• Biometrics Functional Overview & API Integration
• Active Voice Biometrics Product Architecture
• Active Voice Biometrics Product Information
• Capacity Private Cloud Containerized Microservices
• Setting Up a Deployment
• Licensing & Usage Reporting
• API Overview