Title
Create new category
Edit page index title
Edit category
Edit link
Retrieve 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 format below.
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 find 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. |
Yoti recommends that you review any matches internally, to make sure you aren't rejecting genuine users who were incorrectly flagged.
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 user's 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 user's face the below endpoint will need to be called using the UUID linked to the applicant's face. This will return the image in its 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" }}Got a question? Contact us here.