Retrieve results
Face Check Results
The response will detail the session results information including check and task completion status, resource and media data, along with the associated media identifiers.
const { RequestBuilder, Payload } = require("yoti");const request = new RequestBuilder() .withBaseUrl("https://api.yoti.com/idverify/v1") .withPemFilePath("<YOTI_KEY_FILE_PATH>") // file path to PEM file .withEndpoint("/sessions/<session_id>") .withMethod("GET") .withQueryParam("sdkId", "<YOTI_CLIENT_SDK_ID>") .build();// get Yoti responseconst response = await request.execute();GET https://api.yoti.com/idverify/v1/sessions/<SESSION_ID>When the above endpoint is hit you will receive the results of all checks configured in the session, including the familiar face search check. The response will follow the below format.
Response body
{ "client_session_token_ttl": 0, "session_id": "7938ac1e-0a4a-49b7-953f-08cfa764358f", "state": "COMPLETED", "resources": {}, "checks": [], "user_tracking_id": "<YOUR_USER_ID>", "biometric_consent": "2025-06-04T08:50:43Z"}Within the Familiar Face Search check object you will details regarding the result of the check. The recommendation value will depend upon what has been configured in the "approval_criteria". If the approval criteria is set to "MATCH" the recommendation value will be APPROVE if there is a match and if approval_criteria is set to "NO MATCH" the recommendation value will be APPROVE if there is not a match. The Familiar Face Search check object will also detail the applicant pool id that is being searched against as well as a list of applicant ids.
| Field | Description |
|---|---|
| value | The value will either be "REJECT" or "APPROVE" based on what your approval criteria is and if a match has been found. |
| reason | The reason tells you why the check was rejected or approved. The reason can either be "MATCH" or "NO_MATCH", and will depend on what you have set as the approval criteria. |
| breakdown | gives further insight into why the check was approved or rejected. The breakdown will also contain the applicant id of a matching applicant, which can then be used to retrieve the face of that applicant. |
| sub_check | The sub check just identifies if the users face matches any in the applicant pool you are searching against. And will have a fail or pass result associated to it. |
| details | The details object will display the applicant id of the applicant that matched with the user as well as the pool id of which the matched applicant is a part of. |
Retrieve Face
Integrators also have the ability to retrieve the face associated with the matching applicant. The matching applicant id will need to be used in a GET request to retrieve applicant details including a UUID which can be used to retrieve the image of the users face.
GET https://api.yoti.com/idverify/v1/applicant/<applicant_id>Response body
{ "id": "db59ddde-ca99-48aa-ac77-e59be74fc0d1", "faces": { "archetype_face": "8b9c3ea5-ebd4-436b-836d-ba8dbc80b57e", "faces": [] }, "pools": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "label": "Test Pool2" } ]}To retrieve the image of a users face the below endpoint will need to be called using the UUID linked to the applicants face. This will return the image in it's base64 encoded format.
GET https://api.yoti.com/idverify/v1/applicant/<applicant_id>/faces/<face_id>Response body
{ "face": { "data": "base64 string", "content_type": "image/jpeg" }}