Retrieve results and data

The response will detail all information, check and task completion status, resource and media data, along with the associated media identifiers.

Sessions can be retrieved at any time, however the integrating backend will be notified when a session update occurs, according to the notifications settings provided at session creation.

Get Session Request

Please note:

• withMethod should be set to GET
• The withEndpoint should be set to /sessions/SESSION_ID where SESSION_ID should be replaced with the SESSION_ID obtained at Create a Session.

const { RequestBuilder, Payload } = require("yoti");

​

const request = new RequestBuilder()

  .withBaseUrl("https://api.yoti.com/idverify/v1")

  .withPemFilePath("<YOTI_KEY_FILE_PATH>")

  .withEndpoint(`/sessions/<SESSION_ID>`)

  .withMethod("GET")

  .withQueryParam("sdkId", "<YOTI_CLIENT_SDK_ID>")

  .build();

​

//get Yoti response

const response = request.execute();

See below for an example response from the retrieve session endpoint.

Example of a full session retrieval

{

  "client_session_token_ttl": 599,

  "session_id": "<uuid>",

  "user_tracking_id": "<uuid>",

  "state": "COMPLETED",

  "client_session_token": "<uuid>",

  "resources": {...},

  "checks": [...]

}

Get Session Response Explained

Retrieved State

Yoti will provide back the following information regarding the state of the session:

• The state of the session
• Session ID
• client_session_token_ttl - will be 0 if expired.
• user_tracking_id set by the relying business backend

{

  "client_session_token_ttl" : 599,

  "session_id" : "<uuid>",

  "user_tracking_id" : "<uuid>",

  "state" : "ONGOING",

  "client_session_token" : "<uuid>",

}

Retrieved Checks

We provide back the following details for the checks:

• Type and unique ID
• Resources used
• State
• Report - containing a recommendation and a breakdown of the report.

ID Document Authenticity

An example of an 'APPROVE' report is shown below, please use the language snippet to see examples of a 'REJECT' and 'NOT_AVAILABLE' report.

// APPROVE REPORT. Navigate to the next tab for the rejected example.

​

"checks": [

      {

         "type": "ID_DOCUMENT_AUTHENTICITY",

         "id": "<uuid>",

         "state": "DONE",

         "resources_used": [

            "<uuid>"

         ],

         "generated_media": [],

         "report": {

            "recommendation": {

               "value": "APPROVE"

            },

         "breakdown": [

          {

            "sub_check": "data_in_correct_position",

            "result": "PASS",

            "details": []

          },

          {

            "sub_check": "document_in_date",

            "result": "PASS",

            "details": []

          },

          {

            "sub_check": "expected_data_present",

            "result": "PASS",

            "details": []

          },

          {

            "sub_check": "fraud_list_check",

            "result": "PASS",

            "details": []

          },

          {

            "sub_check": "hologram",

            "result": "PASS",

            "details": []

          },

          {

            "sub_check": "hologram_movement",

            "result": "PASS",

            "details": []

          },

          {

            "sub_check": "no_sign_of_tampering",

            "result": "PASS",

            "details": []

          },

          {

            "sub_check": "other_security_features",

            "result": "PASS",

            "details": []

          },

          {

            "sub_check": "real_document",

            "result": "PASS",

            "details": []

          }

        ]

         },

         "created": "<yyyy-mm-ddThh:mm:ssZ>",

         "last_updated": "<yyyy-mm-ddThh:mm:ssZ>"

      }

]

If Yoti responds with the REJECT recommendation there will be a rejection reason alongside this.

• Missing Hologram
• Document Copy
• Tampered
• Not genuine

If Yoti responds with the NOT AVAILABLE recommendation, this means we were unable to carry out the check. A recovery suggestion will be provided to give the user an idea of what can be done to correct the issue causing the not available recommendation. A full list of possible reasons for this can be found below:

Liveness

Liveness checks can be retried if failed, depending on specified limited set when generating the session. Each try will generate a new report in the JSON response. The check will either be approved or rejected based on the result of the liveness check which is a pass/fail result.

"checks": [

  {

         "type": "LIVENESS",

         "id": "<uuid>",

         "state": "DONE",

         "resources_used": [

            "<uuid>"

         ],

         "generated_media": [],

         "report": {

            "recommendation": {

               "value": "APPROVE" //"REJECT

            },

            "breakdown": [

               {

                  "sub_check": "liveness_auth",

                  "result": "PASS", //"FAIL"

                  "details": []

               }

            ]

         },

         "created": "<yyyy-mm-ddThh:mm:ssZ>",

         "last_updated": "<yyyy-mm-ddThh:mm:ssZ>"

      }

]

ID Document Face Match

An ID_DOCUMENT_FACE_MATCH check will return a report containing an overall recommendation, and the breakdown of sub checks performed (the result of the machine (AI) face match, and/or the manual face match, according to which were performed).

If an AI face match is performed, a pass/fail result is returned, along with a confidence score (between 0 and 1) depending on how successful the match is, Yoti offers a PASS score if the confidence score is over 0.7.

A manual check will be either a pass or a fail.

The face match check will give a recommendation based on these as either APPROVE or REJECT.

