Run work-rights checks
The VEVO checks module checks a new starter's right to work in Australia as part of onboarding. Employees who are not Australian citizens consent to a check with the Department of Home Affairs Visa Entitlement Verification Online (VEVO) service, and SuperAPI returns the outcome, the visa details and the VEVO result PDF on the onboarding session. Australian citizens upload proof of citizenship for the employer to review instead.
This guide covers turning the module on, requesting a check for a hire, what the employee sees, how to read the result, and how to test it in sandbox.
Turn on work-rights checks
Contact SuperAPI to turn on work-rights checks for your partner and we will set it up.
Request a check
A work-rights check is requested per hire on an onboarding session intent. A session created without an intent never includes the step. There are two ways to request it.
From your API
Pass work_rights_check: true when you create the intent. It is a boolean and defaults to false.
curl -X POST https://api.superapi.com.au/api/v1/onboarding-session-intent \
-H "Content-Type: application/json" \
-H "x-api-key: superapiproduct_yourkeyQvyaXOF" \
-d '{
"employer_id": "45910b12-d2e7-4ebc-8033-f014a7efc88b",
"remote_id": "hire-1",
"work_rights_check": true
}'The value is returned whenever you fetch the intent. If work-rights checks are not turned on for your partner, a request with true is rejected with a validation error on work_rights_check saying it is not enabled for this partner.
From the employer
In the intent embed's customise onboarding page, the employer can switch on Check the employee's right to work in Australia. The option is only shown when work-rights checks are turned on for your partner.
Either way, the onboarding session created from the intent includes the work-rights step straight after the TFN declaration.
What the employee does
The step asks "What is your citizenship?" with three answers: Australian citizen, New Zealand citizen, and Citizen of another country. The answer picks one of two routes.
VEVO route
New Zealand citizens and citizens of other countries, including permanent residents, go through a VEVO check.
The employee's given name, family name and date of birth are prefilled from earlier steps, labelled as shown on their document, and can be edited. Edits stay on the check and do not change the employee record. Names must be in Latin script.
The document defaults to a passport. Choosing "I don't have a passport" reveals the other accepted documents: ImmiCard, Document for Travel to Australia (DFTTA), PLO56 evidence card and Convention Travel Document. The employee enters the document number and the nationality on the document. Nationality defaults to New Zealand for New Zealand citizens.
The employee must tick a consent box before the check can be submitted. The time of consent is recorded.
Document route
Australian citizens are shown a collection notice, then upload one of:
- An Australian passport. One file, the photo page.
- A birth certificate or citizenship certificate plus a photo ID. Two files.
A birth certificate is only accepted for people born before 20 August 1986, and it must be the full certificate, not an extract. Each file is a PDF, JPEG or PNG up to 10 MB.
After submitting
On both routes, submitting completes the step. The employee moves on and cannot resubmit. They see a neutral "submitted" confirmation and never see the result. They do not wait for the check to settle. If the employee leaves the step before submitting, nothing is stored.
Read the result
The result is the work_rights key on the onboarding session. Fetch the session as usual. The key is present only when the session includes the work-rights step, and is null until the employee submits.
| Field | Description |
|---|---|
id | The check's id (UUID) |
onboarding_session_id | The onboarding session the check belongs to |
method | vevo or document |
outcome | The result of the check. See the outcomes table below |
submitted_at | When the employee submitted the check |
checked_at | When the check settled. null while the outcome is pending |
visa | The visa VEVO reported. null unless the outcome is unlimited_work_rights, limited_work_rights or no_work_rights. Holds subclass, type_name, grant_date, expiry_date (null for a visa that does not expire), entitlement_description and conditions, an array of {code, description} |
checked_details | The details the employee was checked against, as shown on their document. null on the document method. Holds given_name, family_name, date_of_birth, document_type (one of passport, immicard, convention_travel_document, dftta, plo56_evidence_card) and nationality as a lowercase ISO 3166-1 alpha-3 code, such as nzl |
generated | Evidence produced by the check. vevo_pdf_url is a download link for the VEVO result PDF, or null. documents is an array of {kind, url} with kind one of australian_passport, birth_certificate, citizenship_certificate or photo_id. Always empty on the vevo method |
The document number is never returned.
A settled limited check looks like this:
{
"id": "0f9b2a5e-6c1d-4a8f-9d3b-2e7c4f1a8b60",
"onboarding_session_id": "c2bc0c04-6b98-4333-91a6-919f5ebc9000",
"method": "vevo",
"outcome": "limited_work_rights",
"submitted_at": "2026-03-02T04:15:09Z",
"checked_at": "2026-03-02T20:07:41Z",
"visa": {
"subclass": "500",
"type_name": "Student",
"grant_date": "2025-03-02",
"expiry_date": "2029-03-02",
"entitlement_description": "The visa holder has limited work rights in Australia. Check the visa conditions.",
"conditions": [
{
"code": "8105",
"description": "Work is limited to 48 hours a fortnight while the course is in session."
}
]
},
"checked_details": {
"given_name": "Jane",
"family_name": "Citizen",
"date_of_birth": "1990-04-12",
"document_type": "passport",
"nationality": "nzl"
},
"generated": {
"vevo_pdf_url": "https://...",
"documents": []
}
}Outcomes
| Outcome | Meaning |
|---|---|
pending | The VEVO check has not settled yet |
unlimited_work_rights | VEVO reports a visa with unlimited work rights |
limited_work_rights | VEVO reports a visa with limited work rights. Check visa.conditions |
no_work_rights | VEVO reports a visa with no work rights |
not_found | VEVO has no record matching the details the employee entered |
no_visa | VEVO found the person but they have no visa in effect |
could_not_be_checked | The check could not be completed, for example because VEVO was unavailable for three nights |
document_submitted | The employee used the document route. Final at submission |
Every value other than pending is final. There is no re-check or correction in this version.
Evidence links
vevo_pdf_url and each documents[].url are temporary links. They are regenerated each time you fetch the session and each one is valid for 6.5 days. Fetch the session again for a fresh link. There is one link per file. The VEVO PDF is present on the unlimited_work_rights, limited_work_rights and no_work_rights outcomes.
WARNING
SuperAPI never reads or verifies document-route uploads. The employer must check them and keep a record. Show the uploaded documents to the employer in your system.
When the session completes
While the outcome is pending, the session waits in pending_completion, the same way it waits for super registration. See the lifecycle of an onboarding session.
onboarding_session_completed fires once the outcome is final and super selection is done, so the completed session always carries the result. There is no separate work-rights webhook. onboarding_session_changed keeps firing while the session waits, for example when a member number arrives. See the list of webhooks.
VEVO checks run overnight, Sydney time. Most settle the morning after the employee submits. If VEVO is unavailable, SuperAPI retries for up to three nights, so a check can take about four days before it settles as could_not_be_checked. A document_submitted outcome never delays completion.
Test in sandbox
For sandboxed partners the VEVO check is simulated. The document number the employee enters picks the outcome. The check settles one minute after submission through the same path as a live check, so the session waits in pending_completion and then completes, and the webhooks fire.
| Document number | Outcome | Visa |
|---|---|---|
A01234567 | unlimited_work_rights | 189 Skilled Independent, no expiry |
M12345678 | limited_work_rights | 500 Student, condition 8105 |
10939000 | no_work_rights | 600 Visitor, condition 8101 |
12121212 | not_found | |
37373737 | no_visa | |
99999999 | could_not_be_checked | No retries in sandbox |
| Any other number | limited_work_rights | 500 Student, condition 8105 |
The three work-rights outcomes come with a PDF marked "SANDBOX. Not a real VEVO check". The document route behaves as it does live and settles as document_submitted at once.