# FaceTec
Page contents
FaceTec (opens new window) is a third-party eIDV provider integrated with the Assure API. Combining FaceTec with Assure's identity verification capabilities, increases the confidence in the onboarding process and prevents fraud attempts.
# Supported features
Signicat supports the following identity verification features from FaceTec:
- Face match between ID document and selfie
- Liveness check of live video recording
# User flow example
More information will follow later.
# Mobile SDKs (Android and iOS)
The aim of this topic is to help a developer integrating with the Assure API using FaceTec's mobile SDKs.
Please, keep in mind that the following descriptions do not contain all the necessary steps for production mode. In addition, you must add validations, tests and error handling, which is outside the scope of this documentation.
Using the third-party SDKs means that the end-user will see FaceTec's user interface when performing the identity verification on their mobile or desktop.
Check "liveness" of end-user
The main aim of FaceTec's user interface is to check the "liveness" of an end-user against an image of the end-user’s face.
Before you start the SDK integration, we recommend to familiarise yourself with the general steps for integrating with the Assure API.
# Requirements
Before you start the integration, you should be aware of the following requirements for all FaceTec's SDKs:
- You must always use the latest FaceTec SDK version.
Important!
Once implemented, you must update the SDK version every 90 days. If the version is not updated, your FaceTec service will stop working. For more details, see https://dev.facetec.com/updating#update-policy (opens new window).
- Check the supported device versions on this page: https://dev.facetec.com/compatibility (opens new window)
- The app needs camera permission. Access to a microphone is not a requirement.
- Your app must always communicate with your own server and never directly with the Assure API (see Usage recommendations).
- Since you are integrating with the Assure API in a native app context, you should choose the eIDV generic flow.
# Integration steps overview
This diagram provides an abstraction of the client-side implementation.
The next sections describe all the needed steps, including the integration with Assure before and after the FaceTec SDK integration in step 4:
- Create a dossier.
- Create a process.
- Add a photo to the process.
- Integrate with the FaceTec SDK to capture liveness images.
- Start verification.
- Get result.
Note:
All the steps are similar for iOS and Android except the SDK integration in step 4, which is described below in different tabs for iOS and Android.
# Create a dossier
- Use the Create dossier (opens new window) endpoint to create a placeholder for all of your end-user’s data.
- Save the
dossierIdyou get in the response to be used in the next requests.
Note:
Ensure you use one dossier per end-user.
# Create a process
- Use the Create process (opens new window) endpoint to create an identity verification process in that dossier. Ensure you give it the
dossierIdyou got in the Create dossier response. Also, enter the FaceTec provider in the request body:
{
"provider":"facetec"
}
When you have created the FaceTec process, you should get a backend response like this:
{
"processId": "74ee35d5-f542-472e-a087-597bc28bc9d4",
"status": "pending",
"createdAt": "2021-01-05T10:54:47Z",
"updatedAt": "2021-01-05T10:54:47Z",
"authorization": "someAuthorizationToken",
"facetecEncryptionPublicKey": "somePublicKey",
"facetecDeviceKeyIdentifier": "someDeviceKeyIdentifier",
"facetecProductionKeyText": "someOtherKey",
"provider": "facetec"
}
- Save the information from the response. You will need it in the next steps.
# Add a photo to the process
The FaceTec liveness process needs to compare the liveness data (that will be obtained in the next step) with a photo of the person who is supposed to match that liveness data.
The most common use-case is that you have a photo from someone you already know is the valid owner of an ID document and then want to use FaceTec to get liveness evidence from that person.
To do that, you first create another process in the Assure API and use it to verify a person’s identity using an ID document. Then you can get the photo of that person from that process (see Get Image (opens new window)) and feed it to the FaceTec process (Set Image (opens new window) “selfie”).
# Integrate with the FaceTec mobile SDK to capture liveness images
To capture the live images from the end-user, you must now integrate with the FaceTec SDK for either Android or iOS:
# Start verification
Your server (backend) must request the Assure API to start performing the identity verification.
To do this, you must send the necessary fields you got in the app to the backend, and then the backend communicates with Assure by calling Start verification (opens new window) with this request body:
{
"facetecEnrollment": {
"faceScan": "string",
"auditTrailImage": "string",
"lowQualityAuditTrailImage": "string",
"userAgent": "string"
}
}
# Get result
When the verification is finished, you can call the Get process (opens new window) result to get the result of the identity verification. Here is an example of an accepted process:
{
"processId":"c573be77-b253-49e9-863a-fc04965ea66f",
"provider":"facetec",
"status":"accepted",
"providerSpecific":{
"liveness":{
"facescanSecurityChecks.auditTrailVerificationCheckSucceeded":"true",
"facescanSecurityChecks.replayCheckSucceeded":"true",
"facescanSecurityChecks.faceScanLivenessCheckSucceeded":"true",
"success":"true",
"error":"false",
"facescanSecurityChecks.sessionTokenCheckSucceeded":"true"
},
"matching":{
"matchLevel":"8",
"success":"true",
"error":"false"
}
},
"finalResult":{
"livenessDetected":"true",
"similarityScore":"high"
},
"createdAt":"2021-01-06T16:48:32Z",
"updatedAt":"2021-01-06T16:49:06Z"
}
The process is accepted because both the matching of the selfie with the liveness video and the liveness check were successful.
The process is rejected if any of the conditions mentioned before is false.
For more details about the results from "Get process", see the "Service details" section below.
Download full result
You can also get a zip file with the packaged process by calling the Download full result (opens new window) endpoint. For more details, see the "Service details" section below.
# Service details for FaceTec
This section goes more into detail about some useful endpoints when integrating with FaceTec:
# Get process
This section describes the final result statuses for FaceTec.
# Final status of FaceTec processes
Assure API uses the information in the liveness and matching fields to map the process' final status:
- accepted: The end-user passed all liveness checks performed by FaceTec, and their face matched the face in the ID-photo/selfie image with matchLevel >= 6 (1/100,000 FAR).
- inconclusive: The match level (
matchLevel) between the face of the end-user and the face in the ID-photo/selfie image is between 1 (1/100 FAR) and 5 (1/10,000 FAR). - rejected: The end-user did not pass one or more of the liveness checks performed by FaceTec, or their face did not match the face in the ID-photo/selfie image.
# accepted
This is a response example of a FaceTec process that was accepted:
{
"processId":"fd3121cb-f9aa-4c77-bb65-97f6d82a9a02",
"provider":"facetec",
"status":"accepted",
"finalResult":{
"livenessDetected":"true",
"similarityScore":"high"
},
"createdAt":"2021-11-11T15:23:35Z",
"updatedAt":"2021-11-11T15:24:10Z",
"providerSpecific":{
"liveness":{
"faceScanSecurityChecks":{
"auditTrailVerificationCheckSucceeded":true,
"replayCheckSucceeded":true,
"faceScanLivenessCheckSucceeded":true,
"sessionTokenCheckSucceeded":true
},
"error":false,
"success":true
},
"matching":{
"attempts":[
{
"algorithm":"facePortrait",
"matchLevel":8,
"imageProcessing":"faceFound",
"success":true,
"error":false
}
],
"algorithm":"facePortrait",
"matchLevel":8,
"imageProcessing":"faceFound",
"success":true,
"error":false
}
}
}
For field descriptions, see the Open API documentation > Get process (opens new window) and Start verification (opens new window)
# inconclusive
This is a response example of a FaceTec process that was inconclusive:
{
"processId":"1ca4c667-7132-45dc-a826-3bddaf4bc2a6",
"provider":"facetec",
"status":"inconclusive",
"createdAt":"2022-04-21T13:44:37Z",
"updatedAt":"2022-04-21T13:46:51Z",
"providerSpecific":{
"liveness":{
"faceScanSecurityChecks":{
"auditTrailVerificationCheckSucceeded":true,
"replayCheckSucceeded":true,
"faceScanLivenessCheckSucceeded":true,
"sessionTokenCheckSucceeded":true
},
"error":false,
"success":true
},
"matching":{
"attempts":[
{
"algorithm":"facePortrait",
"matchLevel":4,
"imageProcessing":"faceFound",
"success":true,
"error":false
},
{
"algorithm":"idPhoto",
"matchLevel":5,
"imageProcessing":"faceFound",
"success":true,
"error":false
},
{
"algorithm":"idPhotoLowQuality",
"matchLevel":5,
"imageProcessing":"faceFound",
"success":true,
"error":false
}
],
"algorithm":"idPhotoLowQuality",
"matchLevel":5,
"imageProcessing":"faceFound",
"success":true,
"error":false
}
}
}
In this example, matchLevel was not high enough to get accepted.
For more details about matchLevel and other fields, see the providerSpecific element for FaceTec in the Open API documentation for Get process (opens new window) and Start verification (opens new window).
# rejected
This is a response example of a FaceTec process that was rejected. Here, liveness was detected in the recorded video of the user's face, but there was no match with the face on the ID-photo ("matchLevel":0):
{
"processId":"5fe7a9b9-f781-44d1-b37b-6cc958ee7b7a",
"provider":"facetec",
"status":"rejected",
"createdAt":"2021-11-12T13:52:10Z",
"updatedAt":"2021-11-12T13:52:46Z",
"providerSpecific":{
"liveness":{
"faceScanSecurityChecks":{
"auditTrailVerificationCheckSucceeded":true,
"replayCheckSucceeded":true,
"faceScanLivenessCheckSucceeded":true,
"sessionTokenCheckSucceeded":true
},
"error":false,
"success":true
},
"matching":{
"attempts":[
{
"algorithm":"facePortrait",
"matchLevel":0,
"imageProcessing":"faceFound",
"success":false,
"error":false
},
{
"algorithm":"idPhoto",
"matchLevel":0,
"imageProcessing":"faceFound",
"success":false,
"error":false
},
{
"algorithm":"idPhotoLowQuality",
"matchLevel":0,
"imageProcessing":"faceFound",
"success":false,
"error":false
}
],
"algorithm":"idPhotoLowQuality",
"matchLevel":0,
"imageProcessing":"faceFound",
"success":false,
"error":false
}
}
}
# Download full result
# Data files
# liveness.json
This "raw" file contains all the liveness information FaceTec provides from the face scan of the end-user.
# matching_facePortrait.json
This "raw" file contains all the information FaceTec provides when matching the end-user's face in the ID-photo/selfie with the face scan.
# Media files
| Type | File name/format | Comment |
|---|---|---|
| front | front.png/jpeg | This file is only present if it was added to the FaceTec process. It contains the image of the front of the ID document. |
| back | - | This provider does not use images from the backside of the ID document. |
| selfie | selfie.png/jpeg | This file is only present if it was added to the FaceTec process. It contains the image of the end-user's face. |
| portrait | - | This provider does not extract the photo from the ID. |
| video | - | This provider does not capture videos. |
See also the API Reference (opens new window) for even more service details.