The most common payroll integrations with intelliHR take new hires and updates from intelliHR and send these downstream to the payroll system. This allows system administrators in Human Resources to process information about their employees, and removes the requirement for the data to be re-entered into payroll.
This article covers:
New Job Data Flow
Start by Registering Webhooks
We suggest commencing your flow of data with the Job Created event. This event fires a webhook when a new job is processed in intelliHR. Typically, this indicates that a new starter is joining the business.
While you can manually register a webhook in an intelliHR tenant in Settings > Webhooks, we recommend automating the webhook registration via API to remove manual work for future deployments. For more information, see our webhooks guide.
Use Self-links to Return Job Data
intelliHR uses skinny webhooks. A skinny webhook is a type of webhook that only includes minimal meta data in its payload, rather than sending the full data associated with the event that triggered the webhook. Example JSON code below.
{
"id": "f9e721c2-a936-47eb-970e-801e4fe8a9bd",
"event": "job.created",
"timestamp": "2022-12-20T03:31:32Z",
"links": {
"self": "https://api.intellihr.io/v1/people/f9e721c2-a936-47eb-970e-801e4fe8a9bd",
"selfEncoded": "https://api.intellihr.io/v1/people/f9e721c2-a936-47eb-970e-801e4fe8a9bd"
}
}
The idea behind skinny webhooks is to reduce the amount of data that is transmitted over the network and improve the efficiency of the webhook system. Instead of sending the full data for an event, intelliHR only sends a notification containing the jobID
of the person that was created.
In order to return the information about the person that was created. You will need to perform a subsequent HTTP GET request to the relevant endpoint. In the case of job.created
event, we would use the jobs endpoint to perform our request.
Use the self
link returned on the webhook in the url of the following GET request.
"url": https://api.intellihr.io/v1/jobs/{id}
"method": 'GET'
"headers": {
"Content-Type": 'application/json',
"Accept": 'application/json',
"Authorization": `Bearer ${apikey}`,
"Tenant": tenantname
}
Optional: Return Person Data
The/jobs
endpoint will return basic information for the attached person record (as you can see below).
"person": {
"id": "8a5f3ea6-ea6b-4425-8a87-3c256bb7b6f9",
"displayName": "Batman (Bruce) Wayne",
"employeeNumber": "00001",
"autoIncrementIntellihrId": 1000,
"link": "https://api.intellihr.io/v1/people/8a5f3ea6-ea6b-4425-8a87-3c256bb7b6f9"
}
However, Payroll systems usually require more detailed information than is return on the job endpoint alone. If this is the case, you can perform a HTTP GET request using the link
provided in the person
object to return the complete person record attached to the job.
Use the link
returned on the /jobs
endpoint in the URL of the following GET request.
"url": https://api.intellihr.io/v1/jobs/{id}
"method": 'GET'
"headers": {
"Content-Type": 'application/json',
"Accept": 'application/json',
"Authorization": `Bearer ${apikey}`,
"Tenant": tenantname
}
Construct a HTTP POST Request
The first step is to assess which fields in your Payroll system are required to create a new employee. These can usually be found in that system’s API documentation and will vary depending on the platform.
Here are some common fields that are required in payroll systems to create an employee.
FirstName
: The employee's first name.LastName
: The employee's last name.DateOfBirth
: The employee's date of birth in the formatYYYY-MM-DD
.Phone
: The employee's phone number.Email
: The employee's email address.Address
: The employee's address.Position
: The employee's job title.WageType
: The type of wage the employee is paid (e.g. "Hourly", "Salary").WageAmount
: The amount the employee is paid.PayrollSystem
: The payroll system the employee is on (e.g. "Weekly", "Fortnightly", "Monthly").
"url": ${insert_create_employee_url}
"method": 'POST'
"headers": {
"Content-Type": 'application/json',
"Accept": 'application/json',
"Authorization": `Bearer ${apikey}`,
}
body: {
"FirstName": "John",
"LastName": "Doe",
"DateOfBirth": "1980-01-01",
"Phone": "123-456-7890",
"Email": "john.doe@example.com",
"Address": "123 Main St, Brisbane 4000",
"Position": "Software Engineer",
"WageType": "Hourly",
"WageAmount": 50,
"PayrollSystem": "Weekly"
}
Update Job and People Data Flow
Start by Registering Webhooks
We suggest commencing your flow of data with the job.timeline_updated
event. This event fires a webhook when a job update takes effect on the employee timeline. This webhook is particularly useful when the target system does not support date-effective updates.
Alternatively, if the target system does support date-effective updates, you might wish to use the job.update_scheduled
event. This webhook fires when a job update has been scheduled in intelliHR and includes effective date information.
While you can manually register a webhook in an intelliHR tenant in Settings > Webhooks, but we recommend automating the webhook registration via API to remove manual work for future deployments. For more information, see our webhooks guide.
Using job.timeline_updated
intelliHR uses skinny webhooks. A skinny webhook is a type of webhook that only includes minimal information in its payload, rather than sending the full data associated with the event that triggered the webhook.
The job.timeline_updated
webhook payload (as you can see below) includes a self link to the relevant job record.
{
"id": "eb9b067b-ded0-4cf2-aaf4-e3bd31e7e381",
"event": "job.timeline_updated",
"timestamp": "2023-01-04T05:10:33Z",
"links": {
"self": "https://api.intellihr.io/v1/jobs/eb9b067b-ded0-4cf2-aaf4-e3bd31e7e381",
"selfEncoded": "https://api.intellihr.io/v1/jobs/eb9b067b-ded0-4cf2-aaf4-e3bd31e7e381"
}
}
As with the create flow, you will need to perform subsequent GET requests to the and /jobs endpoints in order to retrieve the job information. Since this webhook does not fire until the update has taken effect, perform a simple HTTP GET request to the self link with no asAt query parameter.
"url": https://api.intellihr.io/v1/jobs/{id}
"method": 'GET'
"headers": {
"Content-Type": 'application/json',
"Accept": 'application/json',
"Authorization": `Bearer ${apikey}`,
"Tenant": tenantname
}
Using job.update_scheduled
intelliHR uses skinny webhooks. A skinny webhook is a type of webhook that only includes minimal information in its payload, rather than sending the full data associated with the event that triggered the webhook.
The job.update_scheduled
webhook payload includes a self-link to the relevant job record and provides additional information about the update, including the start and end dates for the update, and details about which attributes of the job record were changed. This webhook can be used to discriminate the types of updates that are sent downstream.
{
"id": "eb9b067b-ded0-4cf2-aaf4-e3bd31e7e381",
"event": "job.update_scheduled",
"timestamp": "2023-01-04T05:12:14Z",
"update_start_date": "2023-01-04T14:00:00+00:00",
"update_end_date": null,
"updated_attributes": [
"business_entity"
],
"links": {
"self": "https://api.intellihr.io/v1/jobs/eb9b067b-ded0-4cf2-aaf4-e3bd31e7e381?asAt=2023-01-04T14:00:00+00:00",
"selfEncoded": "https://api.intellihr.io/v1/jobs/eb9b067b-ded0-4cf2-aaf4-e3bd31e7e381?asAt=2023-01-04T14%3A00%3A00%2B00%3A00"
}
}
As with the create flow, you will need to perform subsequent GET requests to the and /jobs endpoints in order to retrieve the job information. Since this webhook does not fire until the update has taken effect, perform a simple HTTP GET request to the self link with no asAt query parameter.
"url": https://api.intellihr.io/v1/jobs/{id}
"method": 'GET'
"headers": {
"Content-Type": 'application/json',
"Accept": 'application/json',
"Authorization": `Bearer ${apikey}`,
"Tenant": tenantname
}
Construct a HTTP PATCH Request
Depending on the target system, you may have to include various required fields when making updates. Despite this the process is generally to make a PATCH request to the employee endpoint including whichever field need to be updated.
"url": ${insert_create_employee_url}
"method": 'PAT'
"headers": {
"Content-Type": 'application/json',
"Accept": 'application/json',
"Authorization": `Bearer ${apikey}`,
}
body: {
"Id": "123456789",
"Position": "Software Engineer",
"WageType": "Hourly",
"WageAmount": 50,
"PayrollSystem": "Weekly"
}
Terminations & Deletions
Start by Registering Webhooks
We suggest commencing your flow of data with the job.end_date_finalised
event. This event fires a webhook when after a job end date has been finalised in intelliHR.
While you can manually register a webhook in an intelliHR tenant in Settings > Webhooks, but we recommend automating the webhook registration via API to remove manual work for future deployments. For more information, see our webhooks guide.
{
"id": "b8afce05-0277-4560-bf52-b7fb78d720a8",
"event": "job.end_date_finalised",
"timestamp": "2023-01-04T05:59:11Z",
"start_date": "2018-03-25T14:00:00+00:00",
"inclusive_end_date": "2023-01-03T14:00:00+00:00",
"links": {
"self": "https://api.intellihr.io/v1/jobs/b8afce05-0277-4560-bf52-b7fb78d720a8",
"selfEncoded": "https://api.intellihr.io/v1/jobs/b8afce05-0277-4560-bf52-b7fb78d720a8"
}
}
Use Self-Links to Return Job Data
intelliHR uses skinny webhooks. A skinny webhook is a type of webhook that only includes minimal information in its payload, rather than sending the full data associated with the event that triggered the webhook.
{
"id": "f9e721c2-a936-47eb-970e-801e4fe8a9bd",
"event": "job.created",
"timestamp": "2022-12-20T03:31:32Z",
"links": {
"self": "https://api.intellihr.io/v1/people/f9e721c2-a936-47eb-970e-801e4fe8a9bd",
"selfEncoded": "https://api.intellihr.io/v1/people/f9e721c2-a936-47eb-970e-801e4fe8a9bd"
}
}
The idea behind skinny webhooks is to reduce the amount of data that is transmitted over the network and improve the efficiency of the webhook system. Instead of sending the full data for an event, intelliHR only sends a notification containing a the jobID
of the person that was created.
In order to return the information about the person that was created. You will need to perform a subsequent HTTP GET request to the relevant endpoint. In the case of job.created
event, we would use the jobs endpoint to perform our request.
Use the self
link returned on the webhook in the url of the following GET request.
"url": https://api.intellihr.io/v1/jobs/{id}
"method": 'GET'
"headers": {
"Content-Type": 'application/json',
"Accept": 'application/json',
"Authorization": `Bearer ${apikey}`,
"Tenant": tenantname
}
Optional: Return Person Data
The/jobs
endpoint will return basic information for the attached person record (as you can see below).
"person": {
"id": "8a5f3ea6-ea6b-4425-8a87-3c256bb7b6f9",
"displayName": "Batman (Bruce) Wayne",
"employeeNumber": "00001",
"autoIncrementIntellihrId": 1000,
"link": "https://api.intellihr.io/v1/people/8a5f3ea6-ea6b-4425-8a87-3c256bb7b6f9"
}
However, Payroll systems usually require more detailed information than is return on the job endpoint alone. If this is the case, you can perform a HTTP GET request using the link
provided in the person
object to return the complete person record attached to the job.
Use the link
returned on the /jobs
endpoint in the URL of the following GET request.
"url": https://api.intellihr.io/v1/jobs/{id}
"method": 'GET'
"headers": {
"Content-Type": 'application/json',
"Accept": 'application/json',
"Authorization": `Bearer ${apikey}`,
"Tenant": tenantname
}
Comments
0 comments
Please sign in to leave a comment.