Developer Portal

vSure acts on your / your client's behalf when performing a visa check.

In New Zealand, visa checks MUST BE performed with reference to your/your client's RealMe account details.

In NZ specifically you need to create a 'customer authority' and store relevant credentials to perform visa checks.

In Australia, Customer Authority is not required with minimal exceptions. We only recommend a Customer Authority for Migration Agents and very large volume customers.

Reasons for Customer Authority

New Zealand requires Real Me account details against each check as:

NZ Immigration wants to know who is initiating the check;
Check results can vary on sponsored visas, based on who is performing the check (employer vs not the employer - the employer will see more visa details for their sponsored staff);

You may want to use credentials for your organisation OR leverage different credentials for different clients. For example, you are a software developer building software for others - you should consider allowing clients to store their RealMe details for you to use in your checks on their behalf.

Customer Authority for Australian is only required for:

MARA agents checks (who need to prove authority to see ALL visa conditions and details);
Very large volume clients (whom vSure will practively contact to implement)

A note on New Zealand visa checks

There are 2 different NZ Visa checks:

Visa Verification: verifies a visa (and thus foreign passport) is valid based on data from both the visa holder's passport and visa grant letter;
Employer Visa View: specifically verifies NZ work rights with specific reference to work rights details, based on data from the visa holder's passport;

Each RealMe account will have access to either Visa Verification OR Employer Visa View. You cannot perform an Employer Visa View if the RealMe account only has access to Visa Verification.

Therefore there are two different New Zealand visa check types:

Verification - use case: KYC or other form of identity checks; and
Employer - use case: work rights checks

Here's the link to register for NZ RealMe and the Visa Verification Service: https://www.immigration.govt.nz/about-us/our-online-systems/visa-verification-service/using

Scroll down to the bottom and click "Create RealMe Account".

To register for Employer VisaView: https://www.immigration.govt.nz/about-us/our-online-systems/visaview

Scroll down to "Register and log in to VisaView with RealMe".

Customer Authority resource - NZ (Required)

{
    "id": "ca_sa4mp1e",
    "label": "Your Custom Label",
    "authority": "realme",
    "realme": {
        "username": "exampleusername",
        "password": "examplepassword"
    },
    "created_at": "2023-11-29T03:17:30.276Z"
}

Customer Authority resource - Australia (not recommended for most use cases)

We would only recommend Customer Authority in Australia for:

MARA Agents: Migration Agents uniquely can be provided access to ALL visa conditions. To access this, you must prove your permission to do so by providing vSure with a customer authority that allows for MARA agent checks.
Large Volume Users: vSure will work directly with clients where volumes will require a Customer Authority.

IF you are not needing MARA agent checks AND/OR your volumes won't exceed 10,000+ visa checks per month, then you can assume you do not need a customer authority to perform Australian visa checks.

{
    "id": "ca_sa4mp1e",
    "label": "Your Custom Label",
    "authority": "immi",
    "immi": {
        "username": "example@email.com",
        "password": "supersecretpassword"
    },
    "created_at": "2023-11-29T03:17:30.276Z"
}

Field details

id

READ ONLY - A JSON string generated by vSure that uniquely identifies this resource.

label

OPTIONAL - a JSON string provided by the client application. This is useful to differentiate customer authority resources as we do not return the credential values themselves.

authority

REQUIRED - the type of customer authority being created.

Australia - "immi" to store Home Affairs ImmiAccount credential.

NZ - "realme" to store a RealMe credential.

realme

REQUIRED - A JSON object containing the username and password for the RealMe account. This is a required field and is only included when creating a customer authority. The API will not return this key (or the credentials within it) when retrieving customer authority resources.

username

REQUIRED - A JSON string of the email/username for your Immi/RealMe account. We do not return this field when retrieving customer authority resources. The field is not validated until a visa check is attempted.

password

REQUIRED - A JSON string of the password for your Immi/RealMe account. We do not return this field when retrieving customer authority resources. The field is not validated until a visa check is attempted.

created_at

READ ONLY - An ISO formatted timestamp of when the customer authority was first created.

Create a Customer Authority

Make a POST request to the /customer-authorities endpoint as shown:

POST /v2/customer-authorities HTTP/1.1

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

{
    "label": "Sample credential",
    "authority": "realme",
    "realme": {
        "username" : "****",
        "password" : "****"
    }
}

When completed correctly, the response will be the customer authority resource.

201 Created

Content-Type: application/json 
Location: https://platform.vsure.com.au/v2/customer-authorities/ca_sa4mp1e

{
    "id": "ca_sa4mp1e"
    "label": "Sample credential",
    "authority": "realme",
    "created_at": "2023-11-29T03:17:30.276Z"
}

Note that the credentials stored are never returned through the API.

Take note of the id returned from this API operation so that you can then reference this customer authority when submitting a visa check to the API.

vSure Visa Checks API v2

Customer Authority