Sandbox Integration Guide

Welcome to the free Identity verification Sandbox! The sandbox is an isolated test environment, intended to easily create test cases using dummy data where it's not feasible to test your integration with live data.

The sandbox environment will allow you to:

Set outcomes and mock text results
Mock approvals and rejections
Mock liveness and image upload

The main difference between our Yoti production services and sandbox is the sandbox bypasses real world checks and tasks. Instead, you must specify the outcome beforehand, as opposed to it being returned from Yoti’s production systems.

This is achieved by using an additional response-config endpoint. A response-config must be set before proceeding with the user view for sandbox setups.

Before you start

We recommend familiarising yourself with the production integration to ensure you create reliable tests that accurately simulate the production environment. You will also need some sandbox api keys.

Integration Guide Generate Sandbox Keys

An overview of the steps is shown below:

Step 1: Generating sandbox keys

Step 2: Installing the sandbox SDK

Step 3: Generating a sandbox session

Step 4: Configuring the response(breakdown version available too)

Step 5: Launching the user view

Supported Languages

Just like the normal Yoti Client, the Yoti Sandbox Client SDK is available in seven languages:

Install the Sandbox SDK

Once you have generated your keys, you can continue with installing the Sandbox SDK into your backend.

Just like our production integration, the Yoti Sandbox Client SDK is available in seven languages and installing is easy through popular package managers.

Javascript
Java
PHP
Python
C#
Go
Ruby
    
​x
 
// Doc Scan Client (skip if already installed)npm install -S -E yoti​// Sandboxnpm install -S -E -D @getyoti/sdk-sandbox
Copy

The sandbox client is packaged separately to the production Yoti client enabling it to be used as a development dependency.

Initialising the sandbox client

You will need your Sandbox Client SDK ID and PEM file created from the Yoti Hub to initialise the sandbox client.

Please do not open the pem file as this might corrupt the key and you will need to create a new sandbox key.

Javascript
Java
PHP
Python
C#
Go
Ruby
Java v2
    
 
// Point the IDV Client at the sandbox by setting environment variable // YOTI_IDV_API_URL to https://api.yoti.com/sandbox/idverify/v1​const { IDVClient } = require('yoti');const fs = require('fs');​const SANDBOX_CLIENT_SDK_ID = 'SANDBOX_CLIENT_SDK_ID';const PEM = fs.readFileSync('/path/to/your-pem-file.pem', 'utf8');​const idvClient = new IDVClient(SANDBOX_CLIENT_SDK_ID, PEM);// Alternatively - const idvClient = new IDVClient(SANDBOX_CLIENT_SDK_ID, PEM, { apiUrl: 'sandbox-api-url' });
Copy

Configuring the sandbox client

Javascript
Java
PHP
Python
C#
Go
Ruby
    
 
const { SandboxIDVClientBuilder } = require('@getyoti/sdk-sandbox');​const sandboxClient = new SandboxIDVClientBuilder()  .withClientSdkId(SANDBOX_CLIENT_SDK_ID)  .withPemString(PEM)  .build();
Copy

Generating a sandbox session

Before you start

Check out how to create a session with Identity verification for a full understanding of how the product works.

Integration guide

A sandbox session will be created by

1) Replace the base URL with the Sandbox URL.

2) Replace the SDK ID

3) Replacing the pem file.

HTTP
    
 
Sandbox - https://api.yoti.com/sandbox/idverify/v1Production - https://api.yoti.com/idverify/v1
Copy

Configure the responses

Before you start

Understand the results of a session and the report.

Retrieve results Understanding the report

Sandbox requires you to set an expected outcome for your tasks and checks.

Below is a snippet of a full response config for all checks and tasks. These values are provided to mock the return output of fetching the completed session. For a further explanation there is a breakdown version below.

