Employment Hero API: Guide for HRIS Integration and Automation

Getting Started with Employment Hero API

Employment Hero API allows businesses to automate and integrate their HR and payroll processes with Employment Hero's platform. It enables:

• Employee Management: Add, update, or remove employee records.
• Payroll Processing: Automate salary calculations, tax deductions, and payments.
• HR Functions: Manage leave requests, benefits, performance reviews, and more.

This API is designed to streamline HR operations, reduce manual data entry, and ensure data consistency across your organization’s software systems.

‍

OAuth 2.0 Authentication

Before interacting with Employment Hero's API, you need to authenticate your requests to ensure they are secure. Employment Hero uses OAuth 2.0 for authentication, a robust and widely adopted standard.

Steps to Authenticate:

1. Obtain API Credentials:

• Client ID and Client Secret: Provided by Employment Hero when you register your application.

2. Request an Access Token:

• Send a POST request to the authentication endpoint with your credentials to receive an access token.

POST https://api.employmenthero.com/oauth/token
Content-Type: application/json

{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
}

3. Use the Access Token:

• Include the token in the Authorization header of your API requests.

Authorization: Bearer YOUR_ACCESS_TOKEN

Example in Python:

import requests

# Authentication details
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"
auth_url = "https://api.employmenthero.com/oauth/token"

# Requesting access token
response = requests.post(auth_url, json={
    "grant_type": "client_credentials",
    "client_id": client_id,
    "client_secret": client_secret
})

access_token = response.json().get("access_token")

‍

Deep Dive into Employment Hero API Endpoints

The Employment Hero API provides a range of endpoints that allow developers to access various employee data.

Here are the most commonly used endpoints, along with practical use cases.

1. GET /v1/organisations/:id/employees

• Description: Returns an array of all employees. Every employees must be managed by your managed organisation.
• cURL Request:

curl "https://api.employmenthero.com/api/v1/organisations/:id/employees"
  -H "Authorization: bearer AUXJ3123xyrj123fdsjkl124aAJKQ"

• Parameters:
  • organisation_id: The ID of the organization to get employees.
• Use Case: Obtain employee data of an organization from Employment Hero into your system.

‍

2. GET /v1/organisations/:id

• Description: This endpoint retrieves a specific employee.
• cURL Request:

curl "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:id"
  -H "Authorization: bearer AUXJ3123xyrj123fdsjkl124aAJKQ"

• Parameters:
  • id: The ID of the employee to retrieve.
  • organisation_id: The ID of the organization to get employees.
• Use Case: Obtain a specific employee’s data from Employment Hero into your system.

‍

3. GET /v1/organisations/:organisation_id/employees/:employee_id/timesheet_entries

• Description: This endpoint retrieves a list of all timesheet entries for a specific employee.
• cURL Request:

curl
"https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/timesheet_entries"
  -H "Authorization: bearer AUXJ3123xyrj123fdsjkl124aAJKQ"

• Parameters:
  • employee_id: The ID of the employee to retrieve
  • organisation_id: The ID of the organization to get employees
  • start_date: The start date of time range for date field (dd/mm/yyyy)
  • end_date: The end date of time range for date field (dd/mm/yyyy)
• Use Case: Obtain employee timesheet data from Employment Hero into your system.

Pagination and Rate limits

Pagination

When retrieving lists of data (e.g., employees), the API may paginate results to manage large datasets efficiently.

• Parameters:
  • page: The page number to retrieve
  • per_page: The number of items per page

For example, here’s how you can implement pagination while retrieving employees:

GET /v1/employees?page=2&per_page=50
Authorization: Bearer YOUR_ACCESS_TOKEN

‍

Rate Limits

For Employment Hero API, rate limit is currently set to 10 requests per second and 100 requests per minute. Exceeding this limit will result in a 429 error code:

 429 Too Many Requests -- You have exceeded the rate limit. Please try again later.

