What is Onboarding
Most upstreams systems, like Active Directory or Recruitment, will be responsible for creating new hires in HR. This usually involves creating a person, creating a job, issuing a user account, and often triggering a workflow.
Upstream integration consumers may also want to consider automating the initialising of onboarding templates to new employees. Onboarding templates are Administrator built and allow a new employee to input information required for payroll like bank, tax, superannuation and even specific custom fields relevant to your business. This allows a business to collect all of the required information from a new starter in a robust, automated process.
Managing Onboarding via the API
Two models are involved when designing how to automate the issuing of an employee’s onboarding. The first is finding the relevant onboarding template id, and the second is including the onboarding template when issuing a user account.
First, determine how you want to source the onboarding template information in your system. Typically we would suggest including a drop down list of relevant onboarding templates, or POLLing a list from HR on page-load to always surface existing onboarding templates.
You can retrieve a list of Onboarding Templates from the /v1/onboarding-templates endpoint. This will return a paginated list of onboarding templates with a name, id, and whether a template is enabled. You may want to disregard any disabled templates to avoid issuing old or archived onboarding templates.
You only need to store the onboarding template id when triggering an onboarding template as the onboarding template id needs to be included in the users payload in order to issue an onboarding template.
{
"isEnabled": true,
"username": "BruceWayne”,
"activeFrom": "2021-01-01T00:00:00Z”,
"onboardingTemplateId": "8a5f3ea6-ea6b-4425-8a87-3c256bb7b6f9”,
"person": {
"id": "8a5f3ea6-ea6b-4425-8a87-3c256bb7b6f9”,
"name": "Bruce Wayne”,
"primaryEmailAddress": "bruce.wayne@example.com”,
"employeeNumber": "00001”,
"autoIncrementIntellihrId": “1000”
},
"permissionGroups": [
"fd652f39-db15-4a12-8c71-a48358ee9709”
]
}
Retrieving and Dispatching Payroll Sessions from the API - Australia Only
Note: please see “workflows via the API for information on how to subscribe and use intelliHR’s webhooks”
Payroll Onboarding Completed Event
When employees complete an onboarding session, you may want to consume this information to your downstream system. At the time of first hire this is often to populate a payroll record ahead of processing.
Note: currently the payroll onboarding webhook event is only triggered when the employee completes the bank, tax or superannuation validation via SuperAPI Pty Ltd.
After subscribing to the payroll onboarding completed event there are two types of trigger that will dispatch the event:
-
The first onboarding completed for the employee’s job
-
Subsequent updates to bank, tax or superannuation for the employee’s job
How to use the event
Employee completes an onboarding session the webhook will be POSTed to the specified destination url. Your service should then perform a GET request against the self-link to retrieve the information from the payroll sessions.
Note: if an employee is updating their bank, tax or superannuation information the endpoint may exclude key-pair values of fields that were not updated.
The onboarding information belongs to a job, which is owned by a person. This relationship allows you to work forward from a payroll session to the person model or backwards from the person model to the payroll sessions.
Payroll sessions <> job <> person.
The payroll-sessions/id endpoint includes certain logic that you may need to develop around.
Superannuation
When completing their onboarding an employee may select a registered super fund, or select a self managed super fund. The relevant object will return fully populated, while the other object will be returned as an empty object. You may need to check which object contains information when determining which information to consume.
Status Fields
The bottom of the data payload includes a series of booleans and statuses that you will need to review to determine how to consume the event.
-
Bank Account Status
-
Super Status
-
Tax Status
-
Has Bank Account Changed
-
Has Super Changed
-
Has Tax Changed
-
Is First Onboarding Completed
Additional Details
Employees can also be prompted to upload documentation and provide qualification information during an onboarding session. This information is not returned on the payroll sessions endpoint, but can be retrieve by taking the relevant id’s and retrieving this information. Qualifications belong to a person and can be retrieved via the /v1/qualifications endpoint by taking the person id returned under data.job.id, which will return the job object that provides the person id under data.person.id, and passing this as the query param under the List all Qualification Instances endpoint.
Listing Payroll Sessions
You may be using a system that does not allow webhook consumption, or you may have a need to check an employee’s existing payroll sessions. The “List Payroll Session Ids for Job” allows you to take the id of a given job and retrieve a list of completed onboarding sessions.
{
"data": [
{
"id": "8a5f3ea6-ea6b-4425-8a87-3c256bb7b6f9”,
"createdAt": "2015-03-01T22:30:00+00:00”,
"completedAt": "2015-03-01T22:30:00+00:00”,
"isFirstOnboardingCompleted": true
}
],
"meta": {
"requestId": "8a5f3ea6-ea6b-4425-8a87-3c256bb7b6f9”
}
}
Using a combination of completed at date and the “Is First Onboarding Completed” boolean you can determine which onboarding sessions are relevant for your use. You can then take the relevant id’s and include these as the path parameter in a subsequent GET request to /v1/payroll-sessions/{id}.
Common Questions
Does the webhook trigger for onboarding sessions outside of Australian bank, tax and superannuation?
No, the onboarding payroll completed webhook only triggers when employees complete their bank, tax and superannuation detailed here: Bank, Tax and Superannuation Collection - Australia Only - To collect information for employees completed onboarding outside of Australia or using an onboarding template not connected to the Australian bank, tax and superannuation feature you can subscribe to the person.updated webhook to collect fields completed by the new starter.
How to consume onboarding sessions for non-Australian people?
For employees outside of Australia or not utilising the bank, tax and superannuation flow, employees can still be issued onboarding templates to collect key person fields and custom fields, along with providing relevant documentation and qualification information. Typically the best way to listen for this information is to subscribe to the person.updated webhook. While the event does not explicitly return an indication that an onboarding session is completed, you can reference the updated attributes array or perform checks against relevant fields to determine when a record is ready for consumption downstream.
How will multiple bank accounts be handled?
Employees can enter up to 4 bank accounts when completing their Australian banking information. The employee can specify a split for each bank account, either by amount or percentage. These bank accounts are returned as an array under the employee details object:
"bank_accounts": [
{
"account_name": "string”,
"account_number": "string”,
"bsb": "string”,
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08”,
"split_kind": "percentage”,
"split_value": 70
},
{
"account_name": "string”,
"account_number": "string”,
"bsb": "string”,
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08”,
"split_kind": "percentage”,
"split_value": 30
}
]
How can I test the webhook?
Because the onboarding via Super API Pty Ltd connects to the ATO and a library of superannuation providers, there is no way to complete onboarding on behalf of an employee. Instead, if you wish to test the webhook, the best way to do this is to initiate onboarding for yourself. Once you have subscribed to the webhook, login to intelliHR and complete the onboarding flow to trigger the webhook.