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
Australian MARA Agent visa enquiry
Foreign citizen Identity Verification
Replacement of manual Australian VEVO and New Zealand VisaView 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

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

"jurisdiction": "NZL"; must match
"visa_check_schema": "new_zealand"; and must include
"new_zealand": { }; the specific array for New Zealand, populated relevant to the check_type (see below)

===

new_zealand array - required for all New Zealand visa checks, though paraemters vary based on the visa check type

visa_check_type - determines the type of check performed. Options:

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

The two check types align to the two different services offered by NZ Immigration (links below):

Visa Verification Service

It includes information about that visa and its conditions, such as length of stay, and work and study entitlements.

Users might include health care providers, financial services organisations, sponsors, licensed immigration advisers, and travel agents.

Employer VisaView

This service allows registered New Zealand employers to check whether a person who is not a New Zealand citizen is allowed to work for them in New Zealand. It also allows registered employers to confirm New Zealand passport information provided by the jobseeker, and therefore confirm New Zealand citizenship and entitlement to work in any job.

verification checks are available for all RealMe account holders. New Zealand visa 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 - Only relevant to verification check type. Date format: yyyy-mm-dd

approval_letter_gender - Only relevant to verification check type. NZ Immigration currently only accepts binary gender, which is specified on the visa grant letter. Note Gender may also be specified in position 21 on the 2nd row of the Passport Machine Readable Zone, but this is not always binary nor always present. 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 (only option available for New Zealand checks)

identifier - passport 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 - see Resources page.

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 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",
				"given_name": "Jane",
				"date_of_birth": "1999-08-16"
    }
}

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

New Zealand (Verification) Response - visa array

...
"visa": {
    "visa_schema": "new_zealand",
    "new_zealand": {
        "visa_expiry": null,
        "gender": "M",
        "date_of_birth": "1978-02-27",
        "inz_client_number": "77110099",
        "expiry_date_travel": "2026-05-14",
        "number_of_entries": "Multiple",
        "valid_as_at": "2025-03-04",
        "family_first_name": "Bloggs, Joe",
        "passport_nationality": "Indonesia",
        "visa_start_date": "2024-04-14",
        "visa_type": "Resident",
        "passport_number": "V12345678",
        "enquiry_date": "2025-03-04",
        "visa_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.",
        "first_entry_before": "2024-03-14"
    }
}
...

INZ currently issues the following visa types (meaning the results for the visa_type field can be):

visitor
work
student
diplomatic, consular and official
military
limited
interim
transit
permanent resident
resident

This attached pdf is an exert from the NZ Immigration Guide and covers the data returned via Verification check type and explains each field.

New Zealand (Verification) Response - attachments array

The vSure v2 visa checks API for the jurisdiction New Zealand and check type verification, will return a PDF, accessible within the active session via the provided download_url:

...

"attachments": [
                {
                    "type": "vvs_enquiry_record",
                    "file": {
                        "name": "VVS Enquiry Record - BLOGGS, JOE.pdf",
                        "mime": "application/pdf",
                        "size": 41948
                    },
                    "download_url": "https://platform.vsure.com.au/v2/visa-checks/vc_wRScvbS7IA8P/attachments/att_77PHBNNfg32D"
                }
            ]
						
...

This attached pdf is sample of the PDF returned.

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>"
    }
}
...

vSure Visa Checks API v2

Visa Checks - New Zealand

Create a Visa Check

Parameters

Create a Visa Verification Check - NZ

Create an Employer (Work Rights) Visa Check - NZ

Fetch Visa Check Result

Visa Check Schema

New Zealand (Verification) Response - visa array

New Zealand (Verification) Response - attachments array

New Zealand (Employer VisaView)