Javascript
Java
PHP
Python
C#
Go
Ruby
    
 
const {
  SandboxIDVClientBuilder,  SandboxBreakdownBuilder,  SandboxRecommendationBuilder,  SandboxDocumentAuthenticityCheckBuilder,  SandboxCheckReportsBuilder,  SandboxResponseConfigBuilder,  SandboxDocumentTextDataCheckBuilder,  SandboxTaskResultsBuilder,  SandboxZoomLivenessCheckBuilder,  SandboxDocumentFaceMatchCheckBuilder,  SandboxDocumentTextDataExtractionTaskBuilder,} = require('@getyoti/sdk-sandbox');​const sandboxClient = new SandboxIDVClientBuilder()  .withClientSdkId('YOUR_SANDBOX_SDK_ID')  .withPemString('YOUR_PEM_FILE')  .build();​const sessionId = "YOUR_SANDBOX_SESSION_ID"​async function configureSessionResponse() {...}
​configureSessionResponse();
Copy

Async report delay

The Async report delay is a timer (in seconds) which simulates a delay between the Identity verification iFrame user journey and the result of the report, set by your expectation. By using this facility you can effectively handle pending states, or results that are not returned instantly (such as manual checks).

Sandbox Breakdown

This section will go into detail on each task and check with the configuration split out.

Task Results

Before you start

Understand the task extraction and how to retrieve the user results .

Retrieve results Retrieve user information

Data extraction task (ID Document)

The task result contains the extracted text, defined by the document_fields property. This should be used to mock extracted text from documents.

Javascript
Java
PHP
Python
C#
    
 
const {  SandboxDocumentTextDataExtractionTaskBuilder,} = require('@getyoti/sdk-sandbox');​const textExtractionConfig = new SandboxDocumentTextDataExtractionTaskBuilder()  .withDocumentFields({    full_name: 'John Doe',    nationality: 'GBR',    date_of_birth: '1986-06-01',    document_number: '123456789',  })  .build();
Copy

Data extraction task (Supplementary Document)

The supplementary task result contains the extracted text from the supplementary document, also defined by the document_fields property. This should be used to mock extracted text from supplementary documents.

Javascript
Java
PHP
Python
C#
    
 
​
Copy

Check Results

Before you start

Understand the results and the results of the checks .

Retrieve results Results of the checks

Sandbox will allow you to set a response for each of the checks Identity verification offers. Below are examples of the check result.

Document Authenticity

Yoti performs a numerous amount of sub checks on the document submitted, in order to simulate this report request you will need to understand the document report. Yoti will provide a recommendation for the authenticity of the document which you can mock using this service.

Javascript
Java
PHP
Python
C#
    
 
const {  SandboxBreakdownBuilder,  SandboxRecommendationBuilder,  SandboxDocumentAuthenticityCheckBuilder} = require('@getyoti/sdk-sandbox');​const documentAuthenticityCheckConfig = new SandboxDocumentAuthenticityCheckBuilder()  .withRecommendation(    new SandboxRecommendationBuilder().withValue('APPROVE').build(),  )  .withBreakdowns([    new SandboxBreakdownBuilder()      .withSubCheck('data_in_correct_position')      .withResult('PASS')      .build(),    new SandboxBreakdownBuilder()      .withSubCheck('document_in_date')      .withResult('PASS')      .build(),    new SandboxBreakdownBuilder()      .withSubCheck('expected_data_present')      .withResult('PASS')      .build(),    new SandboxBreakdownBuilder()      .withSubCheck('fraud_list_check')      .withResult('PASS')      .build(),    new SandboxBreakdownBuilder()      .withSubCheck('hologram')      .withResult('PASS')      .build(),    new SandboxBreakdownBuilder()      .withSubCheck('hologram_movement')      .withResult('FAIL')      .build(),    new SandboxBreakdownBuilder()      .withSubCheck('no_sign_of_tampering')      .withResult('PASS')      .build(),    new SandboxBreakdownBuilder()      .withSubCheck('other_security_features')      .withResult('PASS')      .build(),    new SandboxBreakdownBuilder()      .withSubCheck('real_document')      .withResult('PASS')      .build(),  ])  .build();
Copy

Data extraction check (ID Document)

Yoti will provide a recommendation for the text data extraction which will contain the sub-check text_data_readable which will either be a PASS or a FAIL.

