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 Australia, visa checks can optionally record your/your client's Immi (VEVO) Account Details against each check.

To do this, you need to create a 'customer authority' and storing relevant credentials to perform visa checks.

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.

Australian checks can optionally use your's or your client's Immi account details:

So that Home Affairs knows who is initiating the check;
MARA agent Immi Accounts can see ALL conditions, not just Work or Study conditions provided by a standard check;

If you don't provide credentials for Australia, Home Affairs will know it is a vSure customer performing the check and may contact us regarding who in fact initiated the check, and we are obliged to provide your nominated contact details if this does arise (rare). Examples in the past have included locating missing persons.

vSure reserves the right to enforce the need for Customer Authority for any Australian visa check API customers, at its descretion or at the direction of Home Affairs.

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

Customer Authority resource - Australia (optional)

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

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

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