How do I verify a user's eVisa using Vouchsafe's API?

You can programmatically verify a user’s UK Immigration Status, Right to Work, and Right to Rent using our eVisa verification API. This guide explains how to use the API and test different scenarios in our sandbox environment.

Testing in Sandbox and Production

Vouchsafe provides both verified production and sandbox environments.

Sandbox: Use this environment for development and testing. It simulates API responses without performing real verification checks with the Home Office.
Production: Use this environment for live checks. It validates real data against the Home Office database.

To use the API in sandbox mode, ensure you are authenticating with your Sandbox API keys.

Simulating Outcomes in Sandbox

When using the sandbox environment, you can trigger specific verification outcomes by using special pre-determined share codes. These allow you to test how your application handles passes, failures, and errors.

1. Successful Verification (Pass)

To simulate a successful check where the user verifies their status correctly:

Share Code: PASS12345
Result: Returns outcome: "pass"
Scenario: Validates Immigration Status, Right to Work, or Right to Rent successfully.

2. Failed Verification (Fail)

To simulate a check where the verification runs but the user does not meet the requirements (e.g., expired visa):

Share Code: FAIL12345
Result: Returns outcome: "fail"
Scenario: Simulates an expired immigration status or lack of right to work/rent.

3. System Error

To simulate an API error or an invalid state (e.g., share code locked out):

Share Code: ERROR1234
Result: Returns an HTTP error (e.g., 422 Unprocessable Entity)
Scenario: Simulates a scenario where the share code is invalid or has been used too many times.

Understanding API Outcomes

All verification responses will include an outcome field indicating the result of the check.

Outcome	Billable	Description
`Pass`	Yes	Verification completed successfully. All validations passed.
`Fail`	Yes	Verification completed, but one or more validations failed (e.g., expired document).
Error	No	A system failure or invalid input prevented verification from completing.

Retrieving Artefacts

A successful verified response includes links to download evidence. These URLs are secure and time-limited:

Document: A PDF copy of the eVisa summary.
Face Scan: The photo extracted from the eVisa profile.

Note: Download URLs expire after 30 minutes. You should download and store these files immediately if you need to keep a record.