vSure Visa Checks API v2

vSure visa check API

Brand banner

Visa Check

The Visa Check endpoint is where all the heavy lifting gets done by vSure to submit and return visa check results. vSure checks can be run for Australia and/or New Zealand across various use cases such as:

  • Work Rights check
  • Study Visa enquiry
  • Foreign citizen Identity Verification
  • Replacement of manual VEVO and Visa View checks

Create a Visa Check

Make a POST request to the /visa-checks endpoint as shown:

POST /v2/visa-checks HTTP/1.1

Host: platform.vsure.com.au
Authorization: Bearer ACCESS.TOKEN.HERE
Version: 2024-03-05 
Content-Type: application/json

Parameters

jurisdiction - Options:

  • AUS - Australia
  • NZL - New Zealand

environment - Options:

  • sandbox - Sandbox, sample data only
  • live - Production, live system for actual responses

mode - Options:

  • fastcheck - result in 5-20 seconds generally
  • offpeak - queued and processed 9pm to 6am AEST, regardless of the time of the request. Please use for high volume and

customer_authority_id - See Customer Authority page

visa_check_schema - Options:

  • australia
  • new_zealand

Requests can only be for one country. The jurisdiction, must match the schema and the array. For example:

  • "jurisdiction": "AUS"; must match
  • "visa_check_schema": "australia"; and must include
  • "australia": { "visa_check_type": "work"}; the specific array for Australia

AND

  • "jurisdiction": "NZL"; must match
  • "visa_check_schema": "new_zealand"; and must include
  • "new_zealand": { "approval_letter_start_date": "2023-11-01", "approval_letter_gender": "M"}; the specific array for New Zealand

===

australia array - only required for Australian visa checks

There are different types of visa checks in Australia. The main difference is the conditions returned. Most use cases will use work rights check.

visa_check_type - Options:

  • work - returns ALL visa types and work conditions. Work Rights, HR tech, KYC, identity verification and other use cases should use work
  • study - study is specifically for Higher Education / CRICOS market and returns study visa conditions only
  • agent - returns ALL visa types and conditions.

NOTE: agent checks are available exclusively for registered MARA agents and approved Legal Practitioners, whereby results include ALL visa conditions (e.g. health insurance condition 8501 which is not shown for either Work or Study checks). NOTE: The Customer Authority is compulsory for agent checks. Those wanting MARA Agent checks must use a MARA Agent / Legal Practitioner Immi account as the Customer Authority.

===

===

new_zealand array - only required for New Zealand visa checks

visa_check_type - determines the type of check performed. Options:

  • verification - default if not specified - visa verification
  • employer - employer work rights check

verification checks are available for all RealMe account holders, see here for Visa Verification Service details. New Zealand verification checks require information from the visa holder's passport and visa grant letter. The visa grant letter details are unique to New Zealand and thus appear in the new_zealand array:

approval_letter_start_date - date format: yyyy-mm-dd

approval_letter_gender - NZ Immigration currently only accepts binary gender, which is specified on the visa grant letter. Options:

  • m - male
  • f - female

employer checks are available exclusively for registered New Zeland businesses, with a NZ Business Number and a NZ ACC number. You must also register for Employer VisaView. employer checks do not require approval_letter_start_date nor approval_letter_gender and thus are optional in the NZ array.

===

document Array

type - The travel document type used to perform the visa check Options:

  • passport - for passport documents (most common document type used in Australia and only option available for New Zealand)

The following alternate travel documents only apply to the Australia schema:

  • immicard - for Australian Immigration cards
  • dftta - for "Document for Travel to Australia" documents
  • pl056 - for PL056 (uncommon but supported)
  • titre_de_voyage - for Titre de Voyage (uncommon but supported)

identifier - document number

country - ISO 3 country code for Nationality / Country of citizenship. For list see: IBAN ISO 3 Country Codes. A RESTful API resource, maintained by vSure, mapping country name and ISO code is available upon request.

family_name - Family name on travel document

given_name - Given name on travel document (Optional)

date_of_birth - Date of birth in date format yyyy-mm-dd

Create a Visa Check - Australia

Make a POST request to the /visa-checks endpoint as shown:

POST /v2/visa-checks HTTP/1.1

Host: platform.vsure.com.au
Authorization: Bearer ACCESS.TOKEN.HERE
Version: 2024-03-05 
Content-Type: application/json 


