v10 Core APIs - Integration Overview

Learn how to integrate 3D Liveness, 3D Enrollment, 3D:3D Re-Verification, 3D:2D Photo ID Matching, and ID Scanning into Your Team's Application.


Overview

Launching the FaceTec UI begins by using the FaceTec Device SDK APIs to start the User Interaction with FaceTec. For instance, startLiveness(...) is called to start a 3D Liveness Check.

At various points during the User Interaction with the FaceTec UI, FaceTec will invoke the onSessionRequest function in Your Team's SessionRequestProcessor.

onSessionRequest is defined in Your Team's Code and is passed a sessionRequestBlob (String) that Your Team's Implementation is responsible for sending to Your Team's Backend Webservice.

Once sessionRequestBlob is received, Your Team's Webservice then calls FaceTec Server's /process-request API, passing it the sessionRequestBlob.

FaceTec Server will process the sessionRequestBlob and will respond with a responseBlob (String), which Your Code is responsible for sending back down to Your SessionRequestProcessor Code.

Finally, Your SessionRequestProcessor calls the processResponse function with the responseBlob.

Security

FaceTec's #1 priority is Security, with Usability & Compatibility as a close #2.

FaceTec sends information related to Security and Usability in each Session Request Blob, and multiple calls to /process-request will be made during the course of any User Interaction with FaceTec.

Over time, FaceTec will leverage improvements to the contents of Session Request Blobs and Response Blobs to improve Security (and Usability), in an effort to continue to prevent Fraudsters and Bad Actors from reverse-engineering and attempting to exploit how FaceTec prevents Presentation Attacks and Camera Feed Injection Attacks (see information about attack types here).

FaceTec User Interactions & Launch IDs

A User Interaction with FaceTec starts when Your Team's Code calls one of the start functions in the FaceTec Device SDK.

When a User Interaction starts and the FaceTec UI is launched, an internal UUID is generated called a Launch ID.

The Launch ID is returned in the FaceTec Server's API Responses and stored to Your Team's FaceTec Database in the Database Entries associated with the User Interaction.

FaceTec recommends storing Launch IDs in Your Application's Backend and Database for Tracking Users, so Your Team has references to all Specific User Interactions with FaceTec.

In FaceTec's Code and Database Implementations, Launch ID is stored and returned as launchId.

User Interaction Completion

When the User Interaction with FaceTec is completed, Your Team's Device-Side Code receives a FaceTecSessionResult, which has a FaceTecSessionStatus Enumeration.

When the User Interaction with FaceTec is completed, FaceTec is done processing, and Your Team's Code and Business Logic can decide the next step for the User.

Evaluating Intermediate Results (3D Liveness, 3D Enrollment, 3D:3D Re-Verification)

FaceTec's APIs are not designed to allow User Experience or Business Logic Changes or Decisions to be made during a User Interaction in these modes.

This is because 98-99% of Users who start the FaceTec UI will eventually prove 3D Liveness. There are no dynamic decisions that need to be made while a User is interacting with the FaceTec UI, and no capability offered by FaceTec to change behaviors about the 3D Face Scanning Process while the User is interacting with the FaceTec UI.

Once the User Interaction with FaceTec is completed, Your Code will evaluate how to handle the result of the User Interaction.

Evaluating Intermediate Results (ID Scanning)

Unlike 3D Face Scanning, FaceTec's ID Scan is designed to allow for evaluation of ID Scan Results and customizing ID Scan Behavior after each Individual Step of the ID Scan Process.

Evaluating Final Results and Triggering Business Logic

After the User Interaction with FaceTec is complete, Your Team's Business Logic can be invoked to decide where to send the User. Your Team will use the Launch ID stored in Your Team's FaceTec Database to trigger Business Logic and the next steps for Users.

3D Liveness, 3D Enrollment, 3D:3D Re-Verification - Validating Success

The vast majority of Users who complete a User Interaction with FaceTec will Successfully Prove 3D Liveness, and if performing 3D:3D Re-Verification, will be able to perform a 3D FaceScan that Matches the Enrolled 3D FaceMap at >1/125,000,000 FAR (Match Level 15).