{

    "type": "ID_DOCUMENT_FACE_MATCH",

    "id": "<uuid>",

    "state": "DONE",

    "resources_used": [

        "<uuid>",

        "<uuid>"

    ],

    "generated_media": [],

    "report": {

        "recommendation": {

            "value": "APPROVE" // "REJECT"

        },

        "breakdown": [

            {

                "sub_check": "manual_face_match",

                "result": "PASS", // "FAIL"

                "details": []

            },

            {

                "sub_check": "ai_face_match",

                "result": "PASS", // "FAIL"

                "details": [

                    {

                        "name": "confidence_score",

                        "value": "1.00"

                    }

                ]

            }

        ]

    },

    "created": "<yyyy-mm-ddThh:mm:ssZ>",

    "last_updated": "<yyyy-mm-ddThh:mm:ssZ>"

}

The below responses are only for manual checks:

ID Document Text Data Check

This check is generated by the ID Document Text Data Extraction task (see below). This will only be generated if the "manual_check" is set to ALWAYS or FALLBACK. This check is performed by our security centre to manually check that the automatic text data extraction was correct or to perform the extraction if the automatic task fails.

{

            "type": "ID_DOCUMENT_TEXT_DATA_CHECK",

            "id": "<UUID>",

            "state": "DONE",

            "resources_used": [

                "<UUID>"

            ],

            "generated_media": [

                {

                    "id": "<UUID>",

                    "type": "JSON"

                }

            ],

            "report": {

                "recommendation": {

                    "value": "APPROVE"

                },

                "breakdown": [

                    {

                        "sub_check": "text_data_readable",

                        "result": "PASS",

                        "details": []

                    }

                ]

            },

            "created": "YYYY-MM-DDTHH:MM:SSZ",

            "last_updated": "YYYY-MM-DDTHH:MM:SSZ"

        }

The ID Document Text Data check will give a recommendation either APPROVE or REJECT. The recommendation will come with a breakdown which will contain the subcheck text_data_readable which will either be a PASS or a FAIL.

If this check is successfully approved then the generated media array will contain the extracted text media ID, which can be used to retrieve the JSON object with the extracted data.

This media will replace the "document_fields" media in the resources. Details of this can be found here: retrieved resources.

Retrieved Tasks

ID Document Text Data Extraction

An ID_DOCUMENT_TEXT_DATA task will return a state and a JSON. See Retrieved resources section for more detail.

"tasks": [

          {

            "type": "ID_DOCUMENT_TEXT_DATA_EXTRACTION",

            "id": "<uuid>",

            "state": "DONE",

            "created": "<yyyy-mm-ddThh:mm:ssZ>",

            "last_updated": "<yyyy-mm-ddThh:mm:ssZ>",

            "generated_checks": [],

            "generated_media": [

              {

                "id": "<uuid>",

                "type": "JSON"

              }

            ]

          }

        ],

If Yoti responds with the NOT AVAILABLE recommendation, this means we were unable to carry out the check. A recovery suggestion will be provided to give the user an idea of what can be done to correct the issue causing the not available recommendation. A full list of possible reasons for this can be found below:

Get Media Request

For security reasons, we do not include personally identifiable information (PII) within the standard response to a session retrieval request. Rather, we provide pointers to 'media' associated with the session, which are stored and can be retrieved separately. Examples of media are: document images, structured fields extracted from a document, face images, and so on.

Using the media IDs contained within the response to a GET session request, you can retrieve the associated media using the session ID and media ID.

Please note the:

• withMethod should be set to GET
• The withEndpoint should be set to /sessions/SESSIONID/media/MEDIA ID/content where SESSION_ID should be replaced with the SESSION_ID obtained at Create a Session.
• MEDIA_ID should be replaced with the MEDIA_ ID obtained at session retrieval.

const { RequestBuilder, Payload } = require("yoti");

​

const request = new RequestBuilder()

  .withBaseUrl("https://api.yoti.com/idverify/v1")

  .withPemFilePath("<YOTI_KEY_FILE_PATH>")

  .withEndpoint(`/sessions/<SESSION_ID>/media/<MEDIA_ID>/content`)

  .withMethod("GET")

  .withQueryParam("sdkId", "<YOTI_CLIENT_SDK_ID>")

  .build();

​

//get Yoti response

const response = request.execute();

The response will be returned as a JSON object and image media will be returned as a buffer string.

Session & Media Deletion

It is possible to delete a session or session media before the defined retention period (ttl) is over. However, this can only be done once the session is completed. Deleting the session will also delete all media from that session. Deleting a media object will delete only that specific object, leaving the rest of the session untouched.

For more information about DELETE requests see our API references

Session Deletion

• withMethod should be set to DELETE
• The withEndpoint should be set to /sessions/SESSION_ID where SESSION_ID should be replaced with the SESSION_ID obtained in Create a Session.

Media Deletion

Please note the:

• withMethod should be set to DELETE
• The withEndpoint should be set to /sessions/SESSION_ID/media/MEDIA_ID/content where SESSION_ID should be replaced with the SESSION_ID obtained in Create a Session and MEDIA_ID should be replaced with the MEDIA_ID obtained in the get session request.

Retrieved Resources

The resources retrieval returns back details and resources of the id document and liveness check depending on what tasks and checks you request.

ID Document Resources

When the session is retrieved there will be details regarding the ID document and associated tasks.

Liveness Capture Resources

If a liveness check is requested then it will generate resources.

Document fields explained

This is the JSON version of the user.

Explanation of the address format can be found here