{
    "jurisdiction": "AUS",
    "environment": "sandbox",
    "mode": "fastcheck",
    "customer_authority_id": "{{recently_created_ca_id}}",
    "visa_check_schema": "australia",
    "australia": {
        "visa_check_type": "work"
    },
    "document": {
        "type": "passport",
        "identifier": "77777777",
        "country": "IND",
        "family_name": "Smith",
        "given_name": "John",
        "date_of_birth": "2000-01-01"
    }
}

When completed correctly, the response will be the visa check resource.

201 Created

Content-Type: application/json 
Location: https://platform.vsure.com.au/v2/visa_check/vc_sa4mp13


{
    "data": {
        "id": "vc_YXwfYM9tKAJX",
        "environment": "sandbox",
        "mode": "fastcheck",
        "jurisdiction": "AUS",
        "status": "pending",
        "requested_at": "2024-05-21T05:14:43.797Z",
        "customer_authority_id": null,
        "expired_at": null,
        "checked_at": null,
        "purged_at": null,
        "purged_by": null,
        "visa_check_schema": "australia",
        "australia": {
            "visa_check_type": "study"
        },
        "document": {
            "country": "IND",
            "identifier": "77777777",
            "type": "passport",
            "given_name": "John",
            "family_name": "Smith",
            "date_of_birth": "1999-01-01"
        },
        "extra": null,
        "visa": null,
        "attachments": []
    },
    "meta": {
        "links": {
            "self": "https://platform.vsure.com.au/v2/visa-checks/vc_YXwfYM9tKAJX"
        }
    }
}

Create a Visa Verification Check - NZ

Make a POST request to the /visa-checks endpoint as shown:

POST /v2/visa-checks HTTP/1.1

Host: platform.vsure.com.au
Authorization: Bearer ACCESS.TOKEN.HERE
Version: 2024-03-05 
Content-Type: application/json 


{
    "jurisdiction": "NZL",
    "environment": "sandbox",
    "mode": "fastcheck",
    "customer_authority_id": "{{recently_created_ca_id}}",
    "visa_check_schema": "new_zealand",
    "new_zealand": {
         "visa_check_type": "verification"
		"approval_letter_start_date": "2023-11-01",
        "approval_letter_gender": "M"
    },
    "document": {
        "type": "passport",
        "identifier": "V1212121",
        "country": "AUS",
        "family_name": "Doe",
        "given_name": "John",
        "date_of_birth": "1995-12-24"
    }
}

When completed correctly, the response will be the visa check resource.

201 Created

Content-Type: application/json 
Location: https://platform.vsure.com.au/v2/visa_check/vc_sa4mp13

{
    "data": {
        "id": "vc_sa4mp1e",
        "environment": "sandbox",
        "mode": "fastcheck",
        "jurisdiction": "NZL",
        "status": "pending",
        "requested_at": "2023-11-14T04:12:20.932Z",
        "authority": null,
        "customer_authority_id": "ca_sa4mp1e",
        "checked_at": null,
        "expired_at": null,
        "purged_at": null,
        "purged_by": null,
        "document": {
            "type": "passport",
            "identifier": "V1212121",
            "country": "NZL",
            "family_name": "Doe",
            "given_name": "John",
            "date_of_birth": "1995-12-24"
        },
        "visa": {
            "visa_check_schema": "new_zealand",
            "new_zealand": {
            "visa_check_type": "verification",
			"gender": "M",
            "visa_start_date": "2023-11-01"
        }
        }
    },
    "meta": {
        "links": {
            "self": "https://platform.vsure.com.au/v2/visa-checks/vc_sa4mp1e"
        }
    }
}

Create an Employer (Work Rights) Visa Check - NZ

Make a POST request to the /visa-checks endpoint as shown:

POST /v2/visa-checks HTTP/1.1

Host: platform.vsure.com.au
Authorization: Bearer ACCESS.TOKEN.HERE
Version: 2024-03-05 
Content-Type: application/json 

{
    "jurisdiction": "NZL",
    "environment": "sandbox",
    "mode": "fastcheck",
    "customer_authority_id": "{{recently_created_ca_id}}",
    "visa_check_schema": "new_zealand",
    "new_zealand": {
         "visa_check_type": "employer",
				 "employment_start_date": "2024-11-01"
    },
    "document": {
        "type": "passport",
        "identifier": "V1212121",
        "country": "AUS",
        "family_name": "Doe",
    }
}

