Title
Create new category
Edit page index title
Edit category
Edit link
IDP Sandbox
The Yoti Identity Profiles (IDP) 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
Ensure you have submitted your Yoti Hub organisation for verification 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.
xxxxxxxxxxnpm 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
xxxxxxxxxxconst { 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 identity profile scheme is used.
xxxxxxxxxxconst path = require('path');const fs = require('fs'); const { IDVClient, AdvancedIdentityProfileSchemeBuilder, AdvancedIdentityProfileBuilder, AdvancedIdentityProfileRequirementsBuilder SessionSpecificationBuilder, SdkConfigBuilder,} = require('yoti'); const YOTI_CLIENT_SDK_ID = 'YOTI_CLIENT_SDK_ID';const YOTI_PEM = fs.readFileSync(path.join(__dirname, '/path/to/pem'));const idvClient = new IDVClient(YOTI_CLIENT_SDK_ID, YOTI_PEM); const subject = { subject_id: 'subject_id_string',}; ]const advancedIdentityProfileScheme = new AdvancedIdentityProfileSchemeBuilder() .withType('DBS') .withObjective('STANDARD') .withLabel('DBS-EXAMPLE') .build(); const advancedIdentityProfile = new AdvancedIdentityProfileBuilder() .withTrustFramework('UK_TFIDA') .withScheme(advancedIdentityProfileScheme) .build(); const advancedIdentityProfileRequirements = new AdvancedIdentityProfileRequirementsBuilder() .withProfile(advancedIdentityProfile) .build(); const sdkConfig = new SdkConfigBuilder() .withAllowHandoff(true) .withSuccessUrl(`${APP_BASE_URL}/success`) .withErrorUrl(`${APP_BASE_URL}/error`) .build(); const sessionSpec = new SessionSpecificationBuilder() .withSubject(subject) .withAdvancedIdentityProfileRequirements(advancedIdentityProfileRequirements) .withSdkConfig(sdkConfig) .build(); const session = await idvClient.createSession(sessionSpec); const sessionId = session.getSessionId();const clientSessionToken = session.getClientSessionToken();More details on how to create a session can be found here
| Trust Framework | Scheme Type | Objective | Description |
|---|---|---|---|
| UK_TFIDA | RTW | N/A | UK certified right to work verification. |
| UK_TFIDA | RTR | N/A | UK certified right to rent verification. |
| UK_TFIDA | DBS | BASIC, STANDARD, ENHANCED | UK certified digital method for verifying a person's identity for criminal record checks |
| YOTI_GLOBAL | IDENTITY | AL_L1, AL_M1 | Yoti created Identity verification that can be set to a low assurance "L1" or a medium assurance "M1". The medium assurance adds a biometric face match. |
| YOTI_GLOBAL | IDENTITY_PLUS_ADDRESS | AL_L1, AL_M1 | Yoti created Identity verification that can be set to a low assurance "L1" or a medium assurance "M1". The medium assurance adds a biometric face match. An address check will also be performed. |
| YOTI_GLOBAL | GBR_RTW_SHARECODE | N/A | Yoti created verification that will fetch a users share code details and compare them to details extracted from a users Id documents. |
| YOTI_GLOBAL | CAN_CRC | N/A | Yoti created Identity verification that will verify a document and perform a biometric face match. For the Canadian Criminal Record Check. |
Step 3a: Launch the user view (manual testing)
Construct the following URL for manual testing, and render it inside an iFrame:
xxxxxxxxxxhttps://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
xxxxxxxxxxPOST 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
xxxxxxxxxx{ "session_id": "YOUR_SESSION_ID", "client_session_token": "YOUR_SESSION_TOKEN"}Code examples
xxxxxxxxxxconst { 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.
xxxxxxxxxx// 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(); // Identity Profile const advancedIdentityProfile = sessionResult.getAdvancedIdentityProfile(); const report = advancedIdentityProfile.getIdentityProfileReport(); // Biometric consent const biometricConsent = session.getBiometricConsentTimestamp(); console.log('Session completed successfully');}).catch(error => { console.error('Error retrieving session:', error);});More details on how to retrieve the results can be found here
Example sandbox response
Here is a sample JSON response from a finished sandbox session:
xxxxxxxxxx{ "client_session_token_ttl": 8889, "session_id": "09065a5e-ab48-4507-9d39-b061606def09", "state": "COMPLETED", "resources": {...}, "checks": [...], "advanced_identity_profile": {...}}Default responses
The sandbox automatically provides approved results for the checks using sample data which will result in an overall pass, for the configured scheme. for example:
- Document authenticity: APPROVE
- Liveness: APPROVE
- Face match: APPROVE
- Third party identity: APPROVE
- Fraud check: APPORVE
- DBS scheme: REQUIREMENTS MET
- 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.
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.