Sandbox

AI Tools

The Yoti In-Branch Verification (IBV) Sandbox is an isolated testing environment for validating your integration with mock data and simulated verification outcomes.

What you can do

Test end-to-end flows without real user data
Simulate different verification outcomes (approvals, rejections, extractions)
Use standard Yoti backed SDKs (no separate sandbox SDK)
Manually test using the user view, or automate testing (via built-in agent) by bypassing the in-branch experience.

Key differences

Sandbox uses the same SDKs as production but requires:

Sandbox URL: https://api.yoti.com/sandbox/idverify/v1
Sandbox keys from Yoti Hub
Predefined successful responses by default
Optional response configuration (see Configure response)

Ensure you have a verified Yoti Hub account and have generated sandbox keys.

Sandbox keys

Install the SDK

Install the Yoti SDK using your language's package manager. The same SDK is used for both production and sandbox environments.

Javascript
PHP
Python
Java
Go
    
 
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 request.

Step 1: Create the session

Create an in-branch verification session exactly as you would in production. The session configuration determines what checks and tasks will be performed.

Endpoint:

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

Node.js
PHP
Python
Java
Go
    
​x
 
const { RequestBuilder, Payload } = require("yoti");​const request = new RequestBuilder()  .withBaseUrl("https://api.yoti.com/sandbox/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

Example Session Creation

Claimed ID JSON
Resultant ID JSON
Hybrid ID JSON
    
 
{    "session_deadline": "2023-10-15T22:00:00Z",    "resources_ttl": "604800",    "ibv_options": {        "support": "MANDATORY"    },    "user_tracking_id": "optional_string",    "notifications": {        "endpoint": "https://some-domain.example",        "topics": [            "INSTRUCTIONS_EMAIL_REQUESTED",            "THANK_YOU_EMAIL_REQUESTED",            "SESSION_COMPLETION"        ]    },    "requested_checks": [        {            "type": "IBV_VISUAL_REVIEW_CHECK",            "config": {                "manual_check": "IBV"            }        },        {            "type": "PROFILE_DOCUMENT_MATCH",            "config": {                "manual_check": "IBV"            }        },        {            "type": "DOCUMENT_SCHEME_VALIDITY_CHECK",            "config": {                "manual_check": "IBV",                "scheme": "UK_DBS"            }        }    ],    "required_documents": [        {            "type": "ID_DOCUMENT",            "filter": {                "type": "DOCUMENT_RESTRICTIONS",                "inclusion": "WHITELIST",                "documents": [                    {                        "country_codes": ["GBR"],                        "document_types": ["PASSPORT"]                    }                ]            }        },        {            "type": "ID_DOCUMENT",            "filter": {                "type": "DOCUMENT_RESTRICTIONS",                "inclusion": "WHITELIST",                "documents": [                    {                        "country_codes": ["GBR"],                        "document_types": ["DRIVING_LICENCE"]                    }                ]            }        },        {            "type": "SUPPLEMENTARY_DOCUMENT",            "document_types": ["UTILITY_BILL"],            "country_codes": ["GBR"],            "objective": {                "type": "UK_DBS"            }        }    ],    "resources": {        "applicant_profile": {            "full_name": "John James Doe",            "date_of_birth": "1988-11-02",            "structured_postal_address": {                "address_format": 1,                "building_number": "74",                "address_line1": "74 First Address Line",                "town_city": "London",                "postal_code": "E14 3RN",                "country_iso": "GBR",                "country": "United Kingdom"            }        }    }}
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

Step 2: Configure sandbox response

Now that you have successfully created a session, the next step is to set the response config. This is an optional step. If no response is configured, Yoti will use a default successful response. But you do have the option to set an expected outcome for your Yoti tasks and checks. This will be an object with defined task_results and check_reports.

Endpoint:

HTTP
    
 
https://api.yoti.com/sandbox/idverify/v1/sessions/<SESSION_ID>/response-config
Copy

Javascript
PHP
Python
Java
Go
    
 
const { RequestBuilder, Payload } = require("yoti");​const request = new RequestBuilder()  .withBaseUrl("https://api.yoti.com/sandbox/idverify/v1")  .withPemFilePath("<YOTI_KEY_FILE_PATH>")  .withEndpoint("/sessions/<SESSION_ID>/response-config")  .withPayload(new Payload(RESPONSE_CONFIG))  .withMethod("PUT")  .withQueryParam("sdkId", "<YOTI_CLIENT_SDK_ID>")  .build();​//get Yoti responseconst response = request.execute();
Copy

Example Response Configuration

Claimed ID JSON
Resultant ID JSON
Hybrid ID JSON
    
 
{    "check_reports": {        "IBV_VISUAL_REVIEW_CHECK": [            {                "result": {                    "report_template": "SUCCESS"                }            }        ],        "DOCUMENT_SCHEME_VALIDITY_CHECK": [            {                "result": {                    "report_template": "SUCCESS"                }            }        ],         "PROFILE_DOCUMENT_MATCH": [            {                "result_template": "SUCCESS"            }        ]    }}
Copy

On completion of this API request, you will simply receive a 200 response.

In the sandbox you can configure both successful outcomes of checks and unsuccessful outcomes of checks to mock multiple different scenarios. The below table outlines the different scenarios that can be mocked.

Checks

Check	Report template	Description
ID_DOCUMENT_AUTHENTICITY	SUCCESS	This simulates a "APPROVE" outcome for the document authenticity check
ID_DOCUMENT_AUTHENTICITY	TAMPERED	This simulates a "REJECT" outcome for the document authenticity check, due to a fraudulent document.
ID_DOCUMENT___AUTHENTICITY	DOCUMENT_COPY	This simulates a "REJECT" outcome for the document authenticity check, due to an image of a document being used instead of a live capture.
ID_DOCUMENT_AUTHENTICITY	PHOTO_TOO_BLURRY	This simulates a "NOT_AVAILABLE" outcome for the document authenticity check, due a blurry image.
ID_DOCUMENT_AUTHENTICITY	FRAUD_LIST_MATCH	This simulates a "REJECT" outcome for the document authenticity check, due to a fraudulent document.
ID_DOCUMENT_AUTHENTICITY	GLARE_OBSTRUCTION	This simulates a "NOT_AVAILABLE" outcome for the document authenticity check, due to glare obstruction.
ID_DOCUMENT___FACE_MATCH	SUCCESS	This simulates a "APPROVE" outcome for the face match check.
ID_DOCUMENT___FACE_MATCH	AUTO_FAIL	This simulates a "REJECT" outcome for the face match check. With the automated sub check failing.
ID_DOCUMENT_FACE_MATCH	MANUAL_FAIL	This simulates a "REJECT" outcome for the face match check. With the manual sub check failing.
ID_DOCUMENT_FACE_MATCH	FAIL	This simulates a "REJECT" outcome for the face match check. With both the automated and the manual sub check failing.
ID_DOCUMENT_TEXT_DATA_EXTRACTION	SUCCESS	This simulates a "APPROVE" outcome for the manual data extraction.
ID_DOCUMENT_TEXT_DATA_EXTRACTION	EXTRACTION_FAILED	This simulates a "REJECT" outcome for the manual data extraction.

Tasks

Task	Report template	Description
ID_DOCUMENT_TEXT_DATA_EXTRACTION	SUCCESS	This simulates a successful automated data extraction task.
ID_DOCUMENT_TEXT_DATA_EXTRACTION	UNSUPPORTED_DOCUMENT	This simulates an unsuccessful automated data extraction task.
ID_DOCUMENT_TEXT_DATA_EXTRACTION	DOCUMENT_IS_EXPIRED	This simulates a unsuccessful automated data extraction task.
ID_DOCUMENT_TEXT_DATA_EXTRACTION	UNABLE_TO_OCR	This simulates a unsuccessful automated data extraction task.

Step 3: Bypass In-Branch experience

Once you have set your sandbox response config, bypass the user view by making an API call to mock the user flow. The session Id and session token created in the earlier create session step must be used in the payload for this API request to work.

Endpoint

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

Example Request

Javascript
PHP
Python
Java
Go
    
 
const { RequestBuilder, Payload } = require("yoti");​const request = new RequestBuilder()  .withBaseUrl("https://api.yoti.com/sandbox/idverify/v1")  .withPemFilePath("<YOTI_KEY_FILE_PATH>") // file path to PEM file  .withEndpoint("/agent")  .withPayload(new Payload(SKIP_UI))  .withMethod("POST")  .withQueryParam("sdkId", "<YOTI_CLIENT_SDK_ID>")  .build();​//get Yoti responseconst response = await request.execute();
Copy

Payload Example

JSON
    
 
{  "session_id": "YOUR_SESSION_ID",  "client_session_token": "YOUR_SESSION_TOKEN",}
Copy

Last updated by Josh Steadman on Mar 24, 2026

Was this page helpful?