When completed correctly, the response will be the visa check resource.

201 Created

Content-Type: application/json 
Location: https://platform.vsure.com.au/v2/visa_check/vc_sa4mp13

{
    "data": {
        "id": "vc_sa4mp1e",
        "environment": "sandbox",
        "mode": "fastcheck",
        "jurisdiction": "NZ",
				
        "status": "pending",
        "requested_at": "2023-11-14T04:12:20.932Z",
        "authority": null,
        "customer_authority_id": "ca_sa4mp1e",
        "checked_at": null,
        "expired_at": null,
        "purged_at": null,
        "purged_by": null,
        "document": {
            "type": "passport",
            "identifier": "V1212121",
            "country": "AUS",
            "family_name": "Doe",
        },
        "visa": {
            "visa_check_schema": "new_zealand",
            "new_zealand": {
            "visa_check_type": "employer",
				 "employment_start_date": "2024-11-01"
        }
        }
    },
    "meta": {
        "links": {
            "self": "https://platform.vsure.com.au/v2/visa-checks/vc_sa4mp1e"
        }
    }
}

Fetch Visa Check Result

Visa checks are completed asynchronously after a check is created. Usually, fastcheck's only take a few seconds.

To retrieve the result of a Visa Check, query the API using the full URL provided in the initial response as follows:

GET /v2/visa-checks/:id HTTP/1.1

Host: platform.vsure.com.au
Authorization: Bearer ACCESS.TOKEN.HERE
Version: 2024-03-05 
Accept: application/json

Visa Check Schema

Once a visa check is completed, the result is available in the visa attribute of a check.

Each jurisdiction has a slight variation on the schema returned. This polymorphism is flagged using the visa_check_shema attribute

The schema will vary per jurisdiction, and the visa_check_shema field is the discriminator for this variation. Technically speaking, the visa is a polymorphic

Australia (Work Rights / Standard Visa Check)

