Title
Create new category
Edit page index title
Edit category
Edit link
Sandbox
The Yoti Identity Verification (IDV) 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 user view.
Key differences
- 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.
Install the SDK
Install the Yoti SDK using your language's package manager. The same SDK is used for both production and sandbox environments.
npm install -S -E yotiStep 1: Initialise the client
Initialise the Yoti client with your sandbox credentials and point it to the sandbox URL.
Sandbox URL: https://api.yoti.com/sandbox/idverify/v1
const { IDVClient } = require('yoti');const fs = require('fs');const SANDBOX_CLIENT_SDK_ID = 'YOUR_SANDBOX_SDK_ID';const SANDBOX_PEM = fs.readFileSync('/path/to/your-sandbox-pem-file.pem', 'utf8');// Initialise client with sandbox URLconst idvClient = new IDVClient( SANDBOX_CLIENT_SDK_ID, SANDBOX_PEM, { apiUrl: 'https://api.yoti.com/sandbox/idverify/v1' });Step 2: Create a session
Create an identity verification session exactly as you would in production. The session configuration determines what checks and tasks will be performed.
const { SessionSpecificationBuilder, RequestedDocumentAuthenticityCheckBuilder, RequestedLivenessCheckBuilder, RequestedFaceMatchCheckBuilder, RequestedTextExtractionTaskBuilder, SdkConfigBuilder} = require('yoti');// Define checksconst documentAuthenticityCheck = new RequestedDocumentAuthenticityCheckBuilder().build();const livenessCheck = new RequestedLivenessCheckBuilder() .forStaticLiveness() .withMaxRetries(3) .build();const faceMatchCheck = new RequestedFaceMatchCheckBuilder() .withManualCheckFallback() .build();// Define tasksconst textExtractionTask = new RequestedTextExtractionTaskBuilder() .withManualCheckFallback() .build();// Configure SDKconst sdkConfig = new SdkConfigBuilder() .withAllowsCamera() .withPresetIssuingCountry('GBR') .withSuccessUrl('https://yourdomain.com/success') .withErrorUrl('https://yourdomain.com/error') .build();// Build session specificationconst sessionSpec = new SessionSpecificationBuilder() .withClientSessionTokenTtl(900) .withResourcesTtl(90000) .withUserTrackingId('some-unique-user-id') .withRequestedCheck(documentAuthenticityCheck) .withRequestedCheck(livenessCheck) .withRequestedCheck(faceMatchCheck) .withRequestedTask(textExtractionTask) .withSdkConfig(sdkConfig) .build();// Create sessionidvClient.createSession(sessionSpec) .then((session) => { const sessionId = session.getSessionId(); const clientSessionToken = session.getClientSessionToken(); console.log('Session created:', sessionId); }) .catch((err) => { console.error('Error creating session:', err); });Step 3a: Launch the user view (manual testing)
Construct the following URL for manual testing, and render it inside an iFrame:
https://api.yoti.com/sandbox/idverify/v1/web/index.html?sessionID={sessionID}&sessionToken={clientSessionToken}iFrame example
<iframe src="https://api.yoti.com/sandbox/idverify/v1/web/index.html?sessionID={sessionID}&sessionToken={clientSessionToken}" style="height:100vh; width:100%; border:none;" allow="camera"></iframe>Users can upload sample documents and selfies, and the sandbox returns predefined successful responses along with the uploaded image resources.
Step 3b: Use the agent endpoint (automated testing)
The /agent endpoint bypasses the user view and completes sessions programmatically with sample data—ideal for CI/CD and automated tests.
Endpoint
POST https://api.yoti.com/sandbox/idverify/v1/sessions/{sessionId}/agent| Use Case | Benefit |
|---|---|
| Automated tests | Skip manual document upload |
| CI/CD pipelines | Integrate verification in build process |
Payload structure
{ "session_id": "YOUR_SESSION_ID", "client_session_token": "YOUR_SESSION_TOKEN"}Code examples
const { RequestBuilder, Payload } = require("yoti");const payload = { session_id: sessionId, client_session_token: clientSessionToken};const request = new RequestBuilder() .withBaseUrl("https://api.yoti.com/sandbox/idverify/v1") .withPemFilePath(SANDBOX_PEM_PATH) .withEndpoint("/agent") .withPayload(new Payload(payload)) .withMethod("POST") .withQueryParam("sdkId", SANDBOX_CLIENT_SDK_ID) .build();// Execute requestconst response = await request.execute();Step 4: Retrieve session results
After the session is completed (either via user view or agent endpoint), retrieve the results to verify the outcome.
// Retrieve session resultidvClient.getSession(sessionId).then(session => { // Session state const state = session.getState(); // Resources (documents, images) const resources = session.getResources(); const idDocuments = resources.getIdDocuments(); // Checks const authenticityChecks = session.getAuthenticityChecks(); const livenessChecks = session.getLivenessChecks(); const faceMatchChecks = session.getFaceMatchChecks(); // Tasks const textExtractionTasks = session.getTextDataChecks(); // Biometric consent const biometricConsent = session.getBiometricConsentTimestamp(); console.log('Session completed successfully');}).catch(error => { console.error('Error retrieving session:', error);});Example sandbox response
Here is a sample JSON response from a finished sandbox session:
{ "client_session_token_ttl": 433, "session_id": "bfaf87e8-51dc-4ee4-be7b-8d4e3d8e9f41", "state": "COMPLETED", "resources": {...}, "checks": [...], "user_tracking_id": "12345"}Default responses
The sandbox automatically provides approved results for configured checks using sample data, for example:
- Document authenticity: APPROVE
- Liveness: APPROVE
- Face match: APPROVE
- Resources: Sample images and text extraction (Document fields)
This lets you test result handling without configuration.
Step 5: (Optional) Configure custom responses
To simulate failures or custom scenarios, refer to the sandbox Configure response guide. This lets you provide mock data such as for text extraction and also simulate partial check approvals or rejections.
You can use the same production SDKs for this as well.
Next steps
- Configure responses for testing partial or full rejections and custom text extraction.
- Understanding the results for complete session interpretation
- Example code for advanced verification scenarios
Troubleshooting
Session not completing? Verify you're using the sandbox URL: https://api.yoti.com/sandbox/idverify/v1
Authentication errors? Ensure you're using sandbox keys (not production) and haven't opened the PEM file manually.
Got a question? Contact us here.