Create a Session

Every time an end user elects to supply an ID document on the relying party app/website/custom product, you will need to create a session with Yoti to perform the ID checks.

Before you start

You will need the Yoti App on your phone and to have registered your business with Yoti.

Onboarding with Yoti View Generate API Keys

API Link

Jump straight to our API references with code snippets if you prefer.

Yoti Doc Scan API

Generate the request using our SDK

Please use our Yoti SDKs to automatically build the relevant request.

The Yoti SDKs are available via popular dependency management systems.

Javascript
PHP
Python
Java
Go
C#
Ruby
    
 
npm install -S -E yoti
Copy

Once you have added the Yoti SDK dependency to your project, you can use it to build and send your request. See the code snippets below for examples of how to construct the promise.

Javascript
PHP
Python
Java
Go
C#
Ruby
    
​x
 
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")  .withPayload(new Payload(SESSION_OBJ))  .withMethod("POST")  .withQueryParam("sdkId", "<YOTI_CLIENT_SDK_ID>")  .build();​//get Yoti responseconst response = await request.execute();
Copy

Creating the session object

Below is the full payload example of the request for creating the session.

You will need to specify the following:

1) System preferences

Yoti Doc scan session length
User tracking
Status at certain points in the flow

2) Checks

ID Document Authenticity
Liveness
ID Document Face Match

3) Tasks

Document data extraction (OCR technology)

4) Client preferences

Camera and pre set country options and where the user should be directed after the user journey (success/error redirect URL)

Name	Acts on	Type	Comment
ID_AUTHENTICITY_CHECK	1x Document Resource	Asynchronous	Must wait for the TextDataCheck, if there is one.
TEXT_DATA_CHECK	1x Document Resource	Asynchronous	Used to recover a failed TextExtractionTask
LIVENESS_CHECK	1x Liveness Resource	Synchronous	Runs as soon as the FaceMap is uploaded. Can be repeated until it succeeds, but only one successful Check is allowed in each Session.
FACEMATCH_CHECK	1x Doc Resource & 1x Liveness Resource	Asynchronous	Must wait for the TextDataCheck, if there is one

Good to know

The request payload should be in the following format (full details of request parameters are provided in the 'explained' section, below). This JSON string will be the SESSION_OBJ parameter in the withPayload above code snippet.

JSON
    
 
{  "client_session_token_ttl": 600,  "resources_ttl": 604800,  "user_tracking_id": "<YOUR_USER_ID>",  "notifications": {    "endpoint": "https://yourdomain.example/idverify/updates",    "topics": [      "resource_update",      "task_completion",      "check_completion",      "session_completion"    ],    "auth_token": "username:password"  },  "requested_checks": [  {    "type": "ID_DOCUMENT_AUTHENTICITY",    "config": {    }  },  {    "type": "LIVENESS",    "config": {      "liveness_type": "ZOOM",      "max_retries": 3    }  },  {    "type": "ID_DOCUMENT_FACE_MATCH",    "config": {      "manual_check": "FALLBACK"    }  }  ],  "requested_tasks": [    {      "type": "ID_DOCUMENT_TEXT_DATA_EXTRACTION",      "config": {        "manual_check": "FALLBACK"      }    }  ],  "sdk_config": {    "allowed_capture_methods": "CAMERA_AND_UPLOAD",    "primary_colour": "#2d9fff",    "preset_issuing_country": "USA",    "success_url": "https://yourdomain.example/success",    "error_url": "https://yourdomain.example/error"  }}
Copy

Example response

If the request is successful and a session is generated the API will send a response in the form:

JSON
    
 
{  "client_session_token_ttl": 599,  "client_session_token": "<uuid>",  "session_id": "<uuid>"}
Copy

Response	Description
client_session_token_ttl	Time in seconds until the client session expires
client_session_token	Used to authenticate the session
session_id	ID of the session

Creating Sessions explained

1. System preferences

The table below explains the optional parameters for the session and data retention configuration.

JSON
    
 
"client_session_token_ttl": 600,  "resources_ttl": 604800,  "user_tracking_id": "<uuid>",  "notifications": {    "endpoint": "https://yourdomain.com/idverify/updates",    "topics": [      "resource_update",      "task_completion",      "check_completion",      "session_completion"    ],    "auth_token": "XXX"  }
Copy

Parameters	Description	Required
client_session_token_ttl	This is how long the full Yoti Doc Scan session is open for in seconds. This must be longer than 5 minutes.	optional
resources_ttl	Retention period for uploaded documents/images in number of seconds. Default is one week (`606024*7=604800`). This can be a minimum of 24 hours and must be at least 24 hours longer than the client_session_token_ttl. This starts once the `client_session_token_ttl` is completed.	optional
user_tracking_id	Allows the relying business backend to track the same user across multiple sessions. Note: Should not contain any personal identifiable information.	optional
notifications { }	If provided, Yoti Doc Scan posts (POST endpoint required) an update notification every time the session state changes, based on the selected subscription topics "endpoint" : "https://yourdomain.com/idverify/updates". Only HTTPS endpoints with TLS are supported. If there is no 'topics' array then only session completion notifications are sent.	optional
auth_token	Allows the relying business backend to define an authorisation token, if they have secured API endpoints, allowing Yoti to call endpoints.	optional

Knowledge base

Please head over to our knowledge base for more information on notifications or selecting multiple documents / countries.

Notifications Document / Country selection

2. Checks Configuration

1) ID Document authenticity

A request to assess the characteristics of a document, to determine the validity of the ID document.

JSON
    
 
"requested_checks": [    {      "type": "ID_DOCUMENT_AUTHENTICITY",      "config": {}    },  ]
Copy

This requires there to be image media attached to the resource (images of the front and back of the document - the back of the document is not always required).

