Known Faces report

Start here

This guide presents a technical overview of Onfido’s Known Faces report.

Introduction

The Known Faces report compares a specific applicant’s likeness in their most recently captured media (a live photo, live video or motion capture) to media from previous applicants in your Onfido account database. The report alerts you to faces which have already been through your identity verification flow, highlighting potential repeat identity fraud attempts, or identifying users who may have forgotten they already registered with you, in order to help them recover their accounts.

Known Faces will only return matches against applicants that are not the subject of the current report. In other words, the live photos, live videos or motion captures associated with a specific applicant ID will not be compared with each other.

Known Faces Report task

The applicant object that the Known Faces report is run against must contain a live photo, live video or motion capture in order for the report to run successfully. Otherwise, the report will be automatically withdrawn and return an error in the properties attribute.

As a result, it is highly recommended the Known Faces report always be run in conjunction with a Document report and a Facial Similarity report. Although it can be requested on its own, a Known Faces report will only match against applicants who have previously gone through a Facial Similarity report.

Similar to all our reports, to run a Known Faces report, it should be added into your Studio workflow. This can be done by adding the Known Faces Report task from the Studio Workflow Builder. A Known Faces Report task should always follow the path of a Face Capture task and a Facial Similarity Report task, in order to extract the appropriate task input data and make the comparison. The workflow should also include a Document Report task.

Below you will find an illustrated example of a Studio workflow running a Known Faces report:

More information about report tasks can be found in our Studio Product Guide.

Report logic

The Known Faces report will return any matching applicant IDs as entries inside a matches array in the properties attribute. Each applicant ID has a corresponding score and media type (for example live_photos, live_videos or motion_captures), as well as the corresponding UUID for that media type. For example, the live photo or live video ID.

The score attribute is a floating point number between 0 and 1 that expresses how similar the two faces are, where 1 is a perfect match.

Known Faces fuzzy name matching allows you to distinguish and filter between repeat genuine users and repeat fraudsters by determining the similarity between applicant names. A suspected field returns a true/false value to determine the risk of the match from the applicant names. Only matches where the suspected field is true for at least one of the matches found will return a consider result for the Known Faces report. Please note that fuzzy matching is not enabled by default. Get in touch with Client Support if you intend to activate this feature.

The Known Faces report includes a breakdown property containing the following attributes:

Breakdown	Description
previously_seen_faces	An object asserting whether the applicant's most recent facial media (live photo, live video or motion capture) matches any other media already in your Onfido account database. Only matches where the suspected field is true will be considered.
image_integrity	An object asserting whether the uploaded live photo, live video or motion capture and the content contained within it were of sufficient quality to perform a face comparison.

If matches are found and any of them are suspected, the report result will be consider. Conversely, if none of the matches are suspected, the result will be clear.

More details regarding the structure of the Known Faces report and an example result can be found in our API reference documentation.

Known Faces Report task results

If you wish to obtain the specific outputs from the Known Face Report task via the Onfido API (for example, the overall report result or breakdown results), you can manage this by configuring the Workflow Output in the Studio Workflow Builder. You can also retrieve all associated output data from a Known Faces report.

You can refer to our Studio product guide for more information on Workflow Output configuration. Once set up, the output can be consumed by making a Retrieve Workflow Run call to the Onfido API. Report results are found in the output property.

Workflow run results can also be accessed on the "Results" tab of your Studio Dashboard.

Known Faces and deleted applicants

The Known Faces report will not return matches against any permanently deleted applicants. If you delete an applicant from your Onfido account database, any future verification check by this individual will create a new applicant profile, and if combined with a Known Faces report, no matches will be returned because no data would be available to match against.

You can read more about deleting applicants in our API reference documentation, as well is in our data deletion policy.

What to do with matches

For any Known Faces matches, we recommend that you review them in-house, to make sure you aren't rejecting genuine users who were incorrectly flagged (customers who may have forgotten they already registered with you, for example).

To help determine whether a returned match represents a fraudster or a genuine user, fuzzy name matching can be enabled on your account. This will differentiate between applicants with similar names, and applicants that have matched where the names do not match. Applicants detected with different names are flagged in the match suspected field.

You can read more about fuzzy name matching in our API documentation.

If this feature is not activated, we recommend you build some internal logic to compare the name of matches to the original applicants.

Retries with Known Faces

During an identity verification flow, a customer may be asked to retry or resubmit a live photo, live video or motion capture, perhaps due to poor image quality.

It is highly recommended that Known Faces retries are configured with the same applicant object. If there are multiple live captures associated with a specific applicant ID, these will not be compared with each other, therefore the applicant will not be considered a match.

If, on the other hand, a new applicant object is created for each retry, this means that the live photos, live videos or motion captures associated with these additional applicant IDs will be compared and matched with the original applicant object media. In this case, we recommend that you use Known Faces fuzzy name matching, or you can also check in your own database whether the applicant ID in the match corresponds to the same unique user, and ignore those matches.