...
{
    "data": {
        "id": "vc_rYGifUctfmqn",
        "environment": "sandbox",
        "mode": "fastcheck",
        "jurisdiction": "AUS",
        "status": "completed",
        "result": {
            "message": "Visa check is successful",
            "code": "SUCCESS"
        },
        "requested_at": "2024-08-13T04:29:11.091Z",
        "customer_authority_id": null,
        "expired_at": null,
        "checked_at": "2024-08-13T04:29:12.072Z",
        "purged_at": null,
        "purged_by": null,
        "visa_check_schema": "australia",
        "australia": {
            "visa_check_type": "work"
        },
        "document": {
            "type": "passport",
            "country": "ARG",
            "identifier": "22222222",
            "family_name": "Smith",
            "given_name": "John",
            "date_of_birth": "2000-02-02"
        },
        "extra": null,
        "visa": {
            "visa_schema": "australia",
            "australia": {
                "grant_date": "2014-09-19",
                "type_name": "Student Visa",
                "work_entitlement": "LIMITED",
                "study_entitlement": null,
                "expiry_date": "2030-03-15",
                "location": "Onshore",
                "type": "500",
                "type_details": "Student visa for students completing studies in Australia",
                "conditions": [
                    {
                        "description": "<p>8105 - Work limitation:</p><p>This condition means you cannot work in Australia before your course starts unless at the time of applying for this visa, you held another visa that permitted you to work in Australia.</p><p>You also cannot work more than 48 hours a fortnight when your course of study or training is in session. </p><p>A course of study is in session:</p><ul><li>for the duration of the school semesters (including when exams are being held)</li><li>you take another course that will count towards your main course during a term break.</li></ul><p>If you can work over 48 hours a fortnight</p><p>You can only work over 48 hours a fortnight if:</p><ul><li>you hold a student visa granted in relation to a masters degree by research or doctorate degree and your masters degree by research or doctorate degree has started<br></li><li>it is a registered part of your course that is mandatory, that was specified as a requirement of the course when the course particulars were entered into the Commonwealth Register of Institutions and Courses for Overseas Students<br></li></ul><p>A course is not in session:<br></p><ul><li>during scheduled course breaks <br></li><li>if your course was deferred or suspended in line with Standard 9 of the National Code of Practice for Providers of Education and Training to Overseas Students </li><li>if you hold a valid visa and have completed your course as listed on your confirmation of enrolment</li><li>if your enrolment has been cancelled due to the default of your education provider and until you get a new enrolment and start the course.</li></ul><p>A fortnight is a period of 14 days starting on a Monday.</p><p>An example of a student visas holder’s 48 hours a fortnight working limit is:<br></p><ul><li>week 1: 15 hours work</li><li>week 2: 30 hours work</li><li>week 3: 30 hours work</li><li>week 4: 10 hours work.</li></ul><p>The student may not have breached their work conditions in the fortnight comprising the 14 days of weeks 1 and 2 (45 hours worked) or in the fortnight comprising the 14 days of weeks 3 and 4 (40 hours). However, if in session the student will be in breach of their work conditions, in the fortnight comprising the 14 days of weeks 2 and 3 (60 hours worked).</p><p>For example: a student is studying a commercial cookery course on a subclass 500 visa and is offered work experience during school holidays. The Student works 75 hours a fortnight and is allowed to work unlimited hours while the course is not in session. The student visa holder did not break their work condition.</p><p>Work experience is included in a student’s work restriction of 48 hours a fortnight whether it is paid or unpaid.</p><p>The exception to this is if a work experience unit forms a mandatory component of a student’s course and is included in the CRICOS registration of that course. In this circumstance, the work experience will not be included in the student’s work restriction of 48 hours a fortnight. Any work experience/work placement that is not a mandatory course requirement, or that is in excess of the period required in the course registration, is included in a student’s work limitation of 48 hours a fortnight.</p><p>For example: a pharmacy student undertaking a mandatory 4 week block of on the job training has unlimited work rights for the purpose and duration of the work placement, as documented in the registered course structure.</p><p>Examples of definition of work:</p><ul><li>You do a shift at a restaurant as part of a roster, but not during your rostered unpaid meal break.</li><li>You are a taxi driver who has signed in and is ready to receive passengers, until you sign out for a break or your shift ends.</li></ul><p>As a student visa holder, you are considered to have worked if you have:</p><ul><li>attended a place of work for a period by a roster or timesheet (but not during unpaid breaks)</li><li>been ‘clocked on’ to an electronic system that records work activity</li><li>received remuneration for work, as indicated in a payslip you have been given (unless you give documentary evidence that you were not working during this time).</li></ul><p>You can work more than one job as long as the total hours are not more than 48 hours in a fortnight.</p><p>If you are an employer seeking to hire a student visa holder, you should request evidence that they commenced their course. This evidence can be a confirmation of enrolment or a letter from the education provider.<br> Employers who have hired a student visa holder should ensure that the student/employee is not working more hours than the employee’s visa allows.</p><p>Understanding your work rights</p><p>The Department is working with the Fair Work Ombudsman to help employees and employers understand and follow Australian Workplace laws.</p><p>Information on pay rates, shift calculations, leave arrangements and notice and redundancy entitlements is in the Pay and Conditions Tool (PACT).</p><p>The Fair Work Ombudsman website has more information on workplace rights and entitlements for visa holders and migrant workers.</p><p>For the full list of conditions relevant to your visa, see the Federal Register of Legislation.</p> <br> <br>",
                        "code": "8105"
                    }
                ],
                "class": "TU",
				"applicant": "primary",
                "entitlement_description": "The visa holder can work in Australia under the following conditions until the visa cease date."
            }
        },
        "attachments": [
            {
                "type": "vevo_visa_details",
                "file": {
                    "name": "VEVO Visa Details Check - John Smith.pdf",
                    "mime": "application/pdf",
                    "size": 1000
                },
                "download_url": "https://platform.vsure.com.au/v2/visa-checks/vc_rYGifUctfmqn/attachments/att_k7E9WmKBJKjx"
            }
        ]
    },
    "meta": {
        "links": {
            "self": "https://platform.vsure.com.au/v2/visa-checks/vc_rYGifUctfmqn"
        }
    }
}

Australia (Study Visa)

