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:
What is POLLing?
POLLing refers to the act of repeatedly sending requests to the API to check for new data or changes.
For example, your payroll system needs to be notified when a job is created or updated in intelliHR, you might set up the application to "poll" the intelliHR’s API at regular intervals to check for new events (often referred to as deltas). The application would send a request to the API, the API would check for new jobs and return any that have occurred since the last request, and the application would process the new events into your Payroll system as needed.
Polling can be an effective way to get data from an API, but it can also be resource-intensive, since it requires the application to constantly send requests to the API. As a result, we recommend you utilise intelliHR’s wide range of webhooks, which are more efficient, less resource-intensive and more secure than polling.
New Job Data Flow
Set Up Your Polling Application
Set up an application or script that can send requests to the IntelliHR and Payroll APIs and process the responses. This could involve using a programming language like Python or Ruby, or using a tool like Zapier set up the integration.
Regardless of the method, you will need to HTTP GET requests to the /jobs endpoint and make use of the updatedWithin filter.
Including the updatedWithin filter as below would return all jobs updated or created within the last day. As a result, your POLLing application should perform this request once daily.
"url": https://api.intellihr.io/v1/jobs?filters[updatedWithin][eq]=1
"method": 'GET'
"headers": {
"Content-Type": 'application/json',
"Accept": 'application/json',
"Authorization": `Bearer ${apikey}`,
"Tenant": tenantname
}
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/people/{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").
When to use POLLing
There are certain situations where it may be more appropriate to use a polling solution instead of webhooks.
Polling might be more appropriate is when the payroll system needs to check for updates on a regular basis, but the updates are not time-sensitive. For example, an enterprise payroll system might want to check for updates to the list of current employees once a day, and a polling solution could be used to retrieve this information. In order to achieve this, you might use the List All Jobs endpoint with the jobStatus filter set to Current Job.
Another example might be when connecting a system to an SFTP service. If the system needs to periodically check for updates to files on the SFTP server, a polling solution could be used to check for changes at regular intervals.
In general, Polling is most appropriate in situations where the updates being checked for are not time-sensitive and do not need to be acted upon immediately. Webhooks are more suitable for situations where real-time notification of updates is required.
Tip: For information on how to using POLLing to build your payroll integration with intelliHR, contact your friendly intelliHR Integration Team! You can reach them at integrations@intellihr.com