Self-Onboarding Endpoint
You can manage "self on-boarding via email/SMS" in vSure for a new employee/contractor/candidate via the RESTful API.
The vSure API address is:
https://api.vsure.com.au/v1/onboarding
The 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 the API connections.
The Account Key
The vSure client must also include the account key provided on the My Account Screen (see below) as part of the request data. vSure will use this key to add the employee/contractor/candidate to the account.
Functions
Description https request:
List Onboards POST or PUT /v1/onboarding/list
Get Onboard Details POST or PUT /v1/onboarding/get
Create New Onboard POST or PUT /v1/onboarding/
Update Onboard Request POST or PUT /v1/onboarding/
NOTE: API key should be a parameter in the URL, rather than a part of the payload:
List Onboards – JSON Structure
https://api.vsure.com.au/v1/onboarding/list Our list onboards API accepts JSON format:
{
"accountkeyid":"XXXXXXXXXX",
"onboard_status":"XXXXXXX",
"page_number":"XXXXXXXXX"
}
The following is the details of the request:
accountkeyid - string
The key id of the account, obtainable from the account table.
onboard_status - string
Options: Review | Awaiting | Complete | All | Active.
Where Active = Awaiting OR Review
Default if not included: Active
page_number - whole number
displaying 1000 per page. Default: 1
Data Returned
The following is the details of the data:
onboard_id – string
The unique identifier of the self-onboard request
employee_id – string
The unique identifier from an external system such as ATS, HRIS, Payroll or Rostering
onboard_status - string
Options: Review | Awaiting | Complete | All | Active.
given_names - string
The given names of the visa holder.
family_name - string
The family name of the visa holder.
email – string
The email address of the visa holder.
mobile_number – string
The Australian mobile number of the visa holder. Format 0000000000.
datetime - Date and Time
Date and time of last action.
GET Employee Self-Onboard Details – JSON Structure
https://api.vsure.com.au/v1/onboarding
Our GET Onboard Details API accepts JSON format: json
{
"accountkeyid":"XXXXXXXXXX",
"onboard_id":"XXXXXXXX",
"employee_id":"XXXXXXXX"
}
The following is the details of the request:
accountkeyid - Required - string
The key id of the account, obtainable from the account table.
The request must have Either or Both of the following:
employee_id – Optional - string
The unique identifier from an external system such as ATS, HRIS, Payroll or Rostering
onboard_id – Optional - string
The unique identifier of the self-onboard request
Data Returned
The following is the details of the data:
onboard_id – string
The unique identifier of the self-onboard request
employee_id – string
The unique identifier from an external system such as ATS, HRIS, Payroll or Rostering
**given_names **- string
The given names of the visa holder.
family_name - string
The family name of the visa holder.
onboard_status - string
Options: Review | Awaiting | All.
date_of_birth - string (Format: "YYYY-MM-DD")
The date of birth of the visa holder.
email – string
The email address of the visa holder.
mobile_number – string
The Australian mobile number of the visa holder. Format 0000000000.
sendtype – string
Options: Email | SMS | Both
location – string
An identifier for which venue/location etc the employee might work
group – string
Another identifier for grouping employees. Could be used for Role or Department etc
datetime - Date and Time
Date and time of last action.
Create new Self-Onboarding (Right To Work) Request – JSON Structure
API key should be a parameter in the URL, rather than a part of the payload.
Our API POST for creating new self-onboarding (Right To Work Check) requests accepts JSON format:
{
"accountkeyid":"XXXXXXXXXX",
"employee_id":"12345",
"given_names":"John",
"family_name":"Smith",
"date_of_birth":"YYYY-MM-DD",
"email":"XXXXXXXXXX"
}
The following is the details of the data:
accountkeyid - Required - string
The key id of the account, obtainable from the account table.
employee_id – Recommended - string
The unique identifier from an external system such as ATS, HRIS, Payroll or Rostering.
If not unique, will be merged within vSure with exiting self-onboard request.
If not included in POST, will be null, which does not trigger the onboard request to be merged.
given_names - Recommended - string
The given names of the visa holder.
family_name - Recommended - string
The family name of the visa holder.
date_of_birth - Optional - date field (Format: "YYYY-MM-DD")
The date of birth of the visa holder.
The request MUST have either or both of the following:
email – string
The email address of the visa holder.
mobile_number – string
The Australian mobile number of the visa holder. Format 0000000000.
sendtype – Optional - string
This defines how the Right To Work self-Onboard is sent to the candidate/employee.
Options:
Email SMS Both The system defaults to:
Both if both Email and Mobile are included in the email text; Email if only email address is included in the email text; SMS if only Mobile is present.
location – Optional - string
An identifier for which venue/location etc the employee might work
group – Optional - string
Another identifier for grouping employees. Could be used for Role or Department etc
Update Self-Onboarding Request – JSON Structure
Our UPDATE API for updating exiting self-onboarding requests accepts JSON format:
{
"key":"XXXXXXXXXX",
"accountkeyid":"XXXXXXXXXX",
"onboard_id":"XXXXXXXX",
"employee_id":"XXXXXX",
"given_names":"John",
"family_name":"Smith",
"date_of_birth":"YYYY-MM-DD",
"email":"XXXXXXXXXX",
}
The following is the details of the data:
key - Required - string
The vSure API key we provided to you
accountkeyid - Required - string
The key id of the account, obtainable from the account table.
The request must have Either or Both of the following:
employee_id – Optional - string
The unique identifier from an external system such as ATS, HRIS, Payroll or Rostering
Cannot be null if included in the JSON.
**onboard_id **– Optional - string
The unique identifier of the self-onboard request
given_names - Optional - string
The given names of the visa holder.
family_name - Optional - string
The family name of the visa holder.
date_of_birth - Optional - string (Format: "YYYY-MM-DD")
The date of birth of the visa holder.
email – Optional - string
The email address of the visa holder.
**mobile_number **– Optional - string
The Australian mobile number of the visa holder. Format 0000000000.
location – Optional - string
An identifier for which venue/location etc the employee might work
group – Optional - string
Another identifier for grouping employees. Could be used for Role or Department etc