Integration guide

AI Tools

Using the Identity Verification (IDV) service, you can enable a face comparison check that can be used to authenticate a user by using their selfie.

This check does an AI comparison between a live user selfie and the reference facial image to return a confidence score. Combined with a liveness check.

Face Auth (via a face comparison check) can be requested along with other checks (i.e. Document authenticity, Face match etc.) or as a standalone check.

Install the SDK

The Yoti Client SDK provides several helper methods to interact with the API. You can initialise the client using your unique SDK ID and PEM file.

Node.js
Java
PHP
Python
C#
Go
    
​x
 
const path = require('path');const fs = require('fs');​const { IDVClient } = require('yoti');​const YOTI_CLIENT_SDK_ID = 'YOTI_CLIENT_SDK_ID';const YOTI_PEM = fs.readFileSync(path.join(__dirname, '/path/to/pem'));​const idvClient = new IDVClient(YOTI_CLIENT_SDK_ID, YOTI_PEM);
Copy

You can use the createSession method from the above client to create a Yoti session. Session specification needs to be passed as an argument. After the session is successfully created, you will get a Session ID that can be used to retrieve the Session configuration.

Node.js
Java
PHP
Python
C#
Go
    
 
let sessionId, sessionToken;​idvClient    .createSession(sessionSpec)    .then((session) => {        sessionId = session.getSessionId();        sessionToken = session.getClientSessionToken();    })    .catch((err) => {        console.log(err)    });​const sessionConfig = await idvClient.getSessionConfiguration(sessionId);
Copy

Configure a session

To use this service, you have to create an Identity Verification session specification with at least two checks - Liveness and Face Comparison. Face Comparison check is available as an automated check only.

Node.js
Java
PHP
Python
C#
Go
    
 
const {    SessionSpecificationBuilder,    RequestedLivenessCheckBuilder,    RequestedFaceComparisonCheckBuilder,    SdkConfigBuilder} = require('yoti');​// Liveness check with 3 retriesconst livenessCheck = new RequestedLivenessCheckBuilder()    .forStaticLiveness()    .withMaxRetries(3)    .build();​// Face Auth (face comparison check) with manual check set to neverconst faceComparisonCheck = new RequestedFaceComparisonCheckBuilder()    .withManualCheckNever()    .build();​// Configuration for the client SDK (Frontend)const sdkConfig = new SdkConfigBuilder()    .withSuccessUrl('/success')    .withErrorUrl('/error')    .withAllowHandoff(true)    .build();​// Buiding the Session with defined specification from aboveconst sessionSpec = new SessionSpecificationBuilder()    .withClientSessionTokenTtl(600)    .withResourcesTtl(90000)     .withUserTrackingId('some-user-tracking-id')    .withRequestedCheck(livenessCheck)    .withRequestedCheck(faceComparisonCheck)    .withSdkConfig(sdkConfig)    .build();
Copy

Create a Face Capture resource

Before uploading the user's facial image, you have to create a Face capture resource. To do this, a Requirement ID from the Face Capture requirements needs to be retrieved. This can then be used to create a face capture resource. If successful, you will receive a Resource Id.

Node.js
Java
PHP
Python
C#
Go
    
 
const {  CreateFaceCaptureResourcePayloadBuilder,  UploadFaceCaptureImagePayloadBuilder,} = require('yoti');​const resourceRequirements = sessionConfiguration.getCapture().getFaceCaptureResourceRequirements()[0];const requirementId = resourceRequirements.getId();​const faceCapturePayload = new CreateFaceCaptureResourcePayloadBuilder()    .withRequirementId(requirementId)    .build();​const faceCaptureResource = await idvClient.createFaceCaptureResource(sessionId, faceCapturePayload);const resourceId = faceCaptureResource.getId();
Copy

Upload a user facial image

To do accurate face authentication, a user's facial image of the user is required. You have to get the contents of this image, which can then be uploaded using the Yoti Client. You also have to pass in the Resource ID retrieved earlier.

Node.js
Java
PHP
Python
C#
Go
    
 
const fs = require('fs');​const imageBuffer = fs.readFileSync('path-to-selfie-jpeg');​const faceCaptureImagePayload = new UploadFaceCaptureImagePayloadBuilder()    .forJpegImage()    .withImageContents(imageBuffer)    .build();​await idvClient.uploadFaceCaptureImage(sessionId, resourceId, faceCaptureImagePayload);
Copy

Launch the User Interface

The next step is to load the Yoti Client SDK. To do this, you need the following parameters generated with the session creation request above:

Session ID
Session Token

We then utilise these to construct a Web URL which loads the Yoti Client SDK. The URL is in the following format:

HTTP
    
 
https://api.yoti.com/idverify/v1/web/index.html?sessionID=<sessionID>&sessionToken=<sessionToken>
Copy

Once the above URL launches in a web browser, it will take the user through the Selfie and liveness capture flow. For more detailed steps, please refer to the Launch the user view page.

Retrieve results

Once a session has been completed, the associated checks' results and resources can be retrieved using the session ID. Each check would contain a recommendation and a breakdown. The resources, however, are not directly included in the results, but contain a media ID. This can be used to fetch the actual media resource.

The user may have attempted liveness multiple times; the liveness results may contain multiple images, as a liveness result is generated for each allowed retry.

For a face comparison to be considered a 'PASS' overall, the recommended action is to confirm that at least one Liveness check is 'APPROVE' and the Face Comparison check is 'APPROVE'.

Retrieve checks

Node.js
Java
PHP
Python
C#
Go
    
 
idvClient.getSession(sessionId).then(sessionResult => {    const state = sessionResult.getState();      const livenessChecks = sessionResult.getLivenessChecks();      livenessChecks.map(check => {        const id = check.getId();        const state = check.getState();        const resourcesUsed = check.getResourcesUsed();​        const report = check.getReport();        const recommendation = report.getRecommendation().getValue();        const breakdown = report.getBreakdown();              breakdown.forEach(function(breakdown) {          const subCheck = breakdown.getSubCheck();          const subCheckResult = breakdown.getResult();        });    })      const faceComparisonChecks = sessionResult.getFaceComparisonChecks();      faceComparisonChecks.map(check => {        const id = check.getId();        const state = check.getState();        const resourcesUsed = check.getResourcesUsed();              const report = check.getReport();        const recommendation = report.getRecommendation().getValue();        const breakdown = report.getBreakdown();              breakdown.forEach(function(breakdown) {          const subCheck = breakdown.getSubCheck();          const subCheckResult = breakdown.getResult();        });    })}).catch(error => {    console.log(error);    // handle error})
Copy

Retrieve resources

To get the images of the user, you will need to retrieve a resource ID, which will then be used to retrieve the media (below).

Node.js
Java
PHP
Python
C#
Go
    
 
idvClient.getSession(sessionId).then(sessionResult => {    const resources = sessionResult.getResources();      const faceCaptureResources = resources.getFaceCaptureResources();      const staticLivenessResources = resources.getStaticLivenessResources();      staticLivenessResources.map(resource => {        const id = resource.getId();m        const type = resource.getLivenessType();        const mediaId = check.getImage().getId();    })}).catch(error => {    console.log(error);    // handle error})
Copy

Retrieve media

This is to retrieve the images from the session.

Node.js
Java
PHP
Python
C#
Go
    
 
idvClient.getMediaContent(sessionId, mediaId).then(media => {    const buffer = media.getContent();    const mimeType = media.getMimeType();    const base64Content = media.getBase64Content();    // handle base64content or buffer}).catch(error => {    console.log(error)    // handle error})
Copy

Last updated on

Was this page helpful?