Using externalDatabaseRefID in API Calls (HTTPS API)
Learn how to use externalDatabaseRefID to store and retrieve 3D FaceMaps from Your Team's External Database.
Overview
The API parameter externalDatabaseRefID is a developer-defined string that references a 3D FaceMap stored by the FaceTec Server. A 3D FaceMap is only stored after Liveness is Proven on a 3D FaceScan.
The purpose of externalDatabaseRefID is to identify 3D FaceMaps and correlate them to User IDs in an already-existing User Database.
The externalDatabaseRefID(s) should be generated and managed in Your Server-Side Code and Business Logic.
Usage
The FaceTec Server utilizes the /process-request API to process Request Blobs from the Device SDK and implement FaceTec's Core Features. The following FaceTec Features require the externalDatabaseRefID parameter for the storage or retrieval of a 3D FaceMap:
Important Note: The API parameter externalDatabaseRefID is developer-defined and created and set by you using your own Business Logic. The FaceTec Sample App demonstrates generating the demonstrationExternalDatabaseRefID for demonstration purposes. In production, you should be generating and managing externalDatabaseRefIDs in Your Server-Side Code. To Re-Verify Users, externalDatabaseRefID should be fetched with Backend Logic and used as a parameter for Matching. If you expose externalDatabaseRefIDs in Your Front-End Code, you will potentially allow for attacks where externalDatabaseRefIDs can be traced and/or guessed and used in attempts for Unauthorized Access.
3D Enrollment
Unlike 3D FaceScans, 3D FaceMaps do not contain 3D Liveness Data. This eliminates the Honeypot Risk of storing 3D FaceMaps in an External Database, while ensuring they can be retrieved for Features that do not require the original 3D Liveness Data.
The FaceTec Server performs 3D Enrollment (i.e. stores the 3D FaceMap) if an externalDatabaseRefID was specified, the externalDatabaseRefID does not already exist in the Database, and 3D Liveness is Proven. By default, the FaceTec Server performs 3D Enrollment when a Standalone 3D Liveness Check is successful. The FaceTec Server also performs 3D Enrollment as a part of the 3D:2D Photo ID Matching Process.
3D FaceMap Retrieval
FaceTec's Matching, Searching, and Age Estimation APIs operate by processing the data stored in a 3D FaceMap. These APIs use the externalDatabaseRefID to retrieve a 3D FaceMap stored in Your Team's External Database.
For 3D:3D Re-Verification, the Retrieved 3D FaceMap is matched against the 3D FaceScan that was just performed by the User.
For 3D:2D Photo ID Matching, the Retrieved 3D FaceMap is matched against the ID Scan that was just performed by the User.
Use Cases & Security
If the same externalDatabaseRefID is already enrolled, the Session will fail with the following exception: "An enrollment already exists for this externalDatabaseRefID". To resolve this, the existing externalDatabaseRefID must be removed from Your External Database, or a new externalDatabaseRefID needs to be created.
To resolve this, the existing externalDatabaseRefID must be removed from Your External Database, or a new externalDatabaseRefID needs to be created.
FaceTec does not offer a HTTPS API to delete data due to the many variables to consider when deciding which data to delete versus which data to preserve which could result in an irreparable loss of data. All Session Data is stored in the database and can be listed or removed via MongoDB Queries according to the Customer's requirements. Please see the MongoDB Data Storage & Queries Guide for additional information.
Important Note: In the rare scenarios where the User enrolls, but cancels out Mid-Session, as in an 3D:2D Photo ID Matching Flow, FaceTec recommends evaluating the Session, deleting Enrollment Session Data for the User, and starting the Enrollment Process again to ensure all data was generated and processed during the Enrollment Session.