For 3D Liveness, to check that the User has Successfully Proven 3D Liveness, please use the launchId parameter to check the Session Table/Collection for success == true in Your Team's FaceTec Database.

For 3D Enrollment, to check that the User has Successfully Proven 3D Liveness and the Liveness Proven 3D FaceMap was successfully stored to the database, please use the launchId parameter to check the Session Table/Collection for success == true in Your Team's FaceTec Database.

For 3D:3D Re-Verification, to check that the User has Successfully Proven 3D Liveness and that the User Matched the 3D Enrollment at >1/125,000,000 FAR (Match Level 15), please use the launchId parameter to check the Session Table/Collection for success == true in Your Team's FaceTec Database.

3D:2D Photo ID Matching & ID Scan Only - Validating Success

The vast majority of Users who complete a User Interaction with FaceTec will Successfully Prove 3D Liveness and/or be able to complete the Full ID Scan Process. 

For 3D:2D Photo ID Matching, please use the launchId parameter to check the Session Table/Collection for success == true in Your Team's FaceTec Database. Please note, that in this mode, success can only be true if the User has Successfully Proven 3D Liveness. The ID Scan Portion also incorporates Your Team's Customizable Logic for evaluating ID Scan Results and proceeding Users through their ID Scan. However, please note that the User completing an ID Scan does not necessarily mean the ID Scan Portion of the User Interaction is "successful". This is because FaceTec does not "Authenticate" Documents (more info here) -- instead, FaceTec provides back a wide variety of signals, including 3D:2D Matching Results, OCR Results, NFC Results, Barcode Results, and Document Anti-Spoof & Anti-Tampering Results, allowing Your Team to decide the Logic and Checks that work best for Your Team's Use Case.

For ID Scan Only, please use the launchId parameter to check the Session Table/Collection for success == true in Your Team's FaceTec Database. Please note, that in this mode, success is true based on Your Team's Customizable Logic for evaluating ID Scan Results and proceeding Users through their ID Scan. Please note that the User completing an ID Scan does not necessarily mean the ID Scan Portion of the User Interaction is "successful". This is because FaceTec does not "Authenticate" Documents (more info here) -- instead, FaceTec provides back a wide variety of signals, including 3D:2D Matching Results, OCR results, NFC Results, Barcode Results, and Document Anti-Spoof & Anti-Tampering Results, allowing you to decide the logic and checks that work best for Your Use Case.

3D Liveness, 3D Enrollment, 3D:3D Re-Verification, 3D:2D Photo ID Matching & ID Scan Only - Evaluating Edge Cases

Although the vast majority of Users who complete a User Interaction with FaceTec will Succeed/Complete their User Interaction with FaceTec, there are few other cases that should be evaluated and handled.

Here is a list of additional cases where a User Interaction with FaceTec ends and how FaceTec recommends to handle them:

  • User Cancellation -- A User Interaction with FaceTec can end with a User Cancelling out of the FaceTec UI. Users may cancel out of the FaceTec UI if they are not prepared to perform a Scan or for other reasons. FaceTec recommends continuing to allow the User to start another User Interaction with FaceTec since the vast majority of Users who start FaceTec, and make attempts to complete the process, will complete it Successfully. Please note that a portion of User Cancellations will be from Bad Actors and Fraudsters failing to bypass FaceTec's Software and is indicative of FaceTec achieving its Security Goals.
  • Unrecoverable Error -- An Unrecoverable Error should only occur in <0.1% of User Interactions with FaceTec and typically occurs when a Hardware Issue (typically with the Camera) occurs on the Device and FaceTec cannot recover from it. Although FaceTec is continuing to improve its ability to detect and recover from these Device-Induced Behaviors, FaceTec may end a User Interaction and provide an error status to Your Device-Side Code. FaceTec recommends continuing to allow the User to start another User Interaction with FaceTec because for Real Users, Unrecoverable Errors can frequently be resolved by starting FaceTec again. Please note that a portion of Unrecoverable Errors will be from Bad Actors and Fraudsters failing to bypass FaceTec's Software by tampering with the Device/Camera or the Application's Runtime and is indicative of FaceTec successfully achieving its Security Goals.
  • Lockout -- If the User performs too many Scans in a short amount of time, FaceTec will exit with a Locked Out Status (more info here). Since the vast majority of Users who start FaceTec can complete Successfully, this status should only be returned in a very small number of cases. Please note that a portion of Locked Out Statuses will be from Bad Actors and Fraudsters failing to bypass FaceTec's Software and is indicative of FaceTec successfully achieving its Security Goals.

