vSure WebApp API

Integrate with the vSure end-to-end work rights compliance platform using our simple, v1 RESTful API

Employee

You can GET existing employee/contractor records and POST to (update) specific employee/contractor fields within the vSure app.

https://api.vsure.com.au/employee/v1

API Key

An API key for specific IP Address(es) must be requested from vSure support. Please use the Zendesk "Submit a Request" above or click here and please include:

  • Your company name;
  • Your product name (if different);
  • The vSure client company name;
  • Developer Contact name;
  • Developer Contact Email;
  • Your Development IP Address(es) for white-listing;
  • Your Live environment IP Address(es) for white-listing;

Once an API key has been created, vSure will use this API key to authenticate all API connections to the vSure web app.

NOTE the API key is a parameter in the URL.

Account Key ID

The vSure client must also include the account key provided on the My Account screen as part of the request data. vSure will use this key to identify the account/dataset.

accountkeyid is a parameter in the pay load of the request.

Functions

Description https request:

  • List Employees POST OR PUT /employee/v1/list
  • Get Employee POST OR PUT /employee/v1/get
  • Update Employee POST OR PUT /employee/v1/update

The API key is a parameter of the POST/PUT.

key=XXXXXXXXXXX

https://api.vsure.com.au/employee/v1/list?key=XXXXXXXXXXX

List Employee

https://api.vsure.com.au/employee/v1/list

Param:

key= [Your IP address white-listed API key]

Our list employee API accepts JSON format:

{
 "accountkeyid":"XXXXXXXXXX",
 "employment_status":"XXXXXXX",
 "datetime":"XXXXXXXX",
 "page_number":"XXXXXXXXX"
}

The following is the details of the request:

accountkeyid - string

The key id of the account, obtainable from the account table.

employment_status - string

Options: All | Current | Prospective | Previous. Default: All

datetime - whole number (epoch)

Acts as a filter for any employee whose work rights have changed since that specified date.

page_number - whole number

displaying 1000 per page. Default: 1

Data Returned key_id

employee_id

employment_status

given_names

family_name

Get Employee details

https://api.vsure.com.au/employee/v1/get

Param:

key= [Your IP address white-listed API key]

Our employee get API accepts JSON format:

{
 "accountkeyid":"XXXXXXXXXX",
 "key_id":"XXXXXXXXXX"
}

accountkeyid - string

The key id of the account, obtainable from the account table.

key_id - string

The key id of the employee, obtainable from the employee table and list.

employee_id - string

The Employee ID of the employee, obtainable from the employee table and list.

NOTE: either key_id or employee_id must be present.

Response

{ 
"key_id":"XXXXXXXXXXXX",
"given_names":"John",
"family_name":"Smith",
"date_of_birth":"2000-07-01",
"employee_id":"XXXXXXXXXXXX",
"group":"NSW",
"location":"Bondi",
"email":"name@email.com",
"mobile_number":"0400000000",
"employment_status":"current",
"start_date": "1716225585",
"cease_date": "1716225585",
"course_start_date": "1716225585",
"course_type":"bachelor"
}

Response Fields

key_id

given_names

family_name

date_of_birth

employee_id

group

location

email

mobile_number

employment_status current | prospective | previous

start_date - epoch format

cease_date - epoch format

course_start_date - epoch format

course_type - blank | master_research | master_coursework | bachelor | diploma | elicos | other

Update Employee

https://api.vsure.com.au/employee/v1/update

Param:

key= [Your IP address white-listed API key]

NOTE: by design: given_names, family_name, date_of_birth, email, mobile_number cannot be set to blank via the API

Our Update employee API accepts JSON format:

{
 "accountkeyid":"XXXXXXXXXX",
 "key_id":"XXXXXXXXXX",
 "data": {
         }
}

The following is the details of the data:

accountkeyid - string

The key id of the account, obtainable from the account table.

key_id - string

The key id of the employee, obtainable from the employee table and list.

OR

employee_id - string

The external employee id of the employee, obtainable from the employee table and list.

NOTE: either key_id or employee_id must be present.

Parameters

key_id

given_names

family_name

date_of_birth

employee_id

group

location

email

mobile_number

employment_status current | prospective | previous

start_date - epoch format

cease_date - epoch format

course_start_date - epoch format

course_type - blank | master_research | master_coursework | bachelor | diploma | elicos | other

Example Update Payload

The most common use case for updating an employee is moving them to "Previous" status upon Termination in payroll.

{
"accountkeyid":"XXXXXXXXXX",
"key_id":"XXXXXXXXXX",
"data": {
	 "employment_status": "previous",
	 "cease_date":"1716225585"
 }
}