To use API in sandbox mode, you just need a sandbox client secret. It will start with sandbox-. Otherwise, you can call the API in exactly the same way.
In sandbox mode, endpoints will validate the data you provide with your requests as normal, but:
they return test data
they do not process real verifications
they do not send real emails or text messages
are free to use
Not every endpoint supports sandbox mode. Check the API reference for details.
GetVerification
You can simulate retrieving different kinds of verification results by providing these IDs:
ID | Status | Outcome |
| In progress | New case with everything to do |
| Processing | User has submitted all evidence, results are processing |
| Verified | All checks passed automatically |
| Needs review | Some checks came back with results that require review |
| In progress | Partial completion, only the vouch step remains |
Example - Verified
Request
curl -X GET https://app.vouchsafe.id/api/v1/verifications/333 \ -H "Authorization: Bearer sandbox-your-token"
Response
json
{
"id": "333",
"status": "Verified",
"created_at": "2024-02-02T23:57:20.569Z",
"claim_details": {
"first_name": "Priya",
"last_name": "Nair",
"date_of_birth": "1988-01-27"
},
"checks": [
{
"step": "video_selfie",
"outcome": "pass",
"validations": {
"liveness_check": { "status": "pass", "score": 91 }
}
}
],
"enrichments": [
{ "check": "aml_sanctions", "outcome": "pass" }
]
}
This is a trimmed example, a real response includes the full set of required fields. See the API reference for the complete schema.
You can also filter the list endpoint by status, e.g. GET /verifications?status=Verified.
PerformSmartLookup
The Smart Lookups endpoint uses a last_name convention instead of test IDs. Set last_name to Pass or Fail to simulate a clean outcome across all checks you've requested.
Last Name | Outcome |
| All checks pass cleanly |
| All checks fail cleanly |
Names are case-insensitive, so pass, PASS and Pass all behave the same way.
You can use any first name and it will not affect the outcome - using any last name other than Pass or Fail returns a 400 error.
Address Format
You can submit your address in two formats:
Structured address (recommended):
"address": {
"residence_number": "10",
"street": "Downing Street",
"city": "London",
"postcode": "SW1A 2AA",
"country_code": "GB"
}Legacy flat fields:
"first_line_of_address": "10 Downing Street",
"postcode": "SW1A 2AA"
Example - Pass
Request
curl -X POST https://app.vouchsafe.id/api/v1/smart-lookups \
-H "Authorization: Bearer sandbox-your-token" \
-H "Content-Type: application/json" \
-d '{
"first_name": "Emily",
"last_name": "Pass",
"checks": ["OnlineFootprint", "AML", "CreditBureau"],
"email": "[email protected]",
"phone": "+447700900123",
"date_of_birth": "1990-01-01",
"address": {
"residence_number": "10",
"street": "Downing Street",
"city": "London",
"postcode": "SW1A 2AA",
"country_code": "GB"
}
}'
Response
{
"id": "sl_123",
"first_name": "Emily",
"last_name": "Pass",
"address": {
"residence_number": "10",
"street": "Downing Street",
"city": "London",
"postcode": "SW1A 2AA",
"country_code": "GB",
"country": "United Kingdom"
},
"credit_bureau_verification_report": {
"state": "PASS",
"checks": {
"IDENTITY_MATCH": { "state": "PASS" },
"RESIDENCY_MATCH": { "state": "PASS" }
}
},
"online_footprint_verification_report": {
"state": "PASS",
"checks": {
"EMAIL_SCORE": { "state": "PASS" },
"PHONE_SCORE": { "state": "PASS" }
}
},
"aml_verification_report": {
"state": "PASS",
"checks": {
"AML_SANCTIONS_CHECK": { "state": "PASS" }
}
},
"metadata": {
"creditBureauVerification": {
"status": "ok",
"validation_status": "FOUND",
"match_code_surname": "FULL"
},
"onlineFootprintVerification": {
"email": { "score": 85 },
"phone": { "score": 90 }
},
"amlVerification": {
"responses": {
"user": {
"total": 0,
"results": []
}
}
}
}
}
Example - Fail
Request
curl -X POST https://app.vouchsafe.id/api/v1/smart-lookups \
-H "Authorization: Bearer sandbox-your-token" \
-H "Content-Type: application/json" \
-d '{
"first_name": "Joe",
"last_name": "Fail",
"checks": ["OnlineFootprint", "AML", "CreditBureau"],
"email": "[email protected]",
"phone": "+447700900456",
"date_of_birth": "1995-05-15",
"address": {
"residence_number": "42",
"street": "Test Street",
"city": "London",
"postcode": "SW1A 2AA",
"country_code": "GB"
}
}'
Response
{
"id": "sl_123",
"first_name": "Joe",
"last_name": "Fail",
"address": {
"residence_number": "42",
"street": "Test Street",
"city": "London",
"postcode": "SW1A 2AA",
"country_code": "GB",
"country": "United Kingdom"
},
"credit_bureau_verification_report": {
"state": "FAIL",
"checks": {
"IDENTITY_MATCH": { "state": "FAIL" },
"RESIDENCY_MATCH": { "state": "FAIL" }
}
},
"online_footprint_verification_report": {
"state": "FAIL",
"checks": {
"EMAIL_SCORE": { "state": "FAIL" },
"PHONE_SCORE": { "state": "FAIL" }
}
},
"aml_verification_report": {
"state": "FAIL",
"checks": {
"AML_SANCTIONS_CHECK": { "state": "FAIL" }
}
},
"metadata": {
"creditBureauVerification": {
"identityMatches": 0,
"identityLastUpdate": null,
"residencyMatches": 0
},
"amlVerification": {
"responses": {
"user": {
"total": 1,
"results": [
{
"id": "mock-sandbox-match-001",
"caption": "Joe Fail",
"score": 0.95,
"first_seen": "2025-01-01",
"last_seen": "2025-12-31",
"properties": {
"notes": "Mock name match against sandbox datasets"
}
}
]
}
}
}
}
}
Important notes
Sandbox data is test data. Responses are pre-configured and don't reflect real-world outcomes. Test case IDs and names won't exist in production.
Validation is real. Request validation rules are identical to production, invalid or missing required fields are rejected the same way.
Authentication. Use your sandbox client secret (
sandbox-...). Sandbox and production tokens aren't interchangeable.