Skip to main content

Employment Hero

Availability
Available CoreAvailable StandardAvailable PlusAvailable ProAvailable Enterprise FlexAvailable PyAirbyte
Connector type (beta)
Available Data replicationNot available Agent(learn more)
Support Level
Marketplace
Connector Version
0.1.1 (last updated 4 days ago)
Sync Success Rate
Low
Usage Rate
Low
Data workers used
0.2 per sync (Learn more)
Definition ID
e2db518e-ef68-40bb-a2b6-b9f9aabbadb3

This page contains the setup guide and reference information for the Employment Hero source connector. The connector syncs HR data, including organisations, employees, leave requests, teams, policies, certifications, custom fields, and pay details, from the Employment Hero API.

Prerequisites​

  • An Employment Hero Platinum subscription or above. Employment Hero only offers API access on these plans.
  • Access to the Employment Hero Developer Portal, so you can create an OAuth 2.0 application.
  • An Employment Hero account to authorize the application. Employment Hero recommends an admin or owner account, because the connector can only read data that the authorizing account has permission to see.
  • An OAuth 2.0 client that supports the authorization code flow with PKCE, such as Postman, to obtain a refresh token.

Authentication setup​

The Employment Hero API uses OAuth 2.0, and access tokens expire after 15 minutes. The connector authenticates with your OAuth application's Client ID, Client Secret, and a Refresh Token. It exchanges the refresh token for a new access token at https://oauth.employmenthero.com/oauth2/token whenever it needs one. For details, see the Employment Hero authentication docs.

Step 1: Create an OAuth 2.0 application​

  1. Sign in to Employment Hero and open the Developer Portal from the menu under your profile name in the top right corner. You can also go directly to https://secure.employmenthero.com/app/v2/organisations/<your-org-id>/developer_portal/api.

  2. Select Add Application and give the application a name.

  3. Select the read scopes for every resource you plan to sync. Scopes use the format urn:mainapp:<resource>:read, for example urn:mainapp:organisations:read and urn:mainapp:employees:read.

    warning

    You can't change an application's scopes after you create it. If you need more scopes later, create a new application.

  4. Enter a redirect URI. Employment Hero requires HTTPS redirect URIs. If you use Postman to obtain the refresh token, enter https://oauth.pstmn.io/v1/callback.

  5. Copy the Client ID and Client Secret from the application details page.

Step 2: Obtain a refresh token​

Since 2026-09-30, Employment Hero requires PKCE for all authorization flows. A refresh token works only if it was issued through the PKCE flow, so a refresh token you obtained without PKCE before that date fails.

To obtain a refresh token with Postman:

  1. Open a new request in Postman, go to the Authorization tab, and select OAuth 2.0.
  2. Set Grant Type to Authorization Code (With PKCE) and Code Challenge Method to SHA-256.
  3. Set Auth URL to https://oauth.employmenthero.com/oauth2/authorize and Access Token URL to https://oauth.employmenthero.com/oauth2/token.
  4. Enter your Client ID and Client Secret, and set Client Authentication to Send client credentials in body. Leave Scope and State blank.
  5. Select Get New Access Token, sign in to Employment Hero, and approve the request in your browser.
  6. Copy the refresh_token value from the token response. Don't use the access_token, which expires after 15 minutes.

Employment Hero refresh tokens don't currently expire, and you can reuse the same refresh token for every token request.

If your account belongs to more than one organisation that enforces single sign-on (SSO), each token can include only one SSO organisation. Organisations that don't enforce SSO are included automatically. To sync more than one SSO organisation, authorize each one separately and use each resulting refresh token in its own source.

Step 3: Set up the source in Airbyte​

  1. Enter the Client ID, Client Secret, and Refresh Token.
  2. Optional: To sync the employee_certifications, pay_details, and employee_custom_fields streams, enter Organization ID and Employees ID values. See Organization and employee IDs.
  3. Select Set up source.

Organization and employee IDs​

Most streams discover their parent records automatically. The connector reads the organisations stream and then requests employees, leave requests, teams, policies, certifications, and custom fields for every organisation it returns.

The employee_certifications, pay_details, and employee_custom_fields streams work differently. They only read data for the IDs you enter in the Organization ID (organization_configids) and Employees ID (employees_configids) fields. The connector requests every combination of the organisation IDs and employee IDs you enter, so each employee ID is requested under each organisation ID.

To find these IDs, sync the organisations and employees streams first and copy the id values from the results.

Configuration​

InputTypeDescription
client_idstringClient ID of the OAuth 2.0 application created in the Employment Hero Developer Portal.
client_secretstringClient Secret of the OAuth 2.0 application created in the Employment Hero Developer Portal.
refresh_tokenstringRefresh token obtained from the Employment Hero OAuth 2.0 authorization code flow with PKCE.
organization_configidsarrayOrganization ID. IDs of the organisations to read the employee_certifications, pay_details, and employee_custom_fields streams for. Find them in the organisations stream.
employees_configidsarrayEmployees ID. IDs of the employees to read the employee_certifications, pay_details, and employee_custom_fields streams for. Find them in the employees stream.

Supported streams​