Implement an exponential backoff strategy to retry requests after a brief delay.

‍

Troubleshooting Guide

Error Handling

APIs can return errors for various reasons, such as invalid requests or server issues. Employment Hero uses standard HTTP status codes to indicate success or failure.

Common Status Codes:

• 200 OK: The request was successful.
• 201 Created: A new resource was successfully created.
• 400 Bad Request: The request was malformed or missing required parameters.
• 401 Unauthorized: Authentication failed or was not provided.
• 403 Forbidden: You don’t have permission to access the resource.
• 404 Not Found: The requested resource doesn’t exist.
• 500 Internal Server Error: An error occurred on the server.

Get Started With with Employment Hero API Using Bindbee

Integrating with Employment Hero shouldn’t feel like a battle.But for most teams, it ends up being a major time sink—draining valuable engineering resources.

Why put your developers through the grind when Bindbee can get you live with Employment Hero in just minutes?

Setting up Employment Hero connector with Bindbee

• Sign up with Bindbee and navigate to the dashboard.
• Create a Connector:
  • Click on Create Connector from the dashboard.
  • Select HRIS as the type of integration. Enter customer details and give your connector a unique ID (e.g., Employment_Hero_Integration).
• Generate a Magic Link:
  • After setting up the connector, click Create Link to generate a magic link. This will allow the customer to authenticate the connection with Employment Hero.
  • Open the link and enter the necessary credentials. This step establishes the connection between Employment Hero and Bindbee.
• Sync the Connector:
  • Once the connection is made, the connector will begin syncing data from BambooHR. This may take a few minutes depending on the size of the data. You can track the sync status in the connector section.
• Access the Synced Data:
  • After syncing, go to the Employee section in the Bindbee dashboard and select Get Employees to retrieve employee data from BambooHR.
• Get the API Key and Connector Token:
  • Copy the API key and the x-connector-token from the Bindbee dashboard, which you will need to make authenticated API requests.

‍

Retrieving Employee Data with Bindbee

Once the Employment Hero data has been synced, you can retrieve employee data on to your application via the Bindbee API.

Here’s a step-by-step process for accessing synced data from BambooHR through Bindbee’s unified API:

1. Request Setup:

Use the Bindbee API to send a request for employee data. You’ll need both your Bindbee API token and the x-connector-token.

2. Example  cURL Request:

curl --request GET \
  --url https://api.bindbee.com/hris/v1/employees \
  --header 'Authorization: Bearer YOUR_BINDBEE_API_KEY' \
  --header 'x-connector-token: YOUR_CONNECTOR_TOKEN'

This request will return a list of employee objects, including details like the employee’s first name, last name, job title, department, and contact information.

‍3. Sample Response:

{
  "items": [
    {
      "id": "018b18ef-c487-703c-afd9-0ca478ccd9d6",
      "first_name": "Kunal",
      "last_name": "Tyagi",
      "job_title": "Chief Technology Officer",
      "department": "Engineering",
      "work_email": "kunal@bindbee.dev"
    }
  ]
}

Bulk Employee Data Retrieval

For retrieving large datasets, Bindbee simplifies the process by allowing you to fetch bulk employee data from BambooHR.

The pagination feature helps manage large responses by returning results in pages.

• Pagination Parameters:
  • Use the cursor and page_size parameters to navigate through the results. By default, Bindbee returns 50 records per page.
  • Example of a paginated request:

url = "https://api.bindbee.com/hris/v1/employees?cursor=MDE4YjE4ZWYtYzk5Yy03YTg2LTk5NDYtN2I3YzlkNTQzM2U1&page_size=50"
response = requests.get(url, headers=headers)

• Querying for Specific Employee Data:
  • You can further refine your request by filtering based on specific fields, such as manager_id, remote_id, or company_id to get employees under a particular manager or company.

Say hello to Bindbee.

Book a demo with our experts today.