...
{
    "data": {
        "id": "vc_dWtXXaG9eXCF",
        "environment": "sandbox",
        "mode": "fastcheck",
        "jurisdiction": "AUS",
        "status": "completed",
        "requested_at": "2024-05-21T05:33:04.777Z",
        "customer_authority_id": null,
        "expired_at": null,
        "checked_at": "2024-05-21T05:33:05.999Z",
        "purged_at": null,
        "purged_by": null,
        "visa_check_schema": "australia",
        "australia": {
            "visa_check_type": "study"
        },
        "document": {
            "country": "IND",
            "identifier": "77777777",
            "type": "passport",
            "given_name": "John",
            "family_name": "Smith",
            "date_of_birth": "1999-01-01"
        },
        "extra": null,
        "visa": {
            "visa_schema": "australia",
            "australia": {
                "grant_date": null,
                "type_name": "Australian Permanent Resident or Citizen",
                "work_entitlement": null,
                "conditions_description": null,
                "study_entitlement": "NIL",
                "expiry_date": null,
                "location": "Onshore",
                "type": 998,
                "type_details": "VEVO has indicated that the person is a permanent resident or citizen",
                "conditions": "No limitations on study.",
                "class": null,
                "entitlement_description": "No limitations on study."
            }
        },
        "attachments": [
            {
                "type": "vevo_visa_details",
                "file": {
                    "name": "VEVO Visa Details Check - John Smith.pdf",
                    "mime": "application/pdf",
                    "size": 1000
                },
                "download_url": "https://platform.vsure.com.au/v2/visa-checks/vc_yFJHNcNmaRjP/attachments/att_hc3XGqw4VPPC"
            }
        ]
    },
    "meta": {
        "links": {
            "self": "https://platform.vsure.com.au/v2/visa-checks/vc_dWtXXaG9eXCF"
        }
    }
}
...

New Zealand (Visa Verification)

...
"visa": {
    "visa_schema": "new_zealand",
    "new_zealand": {
        "visa_start_date": "2024-04-14",
        "expiry_date": null,
        "inz_client_number": "77110099",
        "expiry_date_travel": "2026-05-14",
        "number_of_entries": "Multiple",
        "type": "Resident",
        "conditions": "Initial stay subject to grant of entry permission. Please apply for transfer of this visa when the passport expires. Visa is invalid if holder is outside NZ with expired travel conditions. Visa valid for further travel for 24 month(s) from first arrival.",
        "valid_as_at": "2023-12-14",
        "first_entry_before": "2024-03-14"
    }
}
...

New Zealand (Employer VisaView)

...
"visa": {
    "visa_schema": "new_zealand",
    "new_zealand": {
        "enquiry_number": "77110099",
        "valid_until": "indefinitely",
        "valid_as_at": "2024-08-14",
        "enquiry_result": "YES, is entitled to work for <Employer Name>"
    }
}
...

Australia (MARA Agent Check)

...
{
    "data": {
        "id": "vc_rYGifUctfmqn",
        "environment": "sandbox",
        "mode": "fastcheck",
        "jurisdiction": "AUS",
        "status": "completed",
        "result": {
            "message": "Visa check is successful",
            "code": "SUCCESS"
        },
        "requested_at": "2024-08-13T04:29:11.091Z",
        "customer_authority_id": null,
        "expired_at": null,
        "checked_at": "2024-08-13T04:29:12.072Z",
        "purged_at": null,
        "purged_by": null,
        "visa_check_schema": "australia",
        "australia": {
            "visa_check_type": "agent"
        },
        "document": {
            "type": "passport",
            "country": "CHN",
            "identifier": "E482482",
            "family_name": "Zhang",
            "given_name": "Zilin",
            "date_of_birth": "1984-03-22"
        },
        "extra": null,
        "visa": {
            "visa_schema": "australia",
            "australia": {
"grant_date": "2024-09-19",
"expiry_date": "2030-03-15",
"grant_number":"00395050000000",
"visa_stream":"Short-term",
"visa_status":"In Effect",
"location": "Onshore",
"entries_allowed":"Multiple entries to and from Australia during the validity of your visa",
"initial_stay_date":"2026-08-15",
"not_arrive_after":"2026-08-15",
"period_of_stay":"Until 15 August 2026",
"type_name": "Temporary Skill Shortage",
"type": "482",
"type_details": "Temporary resident",
"conditions": [
                    {
                        "description": "You must have and maintain adequate health insurance for the whole of your stay in Australia.",
                        "code": "8501"
                    }
										{
"description": "You must work only in the occupation nominated in your most recent Subclass 482 (Temporary Skill Shortage) visa application. You cannot work in a different occupation unless you apply for and are granted a new Temporary Skill Shortage visa.",
 "code": "8607"
                    }
                ],
"class": "GK",
"applicant": "primary",
"entitlement_description": "Must only work in nominated occupation."
            }