Audit Trail Images and FaceTec Dashboard

When a User Interaction with FaceTec is completed, Audit Trail Images are made available and results from the User Interaction can be seen on the FaceTec Dashboard.

FaceTec Server stores an Audit Trail Image for each Successful 3D Liveness, 3D Enrollment, and 3D:3D Re-Verification Session performed by the User. The Audit Trail Image is stored in the auditTrailImage field of the data object on the Database Record for that launchId. The Audit Trail Image is also viewable on the FaceTec Dashboard.

For User Interactions with FaceTec that do not end with a Success, Audit Trail Image(s) from User Scans are stored in the auditTrailImageSequence field of the data object on the Database Record for that launchId. The Audit Trail Image(s) are also viewable on the FaceTec Dashboard.

Additional Requirements for 3D Enrollment, 3D:3D Re-Verification, & 3D:2D Photo ID Matching

FaceTec Server's /process-request function also requires specifying an externalDatabaseRefID parameter for 3D Enrollment, 3D:3D Re-Verification, and 3D:2D Photo ID Matching.

For 3D Enrollment and 3D:2D Photo ID Matching, the externalDatabaseRefID parameter is used as the identifier to store the Liveness-Proven 3D FaceMap to Your Database.

For 3D:3D Re-Verification, the externalDatabaseRefID parameter is used as the identifier to retrieve the Liveness-Proven 3D FaceMap from Your Team's Database that will be used to perform 3D:3D Matching against the User's 3D FaceScan after the User has Successfully Proven 3D Liveness.

Important Note: The FaceTec Sample Apps include a demonstration of using externalDatabaseRefID for the APIs that require it. This implementation of externalDatabaseRefID in Device-Side Code is for Testing and Demonstration Purposes only. In a Production Integration, Business Logic for determining externalDatabaseRefID should be controlled in Your Team's Webservice Code to avoid exposing these identifiers in Your Team's Client-Side Code.

Session History Data Object

The Session History Data (SessionHistoryData) is a required data object to achieve correct behavior in v10.

Examples of storing and retrieving SessionHistoryData in a v10 integration can be found in the SessionRequestProcessor, the MongoDB, and the PostgreSQL Database implementations.

SessionRequestProcessor Network Requests to Your Webservice

When developing the code in Your Team's SessionRequestProcessor that will be calling Your Team's Webservice to send the sessionRequestBlob, please utilize Your Organization's Networking and Security Best Practices.

For instance, if Your Team needs the API in Your Team's Webservice to have a custom name like "/3d-liveness-check", please update the names of the APIs and Properties being used in Your Team's Webservice.

Also, if Your Team already has methods for identifying Application Users or ensuring the security of API Calls to Your Webservice via Your Team's Own Concept of User Security and Tokens, then please update these API Calls to abide by Your Organization's Required Standards.

However, please note that you will still call FaceTec Server's /process-request function from Your Webservice using the parameters and methodologies specified in this guide. FaceTec understands that Your Organization likely has its own standards for making Device-to-Server Networking Requests, but it is important to understand that Your Team's Application still must send the sessionRequestBlob and respond back to the FaceTec's Device SDK APIs with the responseBlob.

FaceTec sees a frequent need for Organizations to send additional data related to User Tracking and Security, and FaceTec encourages you to use Your Organization's Best Practices to accomplish these goals.