All streams support the Full Refresh sync mode only. Incremental sync isn't supported.

Stream nameEmployment Hero endpointPrimary key
organisations/api/v1/organisationsid
employees/api/v1/organisations/{organisation_id}/employeesid
leave_requests/api/v1/organisations/{organisation_id}/leave_requestsid
employee_certifications/api/v1/organisations/{organisation_id}/employees/{employee_id}/certificationsid
pay_details/api/v1/organisations/{organisation_id}/employees/{employee_id}/pay_detailsid
teams/api/v1/organisations/{organisation_id}/teamsid
policies/api/v1/organisations/{organisation_id}/policiesid
certifications/api/v1/organisations/{organisation_id}/certificationsid
custom_fields/api/v1/organisations/{organisation_id}/custom_fieldsid
employee_custom_fields/api/v1/organisations/{organisation_id}/employees/{employee_id}/custom_fieldsid

The Employment Hero interface calls teams "Groups," but the API and the teams stream still use the term "teams."

Limitations​

  • Rate limits: Employment Hero allows 20 requests per second and 100 requests per minute. The connector requests 20 records per page and retries rate-limited (HTTP 429) responses up to three times with exponential backoff.
  • Permissions: The connector only returns data that the account you authorized with can access. A non-admin account can return partial data or 403 Forbidden errors.
  • Regional fields: Some fields only apply to employees in specific regions (Australia, Malaysia, Singapore, New Zealand, United Kingdom, or Canada). Employment Hero omits these fields from records for employees outside the matching region.

IP allow list​

If you use Airbyte Cloud and your organization restricts access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Reference​

Config fields reference

Field
Type
Property name
string
client_id
string
client_secret
string
refresh_token
array
employees_configids
array
organization_configids

Changelog​

Expand to review
VersionDatePull RequestSubject
0.1.12026-10-1388611Update dependencies
0.1.02026-10-0988211Replace static access-token auth with OAuth 2.0 refresh-token flow (access tokens expire after 15 minutes)
0.0.662026-10-0687860Update dependencies
0.0.652026-09-2987167Update dependencies
0.0.642026-09-2286634Update dependencies
0.0.632026-09-1586035Update dependencies
0.0.622026-09-0885480Update dependencies
0.0.612026-08-1884556Update dependencies
0.0.602026-08-1183920Update dependencies
0.0.592026-08-0483450Update dependencies
0.0.582026-07-2882927Update dependencies
0.0.572026-07-2182420Update dependencies
0.0.562026-07-1481805Update dependencies
0.0.552026-06-3081067Update dependencies
0.0.542026-06-2380448Update dependencies
0.0.532026-06-1679850Update dependencies
0.0.522026-06-0979324Update dependencies
0.0.512026-06-0278697Update dependencies
0.0.502026-04-2877200Update dependencies
0.0.492026-04-2176563Update dependencies
0.0.482026-03-3175776Update dependencies
0.0.472026-03-2475338Update dependencies
0.0.462026-03-1074440Update dependencies
0.0.452026-02-2473901Update dependencies
0.0.442026-02-1773460Update dependencies
0.0.432026-02-1073012Update dependencies
0.0.422026-01-2071917Update dependencies
0.0.412026-01-1471556Update dependencies
0.0.402025-12-1870568Update dependencies
0.0.392025-11-2570162Update dependencies
0.0.382025-11-1869391Update dependencies
0.0.372025-10-2968707Update dependencies
0.0.362025-10-2168566Update dependencies
0.0.352025-10-1467739Update dependencies
0.0.342025-10-0767270Update dependencies
0.0.332025-09-3065842Update dependencies
0.0.322025-08-2365290Update dependencies
0.0.312025-08-0964694Update dependencies
0.0.302025-08-0264327Update dependencies
0.0.292025-07-2664022Update dependencies
0.0.282025-07-1963552Update dependencies
0.0.272025-07-1263015Update dependencies
0.0.262025-07-0562795Update dependencies
0.0.252025-06-2862339Update dependencies
0.0.242025-06-2261989Update dependencies
0.0.232025-06-1461251Update dependencies
0.0.222025-05-2460021Update dependencies
0.0.212025-05-0359446Update dependencies
0.0.202025-04-2658910Update dependencies
0.0.192025-04-1957832Update dependencies
0.0.182025-04-0557283Update dependencies
0.0.172025-03-2956521Update dependencies
0.0.162025-03-2255970Update dependencies
0.0.152025-03-0855320Update dependencies
0.0.142025-03-0154455Update dependencies
0.0.132025-02-1553716Update dependencies
0.0.122025-02-0853322Update dependencies
0.0.112025-02-0152817Update dependencies
0.0.102025-01-2552347Update dependencies
0.0.92025-01-1851681Update dependencies
0.0.82025-01-1151081Update dependencies
0.0.72024-12-2850526Update dependencies
0.0.62024-12-2150024Update dependencies
0.0.52024-12-1449489Update dependencies
0.0.42024-12-1249190Update dependencies
0.0.32024-11-0447819Update dependencies
0.0.22024-10-2847632Update dependencies
0.0.12024-09-2545888Initial release by @btkcodedev via Connector Builder
Was this page helpful?