Javascript
Java
PHP
Python
C#
    
 
const {  SandboxBreakdownBuilder,  SandboxRecommendationBuilder,  SandboxDocumentTextDataCheckBuilder} = require('@getyoti/sdk-sandbox');​const textDataCheckConfig = new SandboxDocumentTextDataCheckBuilder()  .withRecommendation(    new SandboxRecommendationBuilder().withValue('APPROVE').build(),  )  .withBreakdown(    new SandboxBreakdownBuilder()      .withSubCheck('text_data_readable')      .withResult('PASS')      .build(),  )  .withDocumentFields({    full_name: 'John Doe',    nationality: 'GBR',    date_of_birth: '1986-06-01',    document_number: '123456789',  })  .build();
Copy

Data extraction check (Supplementary Document)

Similar to ID Document data entry, a Text data check may be generated if a Supplementary document goes for manual data entry. This block would mock the relevant response:

Javascript
Java
PHP
Python
C#
    
 
​
Copy

Liveness

Liveness checks can be retried if failed, depending on specified limited set when generating the session. Each try will generate a new breakdown in the response. The check will either be approved or rejected based on the result of the liveness check which is a pass/fail result. For more information head over to our production service.

Javascript
Java
PHP
Python
C#
    
 
const {  SandboxBreakdownBuilder,  SandboxRecommendationBuilder,  SandboxZoomLivenessCheckBuilder,} = require('@getyoti/sdk-sandbox');​const livenessCheckConfig = new SandboxZoomLivenessCheckBuilder()  .withRecommendation(    new SandboxRecommendationBuilder().withValue('APPROVE').build(),  )  .withBreakdown(    new SandboxBreakdownBuilder()      .withSubCheck('liveness_auth')      .withResult('PASS')      .build()  )  .build()
Copy

Face Match

The face match check will give a recommendation based on these as either APPROVE or REJECT which can be mocked on sandbox.

A pass/fail result is returned if a manual check is also done, 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. or more information head over to our production service documentation.

Javascript
Java
PHP
Python
C#
    
 
const {  SandboxBreakdownBuilder,  SandboxRecommendationBuilder,  SandboxDocumentFaceMatchCheckBuilder,} = require('@getyoti/sdk-sandbox');​const faceMatchCheckConfig = new SandboxDocumentFaceMatchCheckBuilder()  .withRecommendation(    new SandboxRecommendationBuilder().withValue('APPROVE').build(),  )  .withBreakdowns([    new SandboxBreakdownBuilder()      .withSubCheck('ai_face_match')      .withResult('FAIL')      .withDetail('confidence_score', '0.53')      .build(),    new SandboxBreakdownBuilder()      .withSubCheck('manual_face_match')      .withResult('PASS')      .build()  ])  .build();
Copy

Completing the session

Once you have set your sandbox response config, you will need to complete the session for Identity verification. This will populate the media and will complete the session.

The Agent endpoint /agent uses the SDK ID and .PEM file for authorisation.

HTTP
    
 
POST https://api.yoti.com/sandbox/idverify/v1/agent​AUTH: X-Yoti-Auth-DigestBODY: {See below}
Copy

HTTP
PHP
.NET
    
 
POST https://api.yoti.com/sandbox/idverify/v1/agent​AUTH: X-Yoti-Auth-DigestBODY: {See below}
Copy

Body

JSON
    
 
{  "session_id": "UUIDstring",  "client_session_token": "UUIDstring",  "resources": {    "id_documents": [      {        "issuing_country": "GBR",        "document_type": "string",        "capture_method": "CAMERA"      },   {        "issuing_country": "GBR",        "document_type": "string",        "capture_method": "CAMERA"      }​    ],    "supplementary_documents": [      {        "issuing_country": "GBR",        "document_type": "string"      }    ]  }}
Copy

Field	Details
Session ID	The UUID String returned when creating the session
Client Session Token	The UUID String returned when creating the session
Resources	This should match any filters you have set up in the session configuration
Issuing Country	3-letter ISO code string
Document Type	String eg PASSPORT, DRIVING_LICENCE

Responses

Code	Desciption
204	OK, completed with no content
400	Invalid payload
401	Unauthorized
500	Server Error
503	Temporarily Unavailable

Retrieving images and user information

Before you start

Understand how to retrieve the images in production.

Retrieve Images

Retrieving the media response is the same as production. Please ensure your base URL is updated to the below:

HTTP
    
 
https://api.yoti.com/sandbox/idverify/v1
Copy

For further details, please see Understanding the report.

Last updated on

Was this page helpful?