Jump to..

On successful completion, the check outputs a report in the form of a structured JSON object, which can be found in the ‘retrieve results’ section. Updates are sent to the updates URL (if subscribed to notifications).

Retrieve results and data ID Document authenticity results

2) Liveness

A requested check to assess whether the document scan is being performed by a real person and not someone wearing a mask or an automated system.

JSON
    
 
"requested_checks": [    {      "type": "LIVENESS",      "config": {        "liveness_type": "ZOOM", // Required        "max_retries": 3 // Required, must be greater than 0      }    }  ]
Copy

You must provide the max number of retries your users can have before the liveness is failed. This must be greater than 1.

An "attempt" is a completed liveness check that is either rejected or approved. If the user does not complete the liveness check this does not count as an attempt and the user will be prompted to try again.

Liveness check

Jump to

This will produce a liveness_capture resource in the session as well as a report in the form of a structured JSON object for each attempted liveness check.

Retrieve results and data Liveness results

3) ID Document face match

A request to assess whether the user's face matches the face on the ID document. The user's facial image is obtained from the liveness check, which must be performed first.

JSON
    
 
"requested_checks": [    {      "type": "ID_DOCUMENT_FACE_MATCH",      "config": {        "manual_check": "FALLBACK" // | "NEVER" | "ALWAYS"      }    }  ]
Copy

This is performed as an automated check, however you can configure whether the check is passed on to our security centre for a manual check by qualified Yoti staff. This can be set to always, fallback or never.

Manual Check	Explanation
ALWAYS	The requested check will always go to the security centre regardless of the success of the automated check.
NEVER	The requested check will never go to the security centre.
FALLBACK	The requested check will only go to the security centre if the machine check fails.

Jump to...

On successful completion, the check outputs a report in the form of a structured JSON object, which can be found in the ‘checks retrieval’ section of the session retrieval

Retrieve results and data ID Document face match results

3. Tasks Configuration

Yoti can complete the following optional task(s), if requested:

ID Document text data extraction

A request to obtain the data printed visually on a document, in structured form.

If machine data extraction is not successful, there is an option (selected at session creation) to fallback to manual data extraction. This generates a ‘text data check’ automatically, and the document is reviewed by one of our document processing experts.

JSON
    
 
"requested_tasks": [    {      "type": "ID_DOCUMENT_TEXT_DATA_EXTRACTION",      "config": {        "manual_check": "FALLBACK"      }    }  ]
Copy

Manual Data Extraction	Explanation
FALLBACK	This will initiate manual data extraction only if the automatic extraction fails. We strongly recommend this option.
NEVER	If the ID fails on automatic extraction, Yoti will not attempt manual extraction and will return a failure in the report.
ALWAYS	The document is always referred for manual review at Yoti's security centre, regardless of whether machine data extraction has succeeded or failed.

Jump to

On successful completion, see the task results section

Retrieve results and data Retrieved resources

Knowledge base

For more information on ID Document Text Data Extraction please head to our knowledge base.

Text extraction explained

4. Client Preferences

The method sdk_config is explained below. If not defined then they will be set to default (indicated)

JSON
    
 
"sdk_config": {    "allowed_capture_methods": "CAMERA_AND_UPLOAD"    "primary_colour": "#2d9fff",    "preset_issuing_country": "USA",    "success_url": "https://yourdomain.com/success",    "error_url": "https://yourdomain.com/error",    "locale": "en-GB"  }
Copy

Document capture

Type	Parameters (examples)	Description	Required
allowed_capture_methods	CAMERA_AND_UPLOAD, CAMERA(default)	The user must use a camera to take a photo of their ID document, or the user can take a photo or has the option to upload an image of the document from file.	optional
primary_colour	#2d9fff(default), #ff0000	Colours of the button provided in the frontend client as a hexadecimal value.	optional
preset_issuing_country	USA, GBR	The user must select the issuing country of the document they are uploading. This setting determines which issuing country is selected by default. NOTE: Must be a 3 letter ISO code.	optional
success_url	https://yourdomain.com/success	If the upload/photo is successfully captured redirect your users here. Yoti will then begin to carry out the requested checks and tasks. If undefined, the page will not redirect and you can listen to Yoti's post messages on the same page.	optional
error_url	https://yourdomain.com/error	If the upload/photo is unsuccessfully captured redirect your users here. If undefined, the user view will display an error screen, with the error code as a query parameter and won't redirect. (Details on the error codes can be found here.)	optional
locale	en-GB(default)	Force language locale for the frontend client. Full list shown below.	optional

Supported Documents Endpoint

To see all documents that are supported for Yoti Doc Scan you can send a GET request to our supported-documents endpoint. The request is built in a similar fashion to other Yoti requests, see the example promises below.

Javascript
PHP
Python
Java
Go
C#
Ruby
    
 
const { RequestBuilder } = require("yoti");​const request = new RequestBuilder()  .withBaseUrl("https://api.yoti.com/idverify/v1")  .withPemFilePath("<YOTI_KEY_FILE_PATH>")  .withEndpoint("/supported-documents")  .withMethod("GET")  .withQueryParam("sdkId", "<YOTI_CLIENT_SDK_ID>")  .build();​//get Yoti responseconst response = await request.execute();
Copy

Yoti will return a JSON object with countries listed by ISO country code. Each country will list an array of supported documents from that country. See the example below:

JSON
    
 
{   "supported_countries": [      {         "code": "AGO",         "supported_documents": [            {              "type": "DRIVING_LICENCE"            },            {              "type": "NATIONAL_ID"            },            {              "type": "PASSPORT"            }         ]      },      {         "code": "AIA",         "supported_documents": [            {              "type": "PASSPORT"            }         ]      }, ...
Copy

Last updated on

Was this page helpful?