Employment HeroIntroduction
Note
API access is currently available on a Platinum subscription and above. If this piques your interest, kindly refer to this article on how you can upgrade your subscription: here or reach out to us via live chat on the HR platform
The Employment Hero API is a RESTful-based API that returns JSON-encoded responses and uses standard HTTP response codes, authentication, and verbs.
Once connected, you'll have access to valuable HR data which can then be leveraged within your app or integration to power workflows and insights. In order to test the Employment Hero API, we recommend using a Bearer token for authentication - see this section for more information.
Base URL: https://api.employmenthero.com
Client Libraries: By default, the Employment Hero API Docs demonstrate using curl to interact with the API over HTTP.
In order to test the Employment Hero API, we recommend using Postman along with a Bearer token for authentication - see the Authentication section for more information on Bearer token-based authentication.
API Versioning Policy
We are committed to providing a stable and reliable API for our developers. To ensure continuity and minimize disruption, we follow a clear versioning policy.
Our API versioning is managed by a version number, for example, https://api.employmenthero.com/api/v1/.... This version number changes only when we introduce breaking changes.
A breaking change is any modification that could disrupt the functionality of a client's existing integration. This includes, but is not limited to:
- Removing or renaming a field.
- Changing the data type of an existing field.
- Altering the fundamental behaviour of an endpoint.
These changes will always result in a new API version (e.g., v1 to v2).
Non-breaking changes are additive and backward-compatible. They will be introduced into the existing API version without creating a new one. Examples of non-breaking changes include:
- Adding new fields to an existing endpoint's response.
- Introducing new endpoints.
- Adding new optional parameters to an existing endpoint.
This approach allows you to confidently build against a stable version, knowing that non-breaking updates will not require you to rewrite your code.
Handling Regional Data
Our platform serves a global user base, and as such, some API responses and functionalities are tied to the regional data of the employee. To help you understand and integrate with these differences, we have established a clear policy for handling regional data.
Global vs. Regional Endpoints and Fields
Global: Unless explicitly tagged, all APIs and fields are considered global. This means they return consistent data regardless of the employee's work location.
Regional: Some APIs and fields are region-specific. This means the data returned will vary based on the employee's assigned work location. To identify these, we use a specific tag format:
- Australia: 🇦🇺 AU
- Malaysia: 🇲🇾 MY
- Singapore: 🇸🇬 SG
- New Zealand: 🇳🇿 NZ
- United Kingdom: 🇬🇧 UK
- Canada: 🇨🇦 CA
Employees working in other regions will default to Australian fields, as consistent with our platform UI.
Regional Field Behavior
- A regional field will only be present in the response if the employee's work location matches the specified region.
- For employees outside that region, the field will be omitted entirely from the response body. You should not expect to receive a null value for these fields in such cases.
Regional API Behavior
- You can still call a regional API for employees in other regions.
- However, for employees outside the specified region, the response will likely contain null or empty values for the regional data fields. This is by design, as the data does not exist for that location.
Errors
Employment Hero uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Employment Hero's servers.
Response Body
An HTTP status code value, without the textual description. Example values include: 400 (Bad Request), 401 (Unauthorized), and 404 (Not Found).
A container for the error information.
A container for the error details.
Note
Rate limit is currently set to 20 requests per second and 100 requests per minute. Should you require a higher limit, please reach out to your admin for assistance.
Response
400 Bad Request -- Invalid request body or parameters.401 Unauthorized -- Invalid or missing authentication token.403 Forbidden -- Insufficient platform user permissions to access requested resource.404 Not Found -- The specified resource could not be found.406 Not Acceptable -- You requested a format that isn't json.422 Unprocessable Entity -- Validation errors in the request body429 Too Many Requests -- You have exceeded the rate limit. Please try again later.Authentication
The preferred secure way to authenticate against and access the Employment Hero API is by using an OAuth 2.0 protocol. Our OAuth 2.0 process described below follows a basic pattern from OAuth 2.0 documentation, please follow the steps below at a high level.
Basic Steps
- To begin, register your application with the Employment Hero platform through our Developer Portal.
- Obtain your client credentials including client ID and secret from the registration page. They will be required in the upcoming steps.
- Authorise your client application with the Employment Hero through our Authorisation Server. You will be redirected to Employment Hero login page if you have not yet logged in. For a successful login, a confirmation page will be shown to acquire user scopes provision.
- Successful authorisation results in a redirection to your provided redirect uri(s) with the authorisation code included.
- Use the authorisation code to request an access token. The response will include both the access and refresh tokens. Extract the access token from the response, and send the access token to the Employment Hero API that you wish to access.
- Please note that for security purposes, the lifetime of the access token is 15 minutes. You can obtain another access token by sending a refresh token request to the Employment Hero Authorisation Server. When refreshing the access token, the new refresh token will be returned as well and does not currently have an expiration time. Clients applications should be built to always store the returned refresh token. Please be sure to keep the refresh token safe and secure.
Developer Portal Access
Note
API access is currently available on a Platinum subscription and above. If this piques your interest, kindly refer to this article on how you can upgrade your subscription: here or reach out to us via live chat on the HR platform
To access the developer portal, visit and sign in to your Employment Hero account. The Developer Portal link is located in the menu under your profile name in the top right corner. The developer portal includes the features:
- API (via OAuth 2.0)
- Webhooks
Obtain Credentials
Visit the Developer Portal to register your application, below are the 3 fields required for creating an OAuth 2.0 application.
Application Properties
| Field | Description |
|---|---|
| Name | A meaningful name for your OAuth 2.0 application (e.g. EH API Test Client) |
| Scope | A list of scopes which the application can access. The scope list will be provided by Employment Hero. NOTE: For security and data sensitivity concerns, scopes are a one-time selection on application creation. |
| Redirect URI(s) | One or more URIs hosted by your company which a user will be redirected to following a successful OAuth handshake. Use a comma-separated list to add multiple redirect URIs. Please note that for security purposes, we request that you provide HTTPS URIs. |
After registering a new OAuth 2.0 application, you can update your application properties except the scopes. The set of credentials includes client ID, secret and your application. Visit the application details page for the set of credentials (e.g. client ID, secret, application information) you will require in the upcoming steps. Below is the description of the generated credentials from the registration.
Credentials
| Attribute | Description |
|---|---|
| Client ID | A unique string representing the registration OAuth 2.0 application. |
| Client Secret | A random secret used by client to authenticate to the Employment Hero Authorisation Server. The client secret is a secret known only to the client and authorisation server. |
Obtain Access Token
OAuth 2.0 application credentials are used for obtaining the access token. We recommend using an admin or an owner type of account to ensure access to all relevant API endpoints.
Authorisation
Before your application can access private data over the Employment Hero API, it must obtain an access token that grants access to that API. Application scopes, which are selected in the previous step, control the set of API endpoints that you are requesting permission for. A single access token is a combination of those permissions. To grant access to your application, a request must be made to our Authorisation Server.
The user accessing the application will be prompted to log in to Employment Hero. After logging in, if the user does not have any Single Sign On organisation's or has already authenticated them, they can click on the skip button. Then the user will be asked to grant the requested permissions from your OAuth 2.0 application as well as the application scopes. A successful login and confirmed permissions will redirect the user back to your specified redirect URL, including the authorisation code. If the user does not grant the permissions, the server will return an error. The authorisation code can then be exchanged for an access token.
For users linked to Single Sign On (SSO) enforced organisations, only one SSO organisation can be authorised per access token. If the user selects and authorises an SSO organisation, the resulting token will include that SSO organisation along with any non-SSO organisations the user has access to. However, if access is required for multiple SSO organisations, the user must authorise each separately, generating a distinct token for each. Non-SSO organisations are automatically included in the access token without additional authorisation steps.
Note
The Employment Hero account used for authorisation can only access the data within its roles or permisions (e.g. the employee cannot see the owner information).
https:/oauth.employmenthero.com/oauth2/authorizeQuery Parameters
Your client ID from OAuth 2.0 credentials
One of your specified redirect url(s) in your OAuth 2.0 application
Use code here.
Example
curl -X GET \"https://oauth.employmenthero.com/oauth2/authorize?\client_id=u6zcls9nx3b9Lq0sSLgUiTgRhMM3Miwx9KytOUrC9d0&\redirect_uri=https://app.example.com/callback&\response_type=code"Response
// example of successful logging in and granting permission// where https://app.example.com/callback is your redirect urihttps://app.example.com/callback? \ code=7E2s5m5OHdNSPdtNMri6xNoKH62nwV_0hl9xdJ1g7fsAccess Token
The access token is required to access protected resources. It represents an authorisation issued to the client and will expire after 15 minutes. To obtain it, request an access token from our Authorisation Server. The request requires client_id, secret, and your granted authorization_code for security purposes. The response data includes access_token, refresh_token and token_type which indicates the correct authorisation type for the access token. There are many types of authorisation when making a request, currently we only support the Bearer type.
https:/oauth.employmenthero.com/oauth2/tokenQuery Parameters
Client ID from OAuth 2.0 application credentials
Secret from OAuth 2.0 application credentials
Uses default value authorization_code
Authorization code obtained from Authorisation Server extracted from redirect uri parameters in the previous step
Your redirect uri listed in the OAuth 2.0 application
Response Body
The granted access token.
The token required to refresh the access token.
Type of authorisation used to access protected API. NOTE: only the Bearer type is currently supported
Lifetime of the access token (in seconds)
Granted scopes for this access token
Example
curl -X POST \"https://oauth.employmenthero.com/oauth2/token?\client_id=u6zcls9nx3b9Lq0sSLgUiTgRhMM3Miwx9KytOUrC9d0&\client_secret=75bAHTX7oo2ksTgnZO71BHMnmkyuaYAQzbgIeBPoecw&\grant_type=authorization_code&\code=7E2s5m5OHdNSPdtNMri6xNoKH62nwV_0hl9xdJ1g7fs&\redirect_uri=https://app.example.com/callback"Response
{ "access_token": "eyJhbGciOiJSUzI1NiJ9.joxNT...xC5vm9EwF3wDpFg", "refresh_token": "PDhcuwQPVMU9XPVpSPekPdpbkY-mm7snmd-5nWVqjg4", "token_type": "bearer", "expires_in": 900, "scope": "urn:mainapp:organisations:read urn:mainapp:employees:read"}Use Access Token
After obtaining the access token from the Employment Hero Authorisation Server, request to the Employment Hero API must include the access token via HTTP authorisation header. All configured scopes can be seen in your OAuth 2.0 application from the Employment Hero Developer Portal page.
https:/api.employmenthero.com/api/v1/organisationsPath Parameters
The access token to use for the request
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Refresh Access Token
Access tokens expire after 15 minutes. For continuous usage, a new access token must be requested using the refresh token.
Note
The same refresh token can be used to refresh the access token each time.
https:/oauth.employmenthero.com/oauth2/tokenQuery Parameters
Client ID from OAuth 2.0 application credentials
Secret from OAuth 2.0 application credentials
Uses default value refresh_token
Authorisation code obtained from Authorisation Server extracted from redirect url parameters in the previous step
Your redirect uri listed in the OAuth 2.0 application
The old refresh token obtained from access token request or last refresh token request.
Response Body
The granted access token.
The refresh token to refresh access token.
Type of authorisation used to access protected API
Lifetime of the access token (in seconds)
Granted scopes for this access token
Example
curl -X POST \"https://oauth.employmenthero.com/oauth2/token?\client_id=u6zcls9nx3b9Lq0sSLgUiTgRhMM3Miwx9KytOUrC9d0&\client_secret=75bAHTX7oo2ksTgnZO71BHMnmkyuaYAQzbgIeBPoecw&\grant_type=refresh_token&\refresh_token=lEzwW-7rz-AiLPo1ZDP0ZFEHzIwAzMbV3yfk7rsJSfs"Response
{ "access_token": "eyJhbGciOiJSUzI1NiJ9.joxNT...xC5vm9EwF3wDpFg", "refresh_token": "kgIaDcs5iy1jw9KN5jz84sSiGnrDr_XW5UYKwueBFDc", "token_type": "bearer", "expires_in": 900, "scope": "urn:mainapp:organisations:read urn:mainapp:employees:read"}Organisation
Returns an array of all organisations. Every organisation must be managed by you or the organisation which you work for.
https:/api.employmenthero.com/api/v1/organisationsQuery Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an item array of up to limit organisations. Each entry in the array is a separate organisation object. If there are no more organisations, the resulting array will be empty.
Unique identifier for the object.
The name of the organisation to retrieve
The phone number of your organisation
Two-letter ISO code representing the country of your organisation
The publicly accessible URL to fetch the your organisation logo.
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "bdfcb02b-fcc3-4f09-8636-c06c14345b86", "name": "Employment Hero Pty Ltd", "phone": "+61280302222", "country": "AU", "logo_url": "http://logo.png" }, { "id": "5a2704b0-e8a2-4765-9aec-b193e30672e4", "name": "Thinkei", "phone": "+611234567890", "country": "AU", "logo_url": "http://logo.png" } ], "page_index": 1, "item_per_page": 20, "total_items": 2, "total_pages": 1 }}This endpoint retrieves information for a specific organisation. The same data is returned as when listing the organisation, but with some additional details.
https:/api.employmenthero.com/api/v1/organisations/:idPath Parameters
The ID of the organisations to retrieve
Response Body
Unique identifier for the object.
The name of the organisation to retrieve
The phone number of your organisation
Two-letter ISO code representing the country of your organisation
The publicly accessible URL to fetch the your organisation logo.
The organisation's address.
The end of week day for the organisation
The typical work day of your organisation (Ex: 8.0 hours).
The list of all your payroll admin emails.
The organisation's subscription plan.
The name of your organisation superfund
The number of your organisation employees
The number of active employees
The number of pending employees
The organisation's time zone
Time at which the organisation was created
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "id": "bdfcb02b-fcc3-4f09-8636-c06c14345b86", "name": "Employment Hero Pty Ltd", "phone": "+612803222", "country": "AU", "logo_url": "logo.png", "primary_address": "Test Street 79390, 11-17 York Street, SYDNEY, NSW, 2000, AU", "end_of_week": "Saturday", "typical_work_day": "8.0", "payroll_admin_emails": [ "admin1@thinkei.com", "admin2@thinkei.com", "admin3@thinkei.com" ], "subscription_plan": "CSA (8)", "superfund_name": null, "employees_count": 154, "active_employees_count": 105, "pending_employees_count": 4, "time_zone": "Australia/Sydney", "created_at": "2016-04-12T16:49:37+10:00" }}Employee
Overview
The Employee object includes personal and employment details for employees in an organisation. Contractor details are also included in this object, and contractor-specific fields will only be returned for contractors. A contractor is identified by the independent_contractor field, and contractor-specific fields will be documented with the label: Contractor
Returns an array of all employees. Every employees must be managed by your managed organisation.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employeesPath Parameters
The ID of the organisation to get employees
Query Parameters
Optional filter: employee or contractor; omit to get both
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of up to the limit of employees. Each entry in the array is a separate employee object. If there are no more employees belonging to your organisation, the resulting array will be empty.
Unique identifier for the object.
The account name of employee
The title of employee
The role of employee
The first name of employee
The last name of employee
The middle name of employee
The address of employee
The avatar url of employee
The preferred name of the employee
The job title of the employee
The gender of the employee
The country of the employee
The date of birth of employee
The martial status of employee
The personal email of employee
The personal mobile number of employee
The home phone of employee
The employing entity of employee
The code of employee
The location of employee
The company email of employee
The company mobile of employee
The company landline of employee
The start date of employee
The termination day of employee
The teams of employee
The primary cost centre of employee
The secondary cost centre of employee
The primary manager of employee
The secondary manager of employee
The external id of employee (ID of payroll system)
The status of employee
The detailed termination summary of a terminated employee, including reason, date, and actioning user
The employment type of employee. Valid types depend on the employee's region. Common values: Full-time, Part-time, Casual
Typical hours worked per day.
Work-hours roster type.
The trial or probation period type of employee. Supported values are trial_period and probation_period
The trial period length in days of employee when trial_or_probation_type is trial_period
The probation period length in months of an employee when trial_or_probation_type is probation_period
The start date of the Global Teams employee
The probation end date of the Global Teams employee
Indicates if the member is an independent contractor
Contractor trading name
Australian Business Number of the contractor
Contractor business registration details
UK–specific tax and national-insurance information
Primary email address of the employee (alias of account_email).
Employee's complete registered legal name.
Registered (legal) name of the employee, excluding preferred or known-as names.
Convenience field that concatenates first, middle and last name.
Employee-provided pronouns (e.g. she/her, they/them).
Whether the employee's mobile number is visible in the staff directory.
Identifies as Aboriginal and/or Torres Strait Islander.
The previous family name of the employee.
Short bio or "about me" text shown in company directory.
Indicates the employee has opted out of Instapay referral communications.
Country in which the employee primarily works.
Payroll engine / product the employee belongs to (e.g. KeyPay, Xero, Global Teams).
IANA time-zone identifier for the employee (e.g. Asia/Singapore).
Nationality of the employee (ISO-3166 alpha-2 code).
Residential address of the employee
Postal address of the employee
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "account_email": "daniel@thinkei.com", "title": "Ms", "role": "owner", "first_name": "Daniel", "last_name": "Tran", "middle_name": "Tuan", "address": "Test Street 184752, Apt 8B, Sydney, NSW, 2000, AU", "avatar_url": "http://avatar.png", "known_as": "Danny", "job_title": "Grad Developer", "gender": "Female", "country": "AU", "date_of_birth": "1995-02-13T00:00:00+00:00", "marital_status": "Single", "personal_email": "abc@thinkei.com", "personal_mobile_number": "01285659993", "home_phone": "02 9123 4567", "employing_entity": "US", "code": "EMP123", "location": null, "company_email": "abc@thinkei.com", "company_mobile": "0412 345 678", "company_landline": "02 8181 1234", "start_date": "2017-03-01T00:00:00+00:00", "termination_date": null, "teams": [ { "id": "95df8139-479f-432e-b8f9-922352123e4a", "name": "Team 1" }, { "id": "95df8139-479f-432e-b8f9-112352123e4a", "name": "Team 2" } ], "primary_cost_centre": { "id": "95df8139-479f-432e-b8f9-922352d2fe4a", "name": "Employment Hero" }, "secondary_cost_centres": [], "primary_manager": { "id": "4a728243-8930-4a93-9bd8-a6843e7b59ec", "name": "Jessica" }, "secondary_manager": null, "external_id": "external_id_123", "status": "active", "termination_summary": null, "employment_type": "Full-time", "typical_work_day": "7.6", "roster": "Annual", "trial_or_probation_type": "probation_period", "trial_length": 30, "probation_length": 3, "global_teams_start_date": "01/01/2025", "global_teams_probation_end_date": "01/03/2025", "independent_contractor": false, "trading_name": "Emma Frost Consulting", "abn": "12345678901", "business_detail": { "country": "AU", "number": "BN-987654", "business_type": "sole_trader" }, "uk_tax_and_national_insurance": { "id": "uk-tni-1", "unique_taxpayer_reference": "1234567890", "national_insurance_number": "QQ123456C" }, "email": "daniel@thinkei.com", "full_legal_name": "Daniel Tuan Tran", "legal_name": "Tran Tuan Daniel", "full_name": "Daniel Tran", "pronouns": "she/her", "display_mobile_in_staff_directory": true, "aboriginal_torres_strait_islander": false, "previous_surname": "Tran", "biography": "Graduate developer passionate about clean code and football.", "instapay_referral_opted_out": false, "work_country": "AU", "payroll_type": "KeyPay", "time_zone": "Australia/Sydney", "nationality": "AU", "residential_address": { "address_type": "residential", "line_1": "Test Street 184752", "line_2": "Apt 8B", "line_3": null, "block_number": "184", "level_number": "8", "unit_number": "B", "city": "SYDNEY", "postcode": "2000", "state": "NSW", "suburb": "Barangaroo", "country": "AU", "is_residential": true, "street_name": "Test Street", "is_manually_entered": false }, "postal_address": { "address_type": "postal", "line_1": "PO Box 999", "line_2": null, "line_3": null, "block_number": null, "level_number": null, "unit_number": null, "city": "SYDNEY", "postcode": "2001", "state": "NSW", "suburb": "Barangaroo", "country": "AU", "is_residential": false, "street_name": "PO Box", "is_manually_entered": false } } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}Contractor-only fields
{ "data": { "items": [ { "trading_name": "Emma Frost Consulting", "abn": "12345678901", "business_detail": { "country": "AU", "number": "BN-987654", "business_type": "sole_trader" }, "uk_tax_and_national_insurance": { "id": "uk-tni-1", "unique_taxpayer_reference": "1234567890", "national_insurance_number": "QQ123456C" } } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}This endpoint retrieves a specific employee.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:idPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve
Response Body
Unique identifier for the object.
The account name of employee
The title of employee
The role of employee
The first name of employee
The last name of employee
The middle name of employee
The address of employee
The avatar url of employee
The preferred name of the employee
The job title of the employee
The gender of the employee
The country of the employee
The date of birth of employee
The martial status of employee
The personal email of employee
The personal mobile number of employee
The home phone of employee
The employing entity of employee
The code of employee
The location of employee
The company email of employee
The company mobile of employee
The company landline of employee
The start date of employee
The termination day of employee
The teams of employee
The primary cost centre of employee
The secondary cost centre of employee
The primary manager of employee
The secondary manager of employee
The external id of employee (ID of payroll system)
The status of employee
The detailed termination summary of a terminated employee, including reason, date, and actioning user
The employment type of employee. Valid types depend on the employee's region. Common values: Full-time, Part-time, Casual
Typical hours worked per day.
Work-hours roster type.
The trial or probation period type of employee. Supported values are trial_period and probation_period
The trial period length in days of employee when trial_or_probation_type is trial_period
The probation period length in months of an employee when trial_or_probation_type is probation_period
The start date of the Global Teams employee
The probation end date of the Global Teams employee
Indicates if the member is an independent contractor
Contractor trading name
Australian Business Number of the contractor
Contractor business registration details
UK–specific tax and national-insurance information
Primary email address of the employee (alias of account_email).
Employee's complete registered legal name.
Registered (legal) name of the employee, excluding preferred or known-as names.
Convenience field that concatenates first, middle and last name.
Employee-provided pronouns (e.g. she/her, they/them).
Whether the employee's mobile number is visible in the staff directory.
Identifies as Aboriginal and/or Torres Strait Islander.
The previous family name of the employee.
Short bio or "about me" text shown in company directory.
Indicates the employee has opted out of Instapay referral communications.
Country in which the employee primarily works.
Payroll engine / product the employee belongs to (e.g. KeyPay, Xero, Global Teams).
IANA time-zone identifier for the employee (e.g. Asia/Singapore).
Nationality of the employee (ISO-3166 alpha-2 code).
Residential address of the employee
Postal address of the employee
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "account_email": "daniel@thinkei.com", "title": "Ms", "role": "owner", "first_name": "Daniel", "last_name": "Tran", "middle_name": "Tuan", "address": "Test Street 184752, Apt 8B, Sydney, NSW, 2000, AU", "avatar_url": "http://avatar.png", "known_as": "Danny", "job_title": "Grad Developer", "gender": "Female", "country": "AU", "date_of_birth": "1995-02-13T00:00:00+00:00", "marital_status": "Single", "personal_email": "abc@thinkei.com", "personal_mobile_number": "01285659993", "home_phone": "02 9123 4567", "employing_entity": "US", "code": "EMP123", "location": null, "company_email": "abc@thinkei.com", "company_mobile": "0412 345 678", "company_landline": "02 8181 1234", "start_date": "2017-03-01T00:00:00+00:00", "termination_date": null, "teams": [ { "id": "95df8139-479f-432e-b8f9-922352123e4a", "name": "Team 1" }, { "id": "95df8139-479f-432e-b8f9-112352123e4a", "name": "Team 2" } ], "primary_cost_centre": { "id": "95df8139-479f-432e-b8f9-922352d2fe4a", "name": "Employment Hero" }, "secondary_cost_centres": [], "primary_manager": { "id": "4a728243-8930-4a93-9bd8-a6843e7b59ec", "name": "Jessica" }, "secondary_manager": null, "external_id": "external_id_123", "status": "active", "termination_summary": null, "employment_type": "Full-time", "typical_work_day": "7.6", "roster": "Annual", "trial_or_probation_type": "probation_period", "trial_length": 30, "probation_length": 3, "global_teams_start_date": "01/01/2025", "global_teams_probation_end_date": "01/03/2025", "independent_contractor": false, "trading_name": "Emma Frost Consulting", "abn": "12345678901", "business_detail": { "country": "AU", "number": "BN-987654", "business_type": "sole_trader" }, "uk_tax_and_national_insurance": { "id": "uk-tni-1", "unique_taxpayer_reference": "1234567890", "national_insurance_number": "QQ123456C" }, "email": "daniel@thinkei.com", "full_legal_name": "Daniel Tuan Tran", "legal_name": "Tran Tuan Daniel", "full_name": "Daniel Tran", "pronouns": "she/her", "display_mobile_in_staff_directory": true, "aboriginal_torres_strait_islander": false, "previous_surname": "Tran", "biography": "Graduate developer passionate about clean code and football.", "instapay_referral_opted_out": false, "work_country": "AU", "payroll_type": "KeyPay", "time_zone": "Australia/Sydney", "nationality": "AU", "residential_address": { "address_type": "residential", "line_1": "Test Street 184752", "line_2": "Apt 8B", "line_3": null, "block_number": "184", "level_number": "8", "unit_number": "B", "city": "SYDNEY", "postcode": "2000", "state": "NSW", "suburb": "Barangaroo", "country": "AU", "is_residential": true, "street_name": "Test Street", "is_manually_entered": false }, "postal_address": { "address_type": "postal", "line_1": "PO Box 999", "line_2": null, "line_3": null, "block_number": null, "level_number": null, "unit_number": null, "city": "SYDNEY", "postcode": "2001", "state": "NSW", "suburb": "Barangaroo", "country": "AU", "is_residential": false, "street_name": "PO Box", "is_manually_entered": false } }}Contractor-only fields
{ "data": { "trading_name": "Emma Frost Consulting", "abn": "12345678901", "business_detail": { "country": "AU", "number": "BN-987654", "business_type": "sole_trader" }, "uk_tax_and_national_insurance": { "id": "uk-tni-1", "unique_taxpayer_reference": "1234567890", "national_insurance_number": "QQ123456C" } }}This endpoint creates a new employee record with minimal required information for quick onboarding. This is a streamlined version of employee creation that requires only essential details to get an employee started in the system.
https:/api.employmenthero.com/api/v1/employees/quick_add_employeeRequest Body
The ID of the employing entity. Must be a valid employing entity within the organisation.
Employee's first name. Cannot be blank.
Employee's last name. Cannot be blank.
Employee's full legal name as it appears on official documents.
Employee's email address. Must be a valid email format and unique within the organisation.
Employee's date of birth in YYYY-MM-DD format.
Work location details
Response Body
Returns a success message with the newly created employee's ID. The employee record is created with the provided information and can be further updated using other employee endpoints.
Note: An invite email will be sent to the newly added employee.
Success message
The ID of the newly created employee
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/employees/quick_add_employee" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "employing_entity_id": "3a41ab5f-fd18-4c99-b475-040a098dac89", "first_name": "First Name", "last_name": "Last Name", "full_legal_name": "Full Legal Name", "email": "dev@example.com", "date_of_birth": "1995-01-01", "work_location": { "id": "b992fc49-7e98-4743-b53b-51bec9cf4dc3", "name": "Sydney Office", "country": "AU" } }'Response
{ "data": { "message": "Employee file successfully created.", "employee_id": "60b3a532-8c18-4ed6-bd01-2aa3b29ad24b" }}This endpoint creates a new contractor record with minimal required information for quick onboarding. This is specifically designed for independent contractors and includes business registration details required for contractor management.
https:/api.employmenthero.com/api/v1/employees/quick_add_contractorRequest Body
Trading name of the contractor's business. Cannot be blank.
Contractor's first name. Cannot be blank.
Contractor's last name. Cannot be blank.
Contractor's full legal name as it appears on official documents.
Contractor's email address. Must be a valid email format and unique within the organisation.
Contractor's date of birth in YYYY-MM-DD format.
Business registration details for the contractor.
Response Body
Returns a success message with the newly created contractor's ID. The contractor record is created with the provided information and can be further updated using other employee endpoints.
Note: An invite email will be sent to the newly added employee.
Success message
The ID of the newly created contractor
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/employees/quick_add_contractor" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "trading_name": "Trading name of business", "first_name": "John", "last_name": "Contractor", "full_legal_name": "John Contractor", "email": "john.contractor@example.com", "date_of_birth": "1990-01-01", "business_detail": { "country": "AU", "number": "ABN123456789", "business_type": "Company" } }'Response
{ "data": { "message": "Employee file successfully created.", "contractor_id": "60b3a532-8c18-4ed6-bd01-2aa3b29ad24b" }}This endpoint updates the personal details for a specific employee. Personal detail fields can be partially updated - fields excluded from the request body will not be affected.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/personal_detailsPath Parameters
The ID of the organisation
The ID of the employee to update
Request Body
Employee's title.
Employee's first name
Employee's middle name
Employee's last name
Preferred name or nickname
Employee's gender.
Employee's preferred pronouns.
Address information object
Employee's nationality
Date of birth in YYYY-MM-DD format
Marital status.
Personal email address
Personal mobile phone number
Home phone number
Whether to display mobile number in staff directory
Complete legal name
Employee biography or description
Response Body
Returns the updated employee object with all employment details. The response includes the complete employee record with updated employment information.
Unique identifier for the object.
The account name of employee
The title of employee
The role of employee
The first name of employee
The last name of employee
The middle name of employee
The address of employee
The avatar url of employee
The preferred name of the employee
The job title of the employee
The gender of the employee
The country of the employee
The date of birth of employee
The martial status of employee
The personal email of employee
The personal mobile number of employee
The home phone of employee
The employing entity of employee
The code of employee
The location of employee
The company email of employee
The company mobile of employee
The company landline of employee
The start date of employee
The termination day of employee
The teams of employee
The primary cost centre of employee
The secondary cost centre of employee
The primary manager of employee
The secondary manager of employee
The external id of employee (ID of payroll system)
The status of employee
The detailed termination summary of a terminated employee, including reason, date, and actioning user
The employment type of employee. Valid types depend on the employee's region. Common values: Full-time, Part-time, Casual
Typical hours worked per day.
Work-hours roster type.
The trial or probation period type of employee. Supported values are trial_period and probation_period
The trial period length in days of employee when trial_or_probation_type is trial_period
The probation period length in months of an employee when trial_or_probation_type is probation_period
The start date of the Global Teams employee
The probation end date of the Global Teams employee
Indicates if the member is an independent contractor
Contractor trading name
Australian Business Number of the contractor
Contractor business registration details
UK–specific tax and national-insurance information
Primary email address of the employee (alias of account_email).
Employee's complete registered legal name.
Registered (legal) name of the employee, excluding preferred or known-as names.
Convenience field that concatenates first, middle and last name.
Employee-provided pronouns (e.g. she/her, they/them).
Whether the employee's mobile number is visible in the staff directory.
Identifies as Aboriginal and/or Torres Strait Islander.
The previous family name of the employee.
Short bio or "about me" text shown in company directory.
Indicates the employee has opted out of Instapay referral communications.
Country in which the employee primarily works.
Payroll engine / product the employee belongs to (e.g. KeyPay, Xero, Global Teams).
IANA time-zone identifier for the employee (e.g. Asia/Singapore).
Nationality of the employee (ISO-3166 alpha-2 code).
Residential address of the employee
Postal address of the employee
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/personal_details" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "title": "Mr", "first_name": "John", "middle_name": "Michael", "last_name": "Smith", "known_as": "Johnny", "gender": "Male", "pronouns": "He/Him", "address_attributes": { "country": "AU", "line_1": "123 Main Street", "line_2": "Apt 4B", "line_3": "Building C", "suburb": "Sydney", "city": "Sydney", "state": "NSW2", "postcode": "20002", "block_number": "1232", "unit_number": "4B2", "level_number": "22", "street_name": "Main Street", "address_type": "Residential" }, "nationality": "Australian", "date_of_birth": "1990-01-15", "marital_status": "In a Relationship", "personal_email": "example@example.com", "personal_mobile_number": "+614123456789", "home_phone": "+614123456789", "display_mobile_in_staff_directory": true, "full_legal_name": "John Michael Smith", "biography": "Experienced software engineer with 10+ years in web development." }'Response
{ "data": { "id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "account_email": "daniel@thinkei.com", "title": "Ms", "role": "owner", "first_name": "Daniel", "last_name": "Tran", "middle_name": "Tuan", "address": "Test Street 184752, Apt 8B, Sydney, NSW, 2000, AU", "avatar_url": "http://avatar.png", "known_as": "Danny", "job_title": "Grad Developer", "gender": "Female", "country": "AU", "date_of_birth": "1995-02-13T00:00:00+00:00", "marital_status": "Single", "personal_email": "abc@thinkei.com", "personal_mobile_number": "01285659993", "home_phone": "02 9123 4567", "employing_entity": "US", "code": "EMP123", "location": null, "company_email": "abc@thinkei.com", "company_mobile": "0412 345 678", "company_landline": "02 8181 1234", "start_date": "2017-03-01T00:00:00+00:00", "termination_date": null, "teams": [ { "id": "95df8139-479f-432e-b8f9-922352123e4a", "name": "Team 1" }, { "id": "95df8139-479f-432e-b8f9-112352123e4a", "name": "Team 2" } ], "primary_cost_centre": { "id": "95df8139-479f-432e-b8f9-922352d2fe4a", "name": "Employment Hero" }, "secondary_cost_centres": [], "primary_manager": { "id": "4a728243-8930-4a93-9bd8-a6843e7b59ec", "name": "Jessica" }, "secondary_manager": null, "external_id": "external_id_123", "status": "active", "termination_summary": null, "employment_type": "Full-time", "typical_work_day": "7.6", "roster": "Annual", "trial_or_probation_type": "probation_period", "trial_length": 30, "probation_length": 3, "global_teams_start_date": "01/01/2025", "global_teams_probation_end_date": "01/03/2025", "independent_contractor": false, "trading_name": "Emma Frost Consulting", "abn": "12345678901", "business_detail": { "country": "AU", "number": "BN-987654", "business_type": "sole_trader" }, "uk_tax_and_national_insurance": { "id": "uk-tni-1", "unique_taxpayer_reference": "1234567890", "national_insurance_number": "QQ123456C" }, "email": "daniel@thinkei.com", "full_legal_name": "Daniel Tuan Tran", "legal_name": "Tran Tuan Daniel", "full_name": "Daniel Tran", "pronouns": "she/her", "display_mobile_in_staff_directory": true, "aboriginal_torres_strait_islander": false, "previous_surname": "Tran", "biography": "Graduate developer passionate about clean code and football.", "instapay_referral_opted_out": false, "work_country": "AU", "payroll_type": "KeyPay", "time_zone": "Australia/Sydney", "nationality": "AU", "residential_address": { "address_type": "residential", "line_1": "Test Street 184752", "line_2": "Apt 8B", "line_3": null, "block_number": "184", "level_number": "8", "unit_number": "B", "city": "SYDNEY", "postcode": "2000", "state": "NSW", "suburb": "Barangaroo", "country": "AU", "is_residential": true, "street_name": "Test Street", "is_manually_entered": false }, "postal_address": { "address_type": "postal", "line_1": "PO Box 999", "line_2": null, "line_3": null, "block_number": null, "level_number": null, "unit_number": null, "city": "SYDNEY", "postcode": "2001", "state": "NSW", "suburb": "Barangaroo", "country": "AU", "is_residential": false, "street_name": "PO Box", "is_manually_entered": false } }}This endpoint updates the employment details for a specific employee. Employment detail fields can be partially updated - fields excluded from the request body will not be affected.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/employment_detailsPath Parameters
The ID of the organisation
The ID of the employee to update
Request Body
Employee code/identifier
Primary cost centre ID
Array of additional cost centre IDs
Primary manager ID (updated asynchronously)
Secondary manager ID (updated asynchronously)
Array of team IDs
Probation period length in months
Company email address
Company mobile number
Company landline number
Employment start date (YYYY-MM-DD format)
System access start date (YYYY-MM-DD format)
Response Body
Returns the updated employee object with all employment details. The response includes the complete employee record with updated employment information.
Note: primary_manager_id and secondary_manager_id updates are processed asynchronously via background jobs. The updated manager information will not be immediately available in the response and may take a few moments to reflect in subsequent API calls.
Unique identifier for the object.
The account name of employee
The title of employee
The role of employee
The first name of employee
The last name of employee
The middle name of employee
The address of employee
The avatar url of employee
The preferred name of the employee
The job title of the employee
The gender of the employee
The country of the employee
The date of birth of employee
The martial status of employee
The personal email of employee
The personal mobile number of employee
The home phone of employee
The employing entity of employee
The code of employee
The location of employee
The company email of employee
The company mobile of employee
The company landline of employee
The start date of employee
The termination day of employee
The teams of employee
The primary cost centre of employee
The secondary cost centre of employee
The primary manager of employee
The secondary manager of employee
The external id of employee (ID of payroll system)
The status of employee
The detailed termination summary of a terminated employee, including reason, date, and actioning user
The employment type of employee. Valid types depend on the employee's region. Common values: Full-time, Part-time, Casual
Typical hours worked per day.
Work-hours roster type.
The trial or probation period type of employee. Supported values are trial_period and probation_period
The trial period length in days of employee when trial_or_probation_type is trial_period
The probation period length in months of an employee when trial_or_probation_type is probation_period
The start date of the Global Teams employee
The probation end date of the Global Teams employee
Indicates if the member is an independent contractor
Contractor trading name
Australian Business Number of the contractor
Contractor business registration details
UK–specific tax and national-insurance information
Primary email address of the employee (alias of account_email).
Employee's complete registered legal name.
Registered (legal) name of the employee, excluding preferred or known-as names.
Convenience field that concatenates first, middle and last name.
Employee-provided pronouns (e.g. she/her, they/them).
Whether the employee's mobile number is visible in the staff directory.
Identifies as Aboriginal and/or Torres Strait Islander.
The previous family name of the employee.
Short bio or "about me" text shown in company directory.
Indicates the employee has opted out of Instapay referral communications.
Country in which the employee primarily works.
Payroll engine / product the employee belongs to (e.g. KeyPay, Xero, Global Teams).
IANA time-zone identifier for the employee (e.g. Asia/Singapore).
Nationality of the employee (ISO-3166 alpha-2 code).
Residential address of the employee
Postal address of the employee
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/employment_details" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "code": "code", "cost_centre_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "additional_cost_centre_ids": [ { "id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1" }, { "id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1" } ], "primary_manager_id": "primary_manager_id", "secondary_manager_id": "secondary_manager_id", "team_ids": [], "probation_length": 20.5, "company_email": "my.company@email.com", "company_mobile": "012345678", "company_landline": "087654321", "start_date": "2025-01-01", "system_access_date": "2025-01-02" }'Response
{ "data": { "id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "account_email": "daniel@thinkei.com", "title": "Ms", "role": "owner", "first_name": "Daniel", "last_name": "Tran", "middle_name": "Tuan", "address": "Test Street 184752, Apt 8B, Sydney, NSW, 2000, AU", "avatar_url": "http://avatar.png", "known_as": "Danny", "job_title": "Grad Developer", "gender": "Female", "country": "AU", "date_of_birth": "1995-02-13T00:00:00+00:00", "marital_status": "Single", "personal_email": "abc@thinkei.com", "personal_mobile_number": "01285659993", "home_phone": "02 9123 4567", "employing_entity": "US", "code": "EMP123", "location": null, "company_email": "abc@thinkei.com", "company_mobile": "0412 345 678", "company_landline": "02 8181 1234", "start_date": "2017-03-01T00:00:00+00:00", "termination_date": null, "teams": [ { "id": "95df8139-479f-432e-b8f9-922352123e4a", "name": "Team 1" }, { "id": "95df8139-479f-432e-b8f9-112352123e4a", "name": "Team 2" } ], "primary_cost_centre": { "id": "95df8139-479f-432e-b8f9-922352d2fe4a", "name": "Employment Hero" }, "secondary_cost_centres": [], "primary_manager": { "id": "4a728243-8930-4a93-9bd8-a6843e7b59ec", "name": "Jessica" }, "secondary_manager": null, "external_id": "external_id_123", "status": "active", "termination_summary": null, "employment_type": "Full-time", "typical_work_day": "7.6", "roster": "Annual", "trial_or_probation_type": "probation_period", "trial_length": 30, "probation_length": 3, "global_teams_start_date": "01/01/2025", "global_teams_probation_end_date": "01/03/2025", "independent_contractor": false, "trading_name": "Emma Frost Consulting", "abn": "12345678901", "business_detail": { "country": "AU", "number": "BN-987654", "business_type": "sole_trader" }, "uk_tax_and_national_insurance": { "id": "uk-tni-1", "unique_taxpayer_reference": "1234567890", "national_insurance_number": "QQ123456C" }, "email": "daniel@thinkei.com", "full_legal_name": "Daniel Tuan Tran", "legal_name": "Tran Tuan Daniel", "full_name": "Daniel Tran", "pronouns": "she/her", "display_mobile_in_staff_directory": true, "aboriginal_torres_strait_islander": false, "previous_surname": "Tran", "biography": "Graduate developer passionate about clean code and football.", "instapay_referral_opted_out": false, "work_country": "AU", "payroll_type": "KeyPay", "time_zone": "Australia/Sydney", "nationality": "AU", "residential_address": { "address_type": "residential", "line_1": "Test Street 184752", "line_2": "Apt 8B", "line_3": null, "block_number": "184", "level_number": "8", "unit_number": "B", "city": "SYDNEY", "postcode": "2000", "state": "NSW", "suburb": "Barangaroo", "country": "AU", "is_residential": true, "street_name": "Test Street", "is_manually_entered": false }, "postal_address": { "address_type": "postal", "line_1": "PO Box 999", "line_2": null, "line_3": null, "block_number": null, "level_number": null, "unit_number": null, "city": "SYDNEY", "postcode": "2001", "state": "NSW", "suburb": "Barangaroo", "country": "AU", "is_residential": false, "street_name": "PO Box", "is_manually_entered": false } }}This endpoint updates contractor-specific details for an employee who is flagged as an independent contractor (independent_contractor = true). Fields omitted from the request body will be left unchanged.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/contractor_detailsPath Parameters
The ID of the organisation
The ID of the contractor to update
Request Body
Contractor trading name. Required when provided but cannot be blank.
Australian Business Number. Must be a valid 11-digit ABN.
Business registration details
Response Body
Returns the updated contractor details merged into the full employee object.
Note: When you supply or update the abn field, the system will automatically set business_detail.country to AU. For contractors outside Australia, leave abn blank and instead update business_detail.number (plus business_detail.country) with the appropriate local business identifier.
Unique identifier for the object.
The account name of employee
The title of employee
The role of employee
The first name of employee
The last name of employee
The middle name of employee
The address of employee
The avatar url of employee
The preferred name of the employee
The job title of the employee
The gender of the employee
The country of the employee
The date of birth of employee
The martial status of employee
The personal email of employee
The personal mobile number of employee
The home phone of employee
The employing entity of employee
The code of employee
The location of employee
The company email of employee
The company mobile of employee
The company landline of employee
The start date of employee
The termination day of employee
The teams of employee
The primary cost centre of employee
The secondary cost centre of employee
The primary manager of employee
The secondary manager of employee
The external id of employee (ID of payroll system)
The status of employee
The detailed termination summary of a terminated employee, including reason, date, and actioning user
The employment type of employee. Valid types depend on the employee's region. Common values: Full-time, Part-time, Casual
Typical hours worked per day.
Work-hours roster type.
The trial or probation period type of employee. Supported values are trial_period and probation_period
The trial period length in days of employee when trial_or_probation_type is trial_period
The probation period length in months of an employee when trial_or_probation_type is probation_period
The start date of the Global Teams employee
The probation end date of the Global Teams employee
Indicates if the member is an independent contractor
Contractor trading name
Australian Business Number of the contractor
Contractor business registration details
UK–specific tax and national-insurance information
Primary email address of the employee (alias of account_email).
Employee's complete registered legal name.
Registered (legal) name of the employee, excluding preferred or known-as names.
Convenience field that concatenates first, middle and last name.
Employee-provided pronouns (e.g. she/her, they/them).
Whether the employee's mobile number is visible in the staff directory.
Identifies as Aboriginal and/or Torres Strait Islander.
The previous family name of the employee.
Short bio or "about me" text shown in company directory.
Indicates the employee has opted out of Instapay referral communications.
Country in which the employee primarily works.
Payroll engine / product the employee belongs to (e.g. KeyPay, Xero, Global Teams).
IANA time-zone identifier for the employee (e.g. Asia/Singapore).
Nationality of the employee (ISO-3166 alpha-2 code).
Residential address of the employee
Postal address of the employee
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/contractor_details" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "trading_name": "Acme Consulting Pty Ltd", "abn": "80112233445", "business_detail": { "country": "AU", "number": "ACN987654321", "business_type": "sole_trader" } }'Response
{ "data": { "id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "account_email": "daniel@thinkei.com", "title": "Ms", "role": "owner", "first_name": "Daniel", "last_name": "Tran", "middle_name": "Tuan", "address": "Test Street 184752, Apt 8B, Sydney, NSW, 2000, AU", "avatar_url": "http://avatar.png", "known_as": "Danny", "job_title": "Grad Developer", "gender": "Female", "country": "AU", "date_of_birth": "1995-02-13T00:00:00+00:00", "marital_status": "Single", "personal_email": "abc@thinkei.com", "personal_mobile_number": "01285659993", "home_phone": "02 9123 4567", "employing_entity": "US", "code": "EMP123", "location": null, "company_email": "abc@thinkei.com", "company_mobile": "0412 345 678", "company_landline": "02 8181 1234", "start_date": "2017-03-01T00:00:00+00:00", "termination_date": null, "teams": [ { "id": "95df8139-479f-432e-b8f9-922352123e4a", "name": "Team 1" }, { "id": "95df8139-479f-432e-b8f9-112352123e4a", "name": "Team 2" } ], "primary_cost_centre": { "id": "95df8139-479f-432e-b8f9-922352d2fe4a", "name": "Employment Hero" }, "secondary_cost_centres": [], "primary_manager": { "id": "4a728243-8930-4a93-9bd8-a6843e7b59ec", "name": "Jessica" }, "secondary_manager": null, "external_id": "external_id_123", "status": "active", "termination_summary": null, "employment_type": "Full-time", "typical_work_day": "7.6", "roster": "Annual", "trial_or_probation_type": "probation_period", "trial_length": 30, "probation_length": 3, "global_teams_start_date": "01/01/2025", "global_teams_probation_end_date": "01/03/2025", "independent_contractor": false, "trading_name": "Emma Frost Consulting", "abn": "12345678901", "business_detail": { "country": "AU", "number": "BN-987654", "business_type": "sole_trader" }, "uk_tax_and_national_insurance": { "id": "uk-tni-1", "unique_taxpayer_reference": "1234567890", "national_insurance_number": "QQ123456C" }, "email": "daniel@thinkei.com", "full_legal_name": "Daniel Tuan Tran", "legal_name": "Tran Tuan Daniel", "full_name": "Daniel Tran", "pronouns": "she/her", "display_mobile_in_staff_directory": true, "aboriginal_torres_strait_islander": false, "previous_surname": "Tran", "biography": "Graduate developer passionate about clean code and football.", "instapay_referral_opted_out": false, "work_country": "AU", "payroll_type": "KeyPay", "time_zone": "Australia/Sydney", "nationality": "AU", "residential_address": { "address_type": "residential", "line_1": "Test Street 184752", "line_2": "Apt 8B", "line_3": null, "block_number": "184", "level_number": "8", "unit_number": "B", "city": "SYDNEY", "postcode": "2000", "state": "NSW", "suburb": "Barangaroo", "country": "AU", "is_residential": true, "street_name": "Test Street", "is_manually_entered": false }, "postal_address": { "address_type": "postal", "line_1": "PO Box 999", "line_2": null, "line_3": null, "block_number": null, "level_number": null, "unit_number": null, "city": "SYDNEY", "postcode": "2001", "state": "NSW", "suburb": "Barangaroo", "country": "AU", "is_residential": false, "street_name": "PO Box", "is_manually_entered": false } }}This endpoints offboards (terminates) an employee.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/offboardPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve
Request Body
Termination date in DD/MM/YYYY format
Type of termination
Reason of termination. Required if termination_type is resignation or termination.
termination_type | Valid termination_reason values |
|---|---|
resignation |
|
termination |
|
Additional comments regarding the termination. Required if termination_reason is other than resignation or termination
Option for removing system access
Custom date and time for removing system access in ISO 8601 format (e.g., 2025-09-28T18:00:00.000Z). Required if remove_access_option is Remove access at a custom date
Response Body
Returns the message confirming the offboarding of the employee.
Example
curl -X PUT \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/offboard" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "termination_date": "30/09/2025", "termination_type": "resignation", "termination_reason": "career_advancement", "comment": "Moving to a new role", "remove_access_option": "Remove access at a custom date", "custom_remove_access_date_time": "2025-09-28T18:00:00.000Z" }'Response
{ "data": { "message": "Offboard successful." }}This endpoint deletes a specific employee.
Warning
This endpoint deletes an employee from the system. This is irreversible, and the employee file will also be removed. Consider using the Offboard Employee API instead to maintain the employee record and safely offboard the employee.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_idPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve
Response Body
Returns the message confirming the deletion of the employee.
Example
curl -X DELETE \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "message": "Deleted Daniel Tran successfully." }}Leave Category
This endpoint retrieves a paginated list of leave categories available within the specified organisation.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/leave_categoriesPath Parameters
The ID of the organisation to retrieve
Query Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of leave category objects and pagination information.
Unique identifier for the leave category.
The name of the leave category.
The unit type for this leave category (e.g., days, hours).
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/leave_categories" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Annual Leave", "unit_type": "days" }, { "id": "b2c3d4e5-f6g7-8901-bcde-f23456789012", "name": "Sick Leave", "unit_type": "hours" }, { "id": "c3d4e5f6-g7h8-9012-cdef-345678901234", "name": "Personal Leave", "unit_type": "days" } ], "page_index": 1, "item_per_page": 20, "total_items": 3, "total_pages": 1 }}Leave Request
This endpoint retrieves a list of all leave requests.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/leave_requestsPath Parameters
The ID of the organisation to retrieve
Query Parameters
The start date of the leave request (YYYY-MM-DD format)
The end date of the leave request (YYYY-MM-DD format)
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of up to the limit of leave requests. Each entry in the array is a separate leave request object. If there are no more leave requests, the resulting array will be empty.
Note: Hours are calculated using the employee's typical working day hours. If the leave category is configured to use days as the unit type, the platform will automatically convert the hours to days based on the employee's typical working day configuration.
Unique identifier for the object.
The start date of your employee leave request.
The end date of your employee leave request.
The total hours of leave request.
The comment of the leave request if an owner or admin has entered a notation
The status of leave request.
The leave balance amount of leave request.
The category name of leave request object. I.E "Annual Leave"
The reason of employee's leave request.
The ID of employee who requested to leave.
Array of objects specifying custom hours for specific dates
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/leave_requests" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "start_date": "2017-05-29T00:00:00+00:00", "end_date": "2017-05-29T00:00:00+00:00", "total_hours": 8, "comment": "The last working day", "status": "Approved", "leave_balance_amount": 0, "leave_category_name": "Annual Leave", "reason": "Vacation", "employee_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "hours_per_day": [ { "date": "2014-08-05", "hours": 7.6 }, { "date": "2014-08-06", "hours": 7.6 }, { "date": "2014-08-07", "hours": 7.6 }, { "date": "2014-08-08", "hours": 7.6 } ] } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}This endpoint retrieves a specific leave request.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/leave_requests/:idPath Parameters
The ID of the organisation to retrieve
The ID of the leave request to retrieve
Response Body
Note: Hours are calculated using the employee's typical working day hours. If the leave category is configured to use days as the unit type, the platform will automatically convert the hours to days based on the employee's typical working day configuration.
Unique identifier for the object.
The start date of your employee leave request.
The end date of your employee leave request.
The total hours of leave request.
The comment of the leave request if an owner or admin has entered a notation
The status of leave request.
The leave balance amount of leave request.
The category name of leave request object. I.E "Annual Leave"
The reason of employee's leave request.
The ID of employee who requested to leave.
Array of objects specifying custom hours for specific dates
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/leave_requests/:id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "start_date": "2017-05-29T00:00:00+00:00", "end_date": "2017-05-29T00:00:00+00:00", "total_hours": 8, "comment": "The last working day", "status": "Approved", "leave_balance_amount": 0, "leave_category_name": "Annual Leave", "reason": "Vacation", "employee_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "hours_per_day": [ { "date": "2014-08-05", "hours": 7.6 }, { "date": "2014-08-06", "hours": 7.6 }, { "date": "2014-08-07", "hours": 7.6 }, { "date": "2014-08-08", "hours": 7.6 } ] }}This endpoint creates a new leave request for a specific employee. The endpoint supports custom hours per day configuration and will automatically fill in missing dates with the employee's typical working day hours.
Note: Dates within the start_date and end_date range that are not explicitly defined in the hours_per_day array will automatically use the employee's full typical working day hours. Hours are calculated using the employee's typical working day hours, and if the leave category is configured to use days as the unit type, the platform will automatically convert the hours to days.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/leave_requestsPath Parameters
The ID of the organisation to create the leave request
The ID of the employee to create the leave request for
Request Body
The category id of the leave request
The start date of the leave request (YYYY-MM-DD format)
The end date of the leave request (YYYY-MM-DD format)
The comment for the leave request
Array of objects specifying custom hours for specific dates
Response Body
Returns the created leave request object with all details including the automatically calculated total hours and any auto-filled hours for dates not specified in the hours_per_day array.
Unique identifier for the object.
The start date of your employee leave request.
The end date of your employee leave request.
The total hours of leave request.
The comment of the leave request if an owner or admin has entered a notation
The status of leave request.
The leave balance amount of leave request.
The category name of leave request object. I.E "Annual Leave"
The reason of employee's leave request.
The ID of employee who requested to leave.
Array of objects specifying custom hours for specific dates
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/leave_requests" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "leave_category_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "start_date": "2025-12-25", "end_date": "2025-12-27", "comment": "Holiday vacation", "hours_per_day": [ { "date": "2025-12-25", "hours": 7.6 }, { "date": "2025-12-26", "hours": 7.6 } ] }'Response
{ "data": { "id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "start_date": "2017-05-29T00:00:00+00:00", "end_date": "2017-05-29T00:00:00+00:00", "total_hours": 8, "comment": "The last working day", "status": "Approved", "leave_balance_amount": 0, "leave_category_name": "Annual Leave", "reason": "Vacation", "employee_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "hours_per_day": [ { "date": "2014-08-05", "hours": 7.6 }, { "date": "2014-08-06", "hours": 7.6 }, { "date": "2014-08-07", "hours": 7.6 }, { "date": "2014-08-08", "hours": 7.6 } ] }}Timesheet Entry
This endpoint retrieves a list of all timesheet entries for a specific employee.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/timesheet_entriesPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve, we also support the wildcard collection id "-" for searching for all timesheet across all employees
Query Parameters
The start date of time range for date field (dd/mm/yyyy)
The end date of time range for date field (dd/mm/yyyy)
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of up to the limit of timesheets. Each entry in the array is a separate timesheet object. If there are no more timesheets, the resulting array will be empty.
Unique identifier for the object.
The date of your employee timesheet object.
The start time of timesheet.
The end time of timesheet.
The status of timesheet
The number of productive working hours for this timesheet record. This represents actual work time and excludes any break periods.
The total number of break hours for this timesheet record
Array of break objects containing start_time and end_time for each break
The reason of timesheet.
The comment of timesheet
The time of timesheet (milliseconds), if start_time is empty or end_time is empty then this field will have the value
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/timesheet_entries" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "16a62c0d-bb91-45e4-ad47-a325117c87eb", "date": "2018-12-17T00:00:00+00:00", "start_time": "2018-12-17T01:00:00+11:00", "end_time": "2018-12-17T07:00:00+11:00", "status": "pending", "units": 6, "break_units": 0.5, "breaks": [ { "start_time": "2018-12-17T03:00:00+11:00", "end_time": "2018-12-17T03:30:00+11:00" } ], "reason": null, "comment": "Working hard", "time": 21600 } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}This endpoint allows you to create multiple timesheet entries for different employees in a single request. The endpoint supports bulk creation with validation and will return both successful creations and any failures.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/timesheet_entriesPath Parameters
The ID of the organisation
Request Body
Array of timesheet entries to create (maximum 10 per request)
The ID of the employee for this timesheet entry
The date of the timesheet entry in YYYY-MM-DD format
The start time in ISO 8601 format
The end time in ISO 8601 format
Optional comment for the timesheet entry
Optional array of break periods consisting of start_time and end_time
Notes
- Maximum 10 timesheet entries per request
- Start time and end time must be on the same date as the timesheet date
- Break times must be within the timesheet start and end times
- Breaks cannot overlap with each other
- Timesheet entries cannot overlap with existing entries for the same employee
- All employees must exist in the organisation
Response Body
The endpoint returns a 201 status code even when some entries fail, allowing for partial success scenarios.
Unique identifier for the object.
The date of your employee timesheet object.
The start time of timesheet.
The end time of timesheet.
The status of timesheet
The number of productive working hours for this timesheet record. This represents actual work time and excludes any break periods.
The total number of break hours for this timesheet record
Array of break objects containing start_time and end_time for each break
The reason of timesheet.
The comment of timesheet
The time of timesheet (milliseconds), if start_time is empty or end_time is empty then this field will have the value
Summary of the timesheet entries creation
Array of failed timesheet entries with error details
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/timesheet_entries" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "timesheets": [ { "employee_id": "001c20e3-c752-4a46-81a1-a5e476e42d06", "date": "2024-01-15", "start_time": "2024-01-15T09:00:00+11:00", "end_time": "2024-01-15T17:00:00+11:00", "comment": "Regular work day", "breaks": [ { "start_time": "2024-01-15T12:00:00+11:00", "end_time": "2024-01-15T13:00:00+11:00" } ] } ] }'Response
{ "data": { "items": [ { "id": "16a62c0d-bb91-45e4-ad47-a325117c87eb", "date": "2018-12-17T00:00:00+00:00", "start_time": "2018-12-17T01:00:00+11:00", "end_time": "2018-12-17T07:00:00+11:00", "status": "pending", "units": 6, "break_units": 0.5, "breaks": [ { "start_time": "2018-12-17T03:00:00+11:00", "end_time": "2018-12-17T03:30:00+11:00" } ], "reason": null, "comment": "Working hard", "time": 21600 } ], "summary": { "total_created": 1, "total_failed": 0 }, "errors": [] }}Employment History
This endpoint retrieves a list of the complete employment history for a specific employee.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/employment_historiesPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve
Query Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of up to the limit of employment history records. Each entry in the array is a separate employment history object. If there is no more employment history, the resulting array will be empty.
Unique identifier for the object.
The title of employee
The start date of employment history
The end date of employment history
The employment type of employee. Valid types depend on the employee's region. Common values: Full-time, Part-time, Casual
The contract type of employee
The industry standard job title
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/employment_histories" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "bf9c12e1-b40b-4fa9-abcb-d824e5cb3654", "title": "Grad Developer", "start_date": "2025-03-01T00:00:00+00:00", "end_date": "2026-08-09T00:00:00+00:00", "employment_type": "Full-time", "contract_type": "Permanent", "industry_standard_job_title": "Software Engineer" } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}Emergency Contact
This endpoint retrieves a list of all emergency contacts for a specific employee.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/emergency_contactsPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve
Query Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of up to the limit of emergency contacts. Each entry in the array is a separate emergency contact object. If there are no more emergency contacts, the resulting array will be empty.
Unique identifier for the object.
The name of contactor
The phone number of contactor in daytime
The phone number of contactor after working hours
the mobile number of contactor after working hours
The relationship between contactor and the employee
The type of contactor
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/emergency_contacts" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": 110762, "contact_name": "Daniel Levi", "daytime_contact_number": "02222222222", "after_hours_no": "02222222222", "after_mobile_no": "02222222222", "relationship": "wife", "contact_type": "primary" } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}Team
Returns an array of all teams. Every teams must be managed by one of your managed organisation.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/teamsPath Parameters
The ID of organisation which the all teams belong to
Query Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of up to the limit of teams. Each entry in the array is a separate team object. If there are no more teams belonging to your organisation, the resulting array will be empty.
Unique identifier for the object.
The name of the team to retrieve
The status of your team
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/teams" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "143ed07a-e7d1-4c19-ade6-b0ffe9123d19", "name": "Customer Success", "status": "active" }, { "id": "36bd330e-3a6b-4539-8c86-a414fc3b485e", "name": "Engineering", "status": "active" }, { "id": "7a040b66-9bd7-47d4-b6e4-c68ed0931876", "name": "Finance", "status": "active" } ], "page_index": 1, "item_per_page": 20, "total_items": 3, "total_pages": 1 }}Returns an array of employees associated to a specific team. Employees must be managed by your managed organisation.
Similar to Get Employees response.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/teams/:team_id/employeesPath Parameters
The ID of the organisation to get employees
The ID of the team to get employees
Query Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an item array of up to limit employees. Each entry in the array is a separate employee object. If there are no more employees, the resulting array will be empty.
Unique identifier for the object.
The account name of employee
The title of employee
The role of employee
The first name of employee
The last name of employee
The middle name of employee
The address of employee
The avatar url of employee
The preferred name of the employee
The job title of the employee
The gender of the employee
The country of the employee
The date of birth of employee
The martial status of employee
The personal email of employee
The personal mobile number of employee
The home phone of employee
The employing entity of employee
The code of employee
The location of employee
The company email of employee
The company mobile of employee
The company landline of employee
The start date of employee
The termination day of employee
The teams of employee
The primary cost centre of employee
The secondary cost centre of employee
The primary manager of employee
The secondary manager of employee
The external id of employee (ID of payroll system)
The status of employee
The detailed termination summary of a terminated employee, including reason, date, and actioning user
The employment type of employee. Valid types depend on the employee's region. Common values: Full-time, Part-time, Casual
Typical hours worked per day.
Work-hours roster type.
The trial or probation period type of employee. Supported values are trial_period and probation_period
The trial period length in days of employee when trial_or_probation_type is trial_period
The probation period length in months of an employee when trial_or_probation_type is probation_period
The start date of the Global Teams employee
The probation end date of the Global Teams employee
Indicates if the member is an independent contractor
Contractor trading name
Australian Business Number of the contractor
Contractor business registration details
UK–specific tax and national-insurance information
Primary email address of the employee (alias of account_email).
Employee's complete registered legal name.
Registered (legal) name of the employee, excluding preferred or known-as names.
Convenience field that concatenates first, middle and last name.
Employee-provided pronouns (e.g. she/her, they/them).
Whether the employee's mobile number is visible in the staff directory.
Identifies as Aboriginal and/or Torres Strait Islander.
The previous family name of the employee.
Short bio or "about me" text shown in company directory.
Indicates the employee has opted out of Instapay referral communications.
Country in which the employee primarily works.
Payroll engine / product the employee belongs to (e.g. KeyPay, Xero, Global Teams).
IANA time-zone identifier for the employee (e.g. Asia/Singapore).
Nationality of the employee (ISO-3166 alpha-2 code).
Residential address of the employee
Postal address of the employee
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/teams/:team_id/employees" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "account_email": "daniel@thinkei.com", "title": "Ms", "role": "owner", "first_name": "Daniel", "last_name": "Tran", "middle_name": "Tuan", "address": "Test Street 184752, Apt 8B, Sydney, NSW, 2000, AU", "avatar_url": "http://avatar.png", "known_as": "Danny", "job_title": "Grad Developer", "gender": "Female", "country": "AU", "date_of_birth": "1995-02-13T00:00:00+00:00", "marital_status": "Single", "personal_email": "abc@thinkei.com", "personal_mobile_number": "01285659993", "home_phone": "02 9123 4567", "employing_entity": "US", "code": "EMP123", "location": null, "company_email": "abc@thinkei.com", "company_mobile": "0412 345 678", "company_landline": "02 8181 1234", "start_date": "2017-03-01T00:00:00+00:00", "termination_date": null, "teams": [ { "id": "95df8139-479f-432e-b8f9-922352123e4a", "name": "Team 1" }, { "id": "95df8139-479f-432e-b8f9-112352123e4a", "name": "Team 2" } ], "primary_cost_centre": { "id": "95df8139-479f-432e-b8f9-922352d2fe4a", "name": "Employment Hero" }, "secondary_cost_centres": [], "primary_manager": { "id": "4a728243-8930-4a93-9bd8-a6843e7b59ec", "name": "Jessica" }, "secondary_manager": null, "external_id": "external_id_123", "status": "active", "termination_summary": null, "employment_type": "Full-time", "typical_work_day": "7.6", "roster": "Annual", "trial_or_probation_type": "probation_period", "trial_length": 30, "probation_length": 3, "global_teams_start_date": "01/01/2025", "global_teams_probation_end_date": "01/03/2025", "independent_contractor": false, "trading_name": "Emma Frost Consulting", "abn": "12345678901", "business_detail": { "country": "AU", "number": "BN-987654", "business_type": "sole_trader" }, "uk_tax_and_national_insurance": { "id": "uk-tni-1", "unique_taxpayer_reference": "1234567890", "national_insurance_number": "QQ123456C" }, "email": "daniel@thinkei.com", "full_legal_name": "Daniel Tuan Tran", "legal_name": "Tran Tuan Daniel", "full_name": "Daniel Tran", "pronouns": "she/her", "display_mobile_in_staff_directory": true, "aboriginal_torres_strait_islander": false, "previous_surname": "Tran", "biography": "Graduate developer passionate about clean code and football.", "instapay_referral_opted_out": false, "work_country": "AU", "payroll_type": "KeyPay", "time_zone": "Australia/Sydney", "nationality": "AU", "residential_address": { "address_type": "residential", "line_1": "Test Street 184752", "line_2": "Apt 8B", "line_3": null, "block_number": "184", "level_number": "8", "unit_number": "B", "city": "SYDNEY", "postcode": "2000", "state": "NSW", "suburb": "Barangaroo", "country": "AU", "is_residential": true, "street_name": "Test Street", "is_manually_entered": false }, "postal_address": { "address_type": "postal", "line_1": "PO Box 999", "line_2": null, "line_3": null, "block_number": null, "level_number": null, "unit_number": null, "city": "SYDNEY", "postcode": "2001", "state": "NSW", "suburb": "Barangaroo", "country": "AU", "is_residential": false, "street_name": "PO Box", "is_manually_entered": false } } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}Bank Account
This endpoint retrieves an employee's bank accounts. The response object is region-aware. Fields not applicable to the employee's payroll region will not be returned.
https:/api.employmenthero.com/api/v2/organisations/:organisation_id/employees/:employee_id/bank_accountsPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve
Query Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of up to the limit of bank account records. Each entry in the array is a separate bank account object. If there is no more bank accounts, the resulting array will be empty.
The currency code for the bank account (e.g., "SGD").
The name of the bank account.
The type of bank account.
The account number of the bank account.
The BSB (Bank State Branch) number for Australian bank accounts.
The amount associated with the bank account.
Indicates whether this is the primary bank account.
The lock level for the bank account (e.g., employee).
External identifier for the bank account.
Text that appears on bank statements.
The roll number for the bank account.
The bank branch information.
The name of the bank.
The bank code.
The SWIFT/BIC code for the bank.
The address of the bank.
The name of the bank branch.
The branch code.
The institute number for the bank.
The payment method associated with the account.
The transit number for the bank account.
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v2/organisations/:organisation_id/employees/:employee_id/bank_accounts" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "currency": "AUD", "account_name": "account_name", "account_type": "account_type", "account_number": "account_number", "bsb": "cbs", "amount": "1000", "primary_account": "primary_account", "lock_level": "employee", "external_id": "external_id", "statement_text": "statement text", "roll_number": "roll_number", "bank_branch": "bank_branch", "bank_name": "bank_name", "bank_code": "bank_code", "bank_swift_bic": "bank_swift_bic", "bank_address": "bank_address", "branch_name": "branch_name", "branch_code": "branch_code", "institute_number": "institute_number", "payment_method": "payment_method", "transit_number": "transit_number" } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}Policy
This endpoint retrieves a list of all policies for a specific organisation.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/policiesPath Parameters
The ID of the organisation to retrieve
Query Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of up to the limit of policy records. Each entry in the array is a separate policy object. If there is no more policies, the resulting array will be empty.
The policy id
The name of policy
Determine policy is mandatory or not
Time at which the policy was created
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/policies" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "1d25a390-7b0e-0135-0209-061f87a4b1b6", "name": "Wonderful Company - Full-Disk Encryption Policy", "induction": true, "created_at": "2017-09-14T10:03:51+10:00" }, { "id": "91216a90-f3cb-0133-ec72-4a8f8c38fb42", "name": "Wonderful Company - Working From Home Agreement", "induction": false, "created_at": "2016-05-04T12:12:25+10:00" } ], "page_index": 1, "item_per_page": 20, "total_items": 2, "total_pages": 1 }}Certification
This endpoint retrieves a list of all certification of a specific organisation.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/certificationsPath Parameters
The ID of the organisation to retrieve
Query Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of up to the limit of certifications. Each entry in the array is a separate certification object. If there are no more certifications, the resulting array will be empty.
The certification id
The name of certification
The type of certification
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/certifications" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "6538a2bb-2b34-4437-9a00-92af3dab5b59", "name": "Full-disk encryption", "type": "check" }, { "id": "3128a2bb-2b34-4437-9a00-92af3dab5b59", "name": "System Training", "type": "training" }, { "id": "s562a2bb-2b34-4437-9a00-92af3dab5b59", "name": "Staff training", "type": "training" } ], "page_index": 1, "item_per_page": 20, "total_items": 3, "total_pages": 1 }}This endpoint retrieves a specific certification.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/certifications/:idPath Parameters
The ID of the organisation to retrieve
The certification id
Response Body
The certification id
The name of certification
The type of certification
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/certifications/:id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "id": "6538a2bb-2b34-4437-9a00-92af3dab5b59", "name": "Full-disk encryption", "type": "check" }}Employee Certification Detail
This endpoint retrieves a list of all certifications assigned to a specific employee.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/certificationsPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve
Query Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an item array of up to limit employee certifications. Each entry in the array is a separate employee certification object. If there are no more employee certification, the resulting array will be empty.
The employee certification id
The certification name of employee certification
The certification id of employee certification
The certification type of employee certification
The expiry date of employee certification
The completion date of employee certification
The certification driver problem of employee certification
The certification driver details of employee certification
The status of certification
The certification reason of employee certification
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/certifications" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "3128a2bb-2b34-4437-9a00-92af3dab5b59", "name": "Full-disk encryption", "certification_id": "6538a2bb-2b34-4437-9a00-92af3dab5b33", "type": "Check", "expiry_date": "2021-01-04T00:00:00+00:00", "completion_date": "2020-01-04T00:00:00+00:00", "driver_problem": false, "driver_details": "", "status": "Outstanding", "reason": "" } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}Document
Returns an array of all documents associated with a specific employee. The documents are returned based on the requesting user's access permissions.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/documentsPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve documents for
Query Parameters
Search query to filter documents by title or filename
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of document objects. Each document object includes metadata about the uploaded file, access permissions, and associated tags. The response includes pagination information for large result sets.
Unique identifier for the document.
The filename of the document.
The display title of the document.
The URL to access the document file.
The ID of the employee this document belongs to.
The date and time when the document was uploaded.
The date and time when the document was last modified.
Array of access permission levels.
Array of tags associated with the document.
Whether the document is restricted to admin access only.
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/documents" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "name": "employment_contract.pdf", "title": "Employment Contract", "url": "https://api.employmenthero.com/documents/0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "member_id": "4a728243-8930-4a93-9bd8-a6843e7b59ec", "created_at": "2024-01-15T10:30:00+00:00", "updated_at": "2024-01-15T10:30:00+00:00", "access_permissions": [ "employee", "direct_managers", "payroll" ], "tag_list": [ "contract", "employment" ], "is_admin_only": false } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}This endpoint uploads a document for a specific employee. The document file is uploaded as a multipart form data request.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/documentsPath Parameters
The ID of the organisation
The ID of the employee to upload the document for
Request Body
The document file to upload
Document name (defaults to filename if not provided)
Array of tags for the document. Can be provided as comma-separated string or array
Array of access permission levels. Can be provided as comma-separated string or array
Supported File Types
| File Type | Extensions | Description |
|---|---|---|
.pdf | Portable Document Format files | |
| Microsoft Word | .doc, .docx | Microsoft Word documents |
| Microsoft Excel | .xls, .xlsx | Microsoft Excel spreadsheets |
| Microsoft PowerPoint | .ppt, .pptx | Microsoft PowerPoint presentations |
| Rich Text Format | .rtf | Rich Text Format documents |
| OpenDocument Text | .odt | OpenDocument Text files |
| Plain Text | .txt | Plain text files |
| CSV | .csv | Comma-separated values files |
| YAML | .yaml, .yml | YAML configuration files |
| JSON | .json | JavaScript Object Notation files |
| JPEG Images | .jpg, .jpeg | JPEG image files |
| PNG Images | .png | Portable Network Graphics images |
| GIF Images | .gif | Graphics Interchange Format images |
| BMP Images | .bmp | Bitmap image files |
| TIFF Images | .tiff | Tagged Image File Format images |
| WebP Images | .webp | WebP image format |
| HEIC Images | .heic | High Efficiency Image Container |
| Photoshop | .psd | Adobe Photoshop files |
| ZIP Archives | .zip | ZIP compressed archives |
| RAR Archives | .rar | RAR compressed archives |
.eml | Email message files | |
| Video | .webm, .wmv, .asf | Video files in various formats |
Response Body
Returns the created document object with all document details.
Note: When you provide a name parameter with a different file extension than the actual uploaded file, the system will use the actual file's extension for the final document name. For example, if you upload a PDF file but specify name as "contract.txt", the final document will be named "contract.pdf".
Important: If multiple files are uploaded in a single request, only the latest file will be attached to the document. To upload multiple documents, make separate API calls for each file.
Unique identifier for the document.
The filename of the document.
The display title of the document.
The URL to access the document file.
The ID of the employee this document belongs to.
The date and time when the document was uploaded.
The date and time when the document was last modified.
Array of access permission levels.
Array of tags associated with the document.
Whether the document is restricted to admin access only.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/documents" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -F "file=@/path/to/document.pdf" \ -F "name=Employment Contract" \ -F "tags=contract,employment" \ -F "access_permissions=employee,direct_managers"Response
{ "data": { "id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "name": "employment_contract.pdf", "title": "Employment Contract", "url": "https://api.employmenthero.com/documents/0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "member_id": "4a728243-8930-4a93-9bd8-a6843e7b59ec", "created_at": "2024-01-15T10:30:00+00:00", "updated_at": "2024-01-15T10:30:00+00:00", "access_permissions": [ "employee", "direct_managers", "payroll" ], "tag_list": [ "contract", "employment" ], "is_admin_only": false }}Payslip
This endpoint retrieves a list of all payslips for a specific employee.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/payslipsPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve
Query Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of up to the limit of payslip records. Each entry in the array is a separate payslip object. If there is no more payslips, the resulting array will be empty.
Unique identifier for the object.
The employee first name.
The employee last name.
The total amount of deductions for the period.
The net pay for the period.
The super contribution for the period.
The total wage for the period.
The total amount of expense reimbursements for the pay period.
The total tax for the period.
The full name of the employee.
Address line 1 of the employee.
Address line 2 of the employee.
The employee suburb.
The employee postcode.
The employee address state.
The payslip note.
The total amount of post tax deductions for the period.
The total amount of pre tax deductions for the period.
The name of the business.
The address of the business.
The business number.
The employee's base rate.
The employee's hourly rate.
The start date of the pay period.
The end date of the pay period.
The unit of pay for the base rate.
The employee's employment type.
The type of payroll.
The payment date.
External identifier of the payslip.
The ISO-8601 timestamp the payslip was created.
The ISO-8601 timestamp the payslip was last updated.
Identifier of the pay run this payslip belongs to.
Total hours worked in the period.
Earnings that are subject to tax.
ISO currency code.
ISO country code of the payslip.
URL to review the payslip online.
Student Financial Supplement Scheme amount.
Year-to-date SFSS amount.
Higher Education Loan Program amount for the period.
Year-to-date HELP amount.
Year-to-date gross earnings.
Year-to-date net earnings.
Year-to-date PAYG tax.
Year-to-date super contribution.
Year-to-date taxable earnings.
Year-to-date pre-tax deductions.
Year-to-date post-tax deductions.
URL to the PDF version of the payslip.
Base pay rate captured from KeyPay.
Total pay for the period.
Year-to-date total deductions.
Year-to-date tax amount.
Summary of key earnings & deductions.
Mapping of display labels (key) to the underlying response fields (value) used to localise field names per region/provider. Example: { "paye": "payg" } will show the PAYG tax value under the label PAYE for NZ users.
Gross earnings YTD by pay category.
Detailed earnings lines for the period.
Bank account payment breakdowns.
Super contribution details.
Leave taken during the period.
Leave balances displayed on the payslip.
Accrued leave balances displayed.
Deductions applied this period.
PAYG adjustments.
Super adjustments.
Reimbursements recorded.
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/payslips" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "e27387ba-2105-4d12-be95-a7e74823f70f", "first_name": "Daniel", "last_name": "Nguyen", "total_deduction": 1280.5, "net_pay": 2520.15, "super": 301.15, "wages": 3346.15, "reimbursements": 1280.5, "tax": 826, "name": "Alex Kopczynski", "address_line1": "4 Sava", "address_line2": null, "suburb": "123 sydney", "postcode": "0880", "address_state": "NT", "note": null, "post_tax_deduction": 0, "pre_tax_deduction": 0, "business_name": "One Disease Limited", "business_address": "Australia", "business_abn": "57162909284", "base_rate": 87000, "hourly_rate": 0, "pay_period_starting": "2012-06-27T00:00:00+00:00", "pay_period_ending": "2012-07-10T00:00:00+00:00", "base_rate_unit": "Annually", "employment_type": "Annually", "payroll_type": null, "payment_date": "2012-07-11T00:00:00+10:00", "external_id": "e27387ba-2105-4d12-be95-a7e74823f70f", "created_at": "2012-07-11T00:00:00+10:00", "updated_at": "2012-07-11T00:00:00+10:00", "payrun_id": "3cc35ef4-aaaa-4114-bfb2-0962691fd0ed", "total_hours": 160, "taxable_earnings": 3346.15, "currency": "AUD", "country_code": "AU", "review_url": "https://openapi.employmenthero.com/payslips/123456", "sfss_amount": 0, "ytd_sfss": 0, "help_amount": 0, "ytd_help": 0, "ytd_gross": 3346.15, "ytd_net": 2520.15, "ytd_payg": 826, "ytd_super": 301.15, "ytd_taxable_earnings": 3346.15, "ytd_pre_tax_deduction": 0, "ytd_post_tax_deduction": 0, "pdf_url": "https://cdn.employmenthero.com/payslips/e27387ba.pdf", "keypay_base_pay_rate": 87000, "total_pay": 3346.15, "ytd_deductions": 1280.5, "ytd_tax": 826, "summary": { "total_hours": 160, "pay_rate": 87000, "pay_rate_unit": "Annually", "gross_earning": 3346.15, "payg": 826, "help_amount": 0, "super_contribution": 301.15, "net_pay": 2520.15 }, "visible_fields": { "payg": "payg", "super_contribution": "super_contribution", "help_amount": "help_amount" }, "gross_ytds": [ { "pay_category_name": "Ordinary - Salaried", "amount": 3346.15, "created_at": "2012-07-11T00:00:00+10:00", "updated_at": "2012-07-11T00:00:00+10:00" } ], "earnings_lines": [ { "pay_category_name": "Ordinary - Salaried", "name": "Ordinary Pay", "notes": "27-10/07/2012 (10 days)", "number_of_units": 80, "rate_per_unit": 41, "gross_earnings": 3346.15, "super_contribution": 301.15, "taxable_earnings": 3346.15, "is_fixed": false, "is_tax_exempt": false } ], "bank_payments": [ { "account_name": "D N Nguyen", "account_number": "12345678", "amount": 2520.15, "bsb": "062000" } ], "superannuation_lines": [ { "contribution_type": "Employer", "payment_date_for_this_period": "2012-07-11T00:00:00+10:00", "fund_name": "REST Super", "member_number": "123456", "amount": 301.15 } ], "taken_leaves": [ { "leave_category_name": "Annual Leave", "amount": 8, "notes": null, "unit_type": "Hours" } ], "displayed_leave_balances": [ { "leave_category_name": "Annual Leave", "amount": 20, "unit_type": "Hours" } ], "displayed_accrued_leaves": [ { "leave_category_name": "Annual Leave", "amount": 20, "unit_type": "Hours" } ], "deductions": [ { "name": "Union Fee", "amount": 20, "is_tax_exempt": false } ], "payg_adjustments": [ { "name": "Manual PAYG Adjustment", "amount": -50, "is_tax_exempt": false } ], "super_adjustments": [ { "name": "Additional Super", "amount": 100 } ], "reimbursement_lines": [ { "description": "Travel expenses", "amount": 150 } ] } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}This endpoint retrieves a particular payslip for a specific employee.
Can be used in tandem with the Generate Payslip PDF API to retrieve the pdf_url after PDF generation.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/payslips/:payslip_idPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve
The ID of the payslip to retrieve
Response Body
A hash with a data property that contains the payslip. If there are no payslips, the response will be a 404.
Unique identifier for the object.
The employee first name.
The employee last name.
The total amount of deductions for the period.
The net pay for the period.
The super contribution for the period.
The total wage for the period.
The total amount of expense reimbursements for the pay period.
The total tax for the period.
The full name of the employee.
Address line 1 of the employee.
Address line 2 of the employee.
The employee suburb.
The employee postcode.
The employee address state.
The payslip note.
The total amount of post tax deductions for the period.
The total amount of pre tax deductions for the period.
The name of the business.
The address of the business.
The business number.
The employee's base rate.
The employee's hourly rate.
The start date of the pay period.
The end date of the pay period.
The unit of pay for the base rate.
The employee's employment type.
The type of payroll.
The payment date.
External identifier of the payslip.
The ISO-8601 timestamp the payslip was created.
The ISO-8601 timestamp the payslip was last updated.
Identifier of the pay run this payslip belongs to.
Total hours worked in the period.
Earnings that are subject to tax.
ISO currency code.
ISO country code of the payslip.
URL to review the payslip online.
Student Financial Supplement Scheme amount.
Year-to-date SFSS amount.
Higher Education Loan Program amount for the period.
Year-to-date HELP amount.
Year-to-date gross earnings.
Year-to-date net earnings.
Year-to-date PAYG tax.
Year-to-date super contribution.
Year-to-date taxable earnings.
Year-to-date pre-tax deductions.
Year-to-date post-tax deductions.
URL to the PDF version of the payslip.
Base pay rate captured from KeyPay.
Total pay for the period.
Year-to-date total deductions.
Year-to-date tax amount.
Summary of key earnings & deductions.
Mapping of display labels (key) to the underlying response fields (value) used to localise field names per region/provider. Example: { "paye": "payg" } will show the PAYG tax value under the label PAYE for NZ users.
Gross earnings YTD by pay category.
Detailed earnings lines for the period.
Bank account payment breakdowns.
Super contribution details.
Leave taken during the period.
Leave balances displayed on the payslip.
Accrued leave balances displayed.
Deductions applied this period.
PAYG adjustments.
Super adjustments.
Reimbursements recorded.
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/payslips/:payslip_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "id": "e27387ba-2105-4d12-be95-a7e74823f70f", "first_name": "Daniel", "last_name": "Nguyen", "total_deduction": 1280.5, "net_pay": 2520.15, "super": 301.15, "wages": 3346.15, "reimbursements": 1280.5, "tax": 826, "name": "Alex Kopczynski", "address_line1": "4 Sava", "address_line2": null, "suburb": "123 sydney", "postcode": "0880", "address_state": "NT", "note": null, "post_tax_deduction": 0, "pre_tax_deduction": 0, "business_name": "One Disease Limited", "business_address": "Australia", "business_abn": "57162909284", "base_rate": 87000, "hourly_rate": 0, "pay_period_starting": "2012-06-27T00:00:00+00:00", "pay_period_ending": "2012-07-10T00:00:00+00:00", "base_rate_unit": "Annually", "employment_type": "Annually", "payroll_type": null, "payment_date": "2012-07-11T00:00:00+10:00", "external_id": "e27387ba-2105-4d12-be95-a7e74823f70f", "created_at": "2012-07-11T00:00:00+10:00", "updated_at": "2012-07-11T00:00:00+10:00", "payrun_id": "3cc35ef4-aaaa-4114-bfb2-0962691fd0ed", "total_hours": 160, "taxable_earnings": 3346.15, "currency": "AUD", "country_code": "AU", "review_url": "https://openapi.employmenthero.com/payslips/123456", "sfss_amount": 0, "ytd_sfss": 0, "help_amount": 0, "ytd_help": 0, "ytd_gross": 3346.15, "ytd_net": 2520.15, "ytd_payg": 826, "ytd_super": 301.15, "ytd_taxable_earnings": 3346.15, "ytd_pre_tax_deduction": 0, "ytd_post_tax_deduction": 0, "pdf_url": "https://cdn.employmenthero.com/payslips/e27387ba.pdf", "keypay_base_pay_rate": 87000, "total_pay": 3346.15, "ytd_deductions": 1280.5, "ytd_tax": 826, "summary": { "total_hours": 160, "pay_rate": 87000, "pay_rate_unit": "Annually", "gross_earning": 3346.15, "payg": 826, "help_amount": 0, "super_contribution": 301.15, "net_pay": 2520.15 }, "visible_fields": { "payg": "payg", "super_contribution": "super_contribution", "help_amount": "help_amount" }, "gross_ytds": [ { "pay_category_name": "Ordinary - Salaried", "amount": 3346.15, "created_at": "2012-07-11T00:00:00+10:00", "updated_at": "2012-07-11T00:00:00+10:00" } ], "earnings_lines": [ { "pay_category_name": "Ordinary - Salaried", "name": "Ordinary Pay", "notes": "27-10/07/2012 (10 days)", "number_of_units": 80, "rate_per_unit": 41, "gross_earnings": 3346.15, "super_contribution": 301.15, "taxable_earnings": 3346.15, "is_fixed": false, "is_tax_exempt": false } ], "bank_payments": [ { "account_name": "D N Nguyen", "account_number": "12345678", "amount": 2520.15, "bsb": "062000" } ], "superannuation_lines": [ { "contribution_type": "Employer", "payment_date_for_this_period": "2012-07-11T00:00:00+10:00", "fund_name": "REST Super", "member_number": "123456", "amount": 301.15 } ], "taken_leaves": [ { "leave_category_name": "Annual Leave", "amount": 8, "notes": null, "unit_type": "Hours" } ], "displayed_leave_balances": [ { "leave_category_name": "Annual Leave", "amount": 20, "unit_type": "Hours" } ], "displayed_accrued_leaves": [ { "leave_category_name": "Annual Leave", "amount": 20, "unit_type": "Hours" } ], "deductions": [ { "name": "Union Fee", "amount": 20, "is_tax_exempt": false } ], "payg_adjustments": [ { "name": "Manual PAYG Adjustment", "amount": -50, "is_tax_exempt": false } ], "super_adjustments": [ { "name": "Additional Super", "amount": 100 } ], "reimbursement_lines": [ { "description": "Travel expenses", "amount": 150 } ] }}This endpoint enqueues a job to generate PDF for a particular payslip if not yet exists.
PDF generation should take a few seconds, after which the pdf_url will be embedded into the response of the Get Payslip API.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/payslips/:payslip_id/pdf_genPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve
The ID of the payslip to retrieve
Response Body
A hash with a data property that contains the result of the enqueuement of the pdf generation.
Indicates if the PDF generation job was successfully enqueued
Example
curl -X PUT \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/payslips/:payslip_id/pdf_gen" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "success": true }}Pay Detail
This endpoint retrieves a list of all pay details for a specific employee.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/pay_detailsPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve
Query Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of up to the limit of pay details. Each entry in the array is a separate pay details object. If there are no more pay details, the resulting array will be empty.
Unique identifier for the object.
The effect date of the pay detail.
The name of the classification.
The name of the industrial instrument.
The name of the pay rate template.
The anniversary date of the pay detail.
The salary amount.
The type of salary.
The unit of pay rate.
The name of the pay category.
The name of the leave allowance template.
The reason of changing pay detail.
The comments.
The currency.
Hours worked per week.
Days worked per week.
Full-time equivalent units.
Work hours configuration for the employee.
Indicates if the pay detail is under review.
Indicates the employee is on a zero-hour contract.
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/pay_details" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "7d9e663f-a493-4523-aea4-4f299efee8b8", "effective_from": "2020-04-21", "classification": "Day Working - Full Time", "industrial_instrument": "Wholesale Award 2010", "pay_rate_template": "Permanent Storeworker", "anniversary_date": "2020-03-25T00:00:00+00:00", "salary": 50, "salary_type": "Hour", "pay_unit": "Hourly", "pay_category": "Permanent Ordinary Hours", "leave_allowance_template": "Permanent", "change_reason": "Some reasons", "comments": "Some comments", "currency": "AUD", "hours_per_week": "38.0", "days_per_week": "5.0", "full_time_equivalent_units": "1.0", "employee_work_hours": "standard_daily", "in_review": false, "zero_hour_based": true } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}Tax Declaration
This endpoint retrieves an employee’s tax declaration. The response object is region-aware. Fields not applicable to the employee’s payroll region will not be returned.
https:/api.employmenthero.com/api/v2/organisations/:organisation_id/employees/:employee_id/tax_declarationPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve
Response Body
A hash containing a data property whose value is a Tax Declaration object.
If it does not exist, a 404 Not Found error is returned.
The employee’s first name.
The employee’s last name.
When the tax declaration record was created.
When the tax declaration record was last updated.
Tax File Number.
Reason for TFN exemption.
Is the employee an Australian resident for tax purposes?
Is the employee a foreign resident?
Claims the tax-free threshold.
Has HELP / study loan debts.
Has Financial Supplement debts.
Unix timestamp when the declaration was signed.
Payroll tax code.
Residency status for tax purposes.
Whether the employee is a Working Holiday Maker.
Lodgement status of the declaration.
Lodgement date.
Signed declaration document (Base64 / attachment ID).
Eligible for senior tax offset.
Eligible for dependent tax offset.
STP country code.
Canada Social Insurance Number (SIN).
SIN expiry date.
Tax exemption flag
New Zealand IRD number.
Unix timestamp when the declaration was signed.
Additional pay-as-you-go rate (%).
Has overseas super/pension subject to FTC.
Income applied to tested benefit.
Income band code.
Source of income is non-disclosed.
This is the primary income source.
Meets main income means test.
New Zealand tax resident.
Special tax code rate.
End date for special tax code rate.
Student loan deductions apply.
Student loan deduction rate.
End date for student loan deduction rate.
Base64 signature pad capture.
Derived source of income.
Eligible for special deduction rate (SDR)
Unix timestamp when the record was imported.
Name of the last user who updated the declaration.
Role of the last user who updated the declaration.
Human-readable income band label.
HMRC starter employee statement.
Employee starter type code.
National Insurance Number.
Tax calculation method.
Has student loan deductions.
Student loan type. (plan_1, plan_2, etc.)
Has postgraduate loan deductions.
NI contribution category.
Is the employee a company director?
NI calculation method.
Appointment start date.
Appointment end date.
Has previous employer form.
Previous employer flags.
Payroll ID.
Timestamp of last payroll sync.
Veterans NI relief qualifying end date.
Indicates whether the record is synced to payroll.
Organisation uses Xero UK payroll.
Snapshot of member personal info
Whether the employee belongs to Global Teams.
Member UUID.
External identifier for the member.
External identifier for the organisation.
Payroll-info UUID.
Member is synced to Xero UK payroll.
Member is synced to KeyPay UK payroll.
Example
curl -X GET \ "https://api.employmenthero.com/api/v2/organisations/:organisation_id/employees/:employee_id/tax_declaration" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "first_name": "Daniel", "last_name": "Alves", "tax_file_number": "000000000", "tax_file_number_exemption_reason": null, "tax_au_resident": true, "tax_foreign_resident": false, "tax_free": false, "tax_help_debt": true, "tax_financial_supplement_debt": false, "tax_signature_signed_at": 1712102400, "tax_code": "TFN", "residency_tax_purposes_status": "resident", "working_holiday_maker": false, "lodgement_status": "lodged", "lodgement_date": "2024-03-10", "tax_signature": "base64-signature==", "senior_tax_offset": false, "dependent_tax_offset": true, "stp_country": "AU", "created_at": "2024-03-02T06:41:31Z", "updated_at": "2024-03-14T02:13:22Z", "social_insurance_number": "123456789", "expiry_date": "2030-12-31", "taxes_and_exemptions": { "income_tax_exempted": false, "cpp_qpp_exempted": false, "ei_qpip_exempted": false, "workers_compensation_exempted": false }, "date_signed": 1712102400, "elected_extra_pay_rate": 4.5, "ftc_overseas_super_or_pension": false, "income_applied_to_tested_benefit": false, "income_band": 2, "ird_number": "123-456-789", "is_non_disclosed": false, "is_primary_income": true, "meets_main_income_means_test": true, "new_zealand_resident": true, "special_tax_code_rate": 10, "special_tax_code_rate_end_date": "31/12/2024", "student_loan": true, "student_loan_rate": 12, "student_loan_rate_end_date": "31/03/2025", "signature_pad": "base64-signature==", "source_of_income": "primary", "eligible_for_sdr": false, "imported_at": 1712102400, "last_updated_by_name": "Jane Smith", "last_updated_by_role": "payroll_admin", "annual_income_band": "Between $48,000 - $70,000", "employee_statement": "A", "employee_starter_type": "new_employee", "national_insurance_number": "QQ123456C", "tax_calculation_method": "cumulative", "has_student_loan": true, "student_loan_type": "plan_2", "has_post_grad_loan": false, "national_insurance_category": "A", "company_director": false, "national_insurance_calculation_method": "standard", "appointment_start_date": "2024-01-01", "appointment_end_date": null, "previous_employer": { "office_number": "123", "reference_number": "AB45678", "w1_m1": false, "tax_period_frequency": "monthly", "tax_period_number": 2, "taxable_pay": 3000, "tax_withheld": 500, "leaving_date": "2023-12-20", "continue_student_loan_deductions": true, "tax_code": "1185L", "document": { "id": "file-123", "name": "p45.pdf", "remote_url": "https://files.example.com/p45.pdf" } }, "payroll_id": "PR-0001", "has_previous_employer_form": true, "last_payroll_updated_at": "2024-03-01T10:15:00Z", "veterans_qualifying_end_date": "2026-12-31", "synced_to_payroll": true, "xero_uk_organisation": false, "member_personal_info": { "age": 30, "gender": "male", "start_date": "2024-02-01" }, "global_teams_employee": false, "member_id": "uuid-member", "member_external_id": "EXT123", "organisation_external_id": "ORG456", "payroll_info_id": "uuid-payrollInfo", "xero_uk_member": false, "keypay_uk_member": true }}Superannuation Detail
This endpoint retrieves an employee’s superannuation detail. The response object is region-aware. Fields not applicable to the employee’s payroll region will not be returned.
https:/api.employmenthero.com/api/v2/organisations/:organisation_id/employees/:employee_id/superannuation_detailPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve
Response Body
A hash containing a data property whose value is a Superannuation Details object.
If it does not exist, a 404 Not Found error is returned.
The type of superannuation scheme.
The account name for the superannuation fund.
Contact number for the superannuation fund.
The Australian Business Number (ABN) of the superannuation fund.
The name of the superannuation fund.
The member number for the superannuation account.
The product code of the superannuation fund.
Electronic service address for SMSF.
Whether this is the employer nominated fund.
The product ID number of the superannuation fund.
Unique Superannuation Identifier.
The type of fund (e.g., "Regulated").
Whether to consolidate superannuation accounts.
Whether the employee agrees to the declaration.
Timestamp when the declaration was agreed to.
Array of uploaded files related to superannuation.
Agreement to "things you should know" declaration.
Timestamp for "things you should know" declaration agreement.
Agreement to trustee declaration.
Timestamp for trustee declaration agreement.
Whether Tax File Number is included.
Agreement to employer default fund.
The superfund account name.
The product name of the superannuation fund.
Website URL of the superannuation fund.
Email address of the superannuation fund.
Bank BSB code for SMSF account.
Bank account number for SMSF account.
Address of the superannuation fund.
The assessment status for auto-enrolment (e.g., non_eligible_job_holder).
The date of the auto-enrolment assessment.
Whether the employee has opted in to the pension scheme.
The date when the employee opted in.
The date when auto-enrolment opt-out occurred.
Reference number for auto-enrolment opt-out.
Override for maximum earnings threshold.
Override for minimum earnings threshold.
Date when pension enrolment was deferred.
Override for employee contribution percentage.
Override for employer contribution percentage.
Override for salary sacrifice percentage.
Whether to process opt-out refunds.
The pension assessment option (e.g., automatic).
Whether the employee is enrolled in the pension scheme.
The postponement option for pension enrolment.
Timestamp of last payroll update.
The pension contribution plan details.
The KiwiSaver enrollment status (1-3).
The employee contribution percentage.
The employer contribution percentage.
Start date for savings suspension.
End date for savings suspension.
The date when the employee opted out of KiwiSaver.
Reason for KiwiSaver ineligibility.
Timestamp when the record was created.
Timestamp when the record was last updated.
Reason for late opt-out from KiwiSaver.
Additional explanation for late opt-out reason.
Array of deduction-related files.
Example
curl -X GET \ "https://api.employmenthero.com/api/v2/organisations/:organisation_id/employees/:employee_id/superannuation_detail" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "superannuation_scheme": "superfund", "account_name": "account name", "contact_number": "contact number", "fund_abn": "39623897732", "fund_name": "The Trustee for EH Super Fund", "member_number": "member number", "product_code": "39623897732001", "electronic_service_address": null, "employer_nominated_fund": false, "product_id_number": "39623897732001", "website": null, "fund_email": null, "account_bsb": null, "account_number": null, "usi": "39623897732001", "fund_type": "Regulated", "consolidate": null, "declaration_agree": true, "declaration_agreed_at": "2025-08-18T23:23:29+10:00", "upload_files": [], "things_you_should_know_declaration_agree": null, "things_you_should_know_declaration_agreed_at": null, "trustee_declaration_agree": null, "trustee_declaration_agreed_at": null, "including_tfn": true, "employer_default_fund_agree": null, "superfund_account_name": "account name", "product_name": null, "address": null, "assessment_status": "non_eligible_job_holder", "assessment_date": "2025-08-18", "opt_in": true, "opt_in_date": "2025-08-18", "auto_enrol_opt_out_date": "2025-08-20", "auto_enrol_opt_out_reference": "opt out reference", "override_max_earnings_threshold": 50270, "override_min_earnings_threshold": 6240, "deferral_date": null, "override_employee_contribution": 5, "override_employer_contribution": 3, "override_salary_sacrifice": 0, "process_opt_out_refunds": false, "pension_assessment_option": "automatic", "enrolled": true, "postponement_option": null, "last_payroll_updated_at": null, "pension_contribution_plan": { "enable": true, "name": "Not Sure", "pension_scheme_name": "Test Scheme 2", "calculate_on_qualifying_earnings": true, "is_auto_enrolment_scheme": true, "pension_type": "net_pay", "reporting_frequency": "w1", "max_earnings_threshold": 50270, "min_earnings_threshold": 6240, "employee_contribution": 5, "employer_contribution": 3, "salary_sacrifice": 0 }, "enrollment_status": 3, "employee_contribution": 3, "employer_contribution": 3, "savings_suspension_from_date": null, "savings_suspension_to_date": null, "opt_out_date": "17/08/2025", "ineligibility_reason": null, "created_at": "2025-08-18T23:24:08.634+10:00", "updated_at": "2025-08-18T23:24:16.865+10:00", "late_opt_out_reason": null, "late_opt_out_reason_other_explanation": null, "deduction_files": [] }}Custom Field
This endpoint retrieves a list of all custom fields for a specific organisation.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/custom_fieldsPath Parameters
The ID of the organisation to retrieve
Query Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an item array of up to limit Custom Fields. Each entry in the array is a separate Custom Field object. If there are no more Custom Fields, the resulting array will be empty.
The custom field ID
The name of the custom field
The hint of the custom field
The description of the custom field
The type of the custom field
Returns true if the custom field captured during onboarding
Returns true if the custom field is mandatory
Lists the permissions for the custom field
Lists the options for the custom field when type is either single_select or multi_select
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/custom_fields" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "f131fbe9-eb01-4802-98d9-6df7d11a6403", "name": "Work day preference", "hint": "Pick the day(s) that you would prefer to be rostered on", "description": "Tracking workday preferences to help with rostering ", "type": "multi_select", "in_onboarding": false, "required": false, "custom_field_permissions": [ { "id": "0d61bec9-8dcf-4e54-a26f-194ec376ee70", "permission": "editable", "role": "employee" }, { "id": "9659d80b-04a7-48fb-9bd9-94e76fdf09ff", "permission": "editable", "role": "manager" } ], "custom_field_options": [ { "id": "2c6fb761-f7b2-4ddc-a6b1-cfe734cfc54d", "value": "Friday" }, { "id": "8b533545-a154-4927-a210-046872eff1d2", "value": "Monday" }, { "id": "47e2c33f-42d4-4dd2-8263-daf533ecfd10", "value": "Thursday" }, { "id": "3c0677ec-7c57-46c2-a584-1a1058ffe184", "value": "Tuesday" }, { "id": "e66bd01e-e563-429f-b476-0956be7c5d04", "value": "Wednesday" } ] }, { "id": "d8fe2759-a033-49bc-92b3-921556491b2f", "name": "Tshirt Size", "hint": "Unisex sizing", "description": "Tshirt sizing for purchasing uniforms", "type": "single_select", "in_onboarding": false, "required": false, "custom_field_permissions": [ { "id": "e4251780-7e3d-4e9a-84e7-45874e9179be", "permission": "editable", "role": "employee" }, { "id": "f7f75c55-5084-4574-9786-36e0fa4cb2d3", "permission": "editable", "role": "manager" } ], "custom_field_options": [ { "id": "c55ee94c-72b7-4042-ac32-b3ab4ab38d12", "value": "Large" }, { "id": "18e33075-7233-4c0a-9fc9-6ce48e07c807", "value": "Medium" }, { "id": "ea3b8a51-3bfb-4500-bd1f-fe81620cc635", "value": "Small" } ] }, { "id": "f6f45926-5425-417b-b010-cc840858154c", "name": "Dietary Requirements", "hint": "Any food restrictions", "description": "To track dietary requirements for catering at events", "type": "free_text", "in_onboarding": false, "required": false, "custom_field_permissions": [ { "id": "b9fe040e-0ebc-4ce6-a79c-837b80795823", "permission": "editable", "role": "employee" }, { "id": "b1522654-2ac8-4593-b51c-8bf0ce2fcfe2", "permission": "editable", "role": "manager" } ] } ], "page_index": 1, "item_per_page": 20, "total_items": 3, "total_pages": 1 }}Employee Custom Field
This endpoint retrieves a list of all custom fields for a specific employee.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/custom_fieldsPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve
Query Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of up to limit employee custom fields. Each entry in the array is a separate employee custom field object. If there are no more employee custom fields, the resulting array will be empty.
The id of the custom field
The value of the custom field filled in by your employee, it is a string when type is free_text and an array when type is single_select or multi_select
The name of the custom field
The description of the custom field
The type of the custom field
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/custom_fields" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "f6f45926-5425-417b-b010-cc840858154c", "value": "No eggs", "name": "Dietary Requirements", "description": "To track dietary requirements for catering at events", "type": "free_text" }, { "id": "78869738-f730-4a92-8978-dd64e5asb0be", "value": [ { "id": "18e33075-7233-4c0a-9fc9-6ce48e07c807", "value": "Medium" } ], "name": "Tshirt Size", "description": "Tshirt sizing for purchasing uniforms", "type": "single_select" }, { "id": "f497b9a4-464b-4637-9c23-0e65bg9ae968", "value": [ { "id": "2c6fb761-f7b2-4ddc-a6b1-cfe734cfc54d", "value": "Friday" }, { "id": "3c0677ec-7c57-46c2-a584-1a1058ffe184", "value": "Tuesday" }, { "id": "e66bd01e-e563-429f-b476-0956be7c5d04", "value": "Wednesday" } ], "name": "Work day preference", "description": "Tracking workday preferences to help with rostering ", "type": "multi_select" } ], "page_index": 1, "item_per_page": 20, "total_items": 3, "total_pages": 1 }}Rostered Shift
List all the rostered shifts accessible by current user. The result is paginated
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/rostered_shiftsPath Parameters
ID of the organisation
Query Parameters
Start date of the range. Date equal to from_date will be included
End date of the range. Date equal to to_date will be included
Statuses of the rostered shifts to filter by
Location IDs of the rostered shifts to filter by
Member IDs of the rostered shifts to filter by
Whether to return only unassigned shifts
Whether to exclude shifts that overlap with from_date.
If this flag is set to true: Retrieve the shift which start time in [from_date, to_date)
Otherwise: Retrieve the shift which start time in [from_date - 1, to_date) and end time in (from_date, to_date + 1]
Current page index
11Number of items per page
20100Response Body
The rostered shifts current user can access
ID of the rostered shift
Shift start time
Shift end time
Status of the rostered shift
Notes for the rostered shift
Whether the shift is open
ID of the location where the shift is rostered
Name of the location where the shift is rostered
ID of the member rostered for the shift
Full name of the member rostered for the shift
Time after which shift swap is not allowed
Type of the shift
ID of the work type for the shift
Name of the work type for the shift
Details of the shift swap
Breaks during the shift
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/rostered_shifts" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e", "start_time": "2024-06-14T09:00:00.000Z", "end_time": "2024-06-14T17:00:00.000Z", "status": "published", "notes": "Hello world", "is_open_shift": false, "location_id": "23e55174-2c7f-468d-9d11-9c387e2c3e70", "location_name": "John Doe Hospital", "member_id": "6664453a-c118-48f1-897e-3df62d45bd84", "member_full_name": "John Doe", "shift_swap_cutoff_time": null, "type": "RosteredShift", "work_type_id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e", "work_type_name": "Full time", "shift_swap": { "id": "d71690b7-381f-4d54-8bdc-e4fd9d3e3be1", "requesting_shift_id": "4a35ccb6-8ff6-4719-b7fb-726b40467957", "receiving_shift_id": "dbab7b49-b40b-4e0d-ae69-a5fde016c5c7", "status": "awaiting_receiver", "requesting_notes": null }, "breaks": [ { "start_time": "2024-06-14T12:00:00.000Z", "end_time": "2024-06-14T13:00:00.000Z" } ] } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}Get rostered shift record using its ID
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/rostered_shifts/:idPath Parameters
ID of the organisation
ID of the rostered shift record
Response Body
The rostered shift record
ID of the rostered shift
Shift start time
Shift end time
Status of the rostered shift
Notes for the rostered shift
Whether the shift is open
ID of the location where the shift is rostered
Name of the location where the shift is rostered
ID of the member rostered for the shift
Full name of the member rostered for the shift
Time after which shift swap is not allowed
Type of the shift
ID of the work type for the shift
Name of the work type for the shift
Details of the shift swap
Breaks during the shift
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/rostered_shifts/:id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e", "start_time": "2024-06-14T09:00:00.000Z", "end_time": "2024-06-14T17:00:00.000Z", "status": "published", "notes": "Hello world", "is_open_shift": false, "location_id": "23e55174-2c7f-468d-9d11-9c387e2c3e70", "location_name": "John Doe Hospital", "member_id": "6664453a-c118-48f1-897e-3df62d45bd84", "member_full_name": "John Doe", "shift_swap_cutoff_time": null, "type": "RosteredShift", "work_type_id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e", "work_type_name": "Full time", "shift_swap": { "id": "d71690b7-381f-4d54-8bdc-e4fd9d3e3be1", "requesting_shift_id": "4a35ccb6-8ff6-4719-b7fb-726b40467957", "receiving_shift_id": "dbab7b49-b40b-4e0d-ae69-a5fde016c5c7", "status": "awaiting_receiver", "requesting_notes": null }, "breaks": [ { "start_time": "2024-06-14T12:00:00.000Z", "end_time": "2024-06-14T13:00:00.000Z" } ] }}Get the summarized rostered shift costs for a given period of time
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/rostered_shifts/costPath Parameters
ID of the organisation
Query Parameters
Start datetime of the range.
End datetime of the range. Must not be more than 30 days from the start date.
Work site IDs to filter by, applicable only for Payroll-integrated organisations
Position IDs to filter by, applicable only for Payroll-integrated organisations
Location IDs to filter by, applicable only for standalone HR organisations
Member IDs to filter by
Statuses to filter by
Response Body
The summarized rostered shift costs for a given period of time.
Costs of the rostered shifts
Open (unassigned) shifts. Not included in cost calculation
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/rostered_shifts/cost" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "costs": [ { "total_cost": 1471.15, "unit": "AUD", "shift_ids": [ "1557a4b4-78b8-464f-bc7f-bf160d8285ed", "68187eff-fc05-4731-a6fe-5866941c4fee" ] }, { "total_cost": 761.54, "unit": "GBP", "shift_ids": [ "624cd1d5-9863-41a7-a7e0-b87074d85b11", "4afb4820-6e5a-4f24-b1ec-1add7db1ec34" ] } ], "open_shifts": [ { "shift_id": "ca2685b6-ed99-4df9-8736-1f5c493294a0", "start_time": "2025-11-06T09:00:00.000Z", "end_time": "2025-11-06T17:00:00.000Z" }, { "shift_id": "def126d9-b0d8-4c0b-9da6-91fa69a1e257", "start_time": "2025-11-07T09:00:00.000Z", "end_time": "2025-11-07T17:00:00.000Z" } ] }}Get roles (standalone HR) or tags (payroll-connected)
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/rolesPath Parameters
ID of the organisation
Query Parameters
Current page index
11Number of items per page
20100Response Body
The roles available in this organisation
ID of the role
Name of the role
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/roles" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e", "name": "Full time" } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}Unavailability
Work Eligibility
This endpoint retrieves work eligibility information for a specific employee.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/work_eligibilityPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve
Response Body
A hash with a data property that contains the work eligibility object for the specified employee.
Unique identifier for the object.
Whether the employee is an oceanic resident.
Whether work eligibility has been acknowledged.
The current status of the employee's visa.
Whether the visa has been verified.
Object containing visa information including type, expiry date, and comments.
The current status of the employee's passport.
Object containing passport information including number, expiry date, and issue country.
Array of documents related to work eligibility.
Array of VEVO (Visa Entitlement Verification Online) check results.
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/work_eligibility" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "id": "be19383c-6130-451b-8222-819b7127e2fb", "is_oceanic_resident": false, "work_eligibility_acknowledged": true, "visa_status": "expired", "visa_verified": true, "default_visa_details": { "visa_type": "TZ / 417", "visa_comment": "visa comment here", "visa_expiry_date": "2025-11-13T00:00:00+00:00", "visa_start_date": "2025-11-13T00:00:00+00:00" }, "passport_status": "valid", "passport_details": { "passport_number": "548133996", "passport_expiry_date": "2027-06-09T00:00:00+00:00", "passport_issue_country": "GB" }, "documents": [ { "id": 89575, "filename": "Work eligibility document file name (eg: VISA 8547)", "url": "file_url_here", "created_at": "2025-03-29T11:36:07+11:00" } ], "vevo_checks": [ { "date": "2025-03-29T11:36:15+11:00", "status": "success", "details": { "visa_class_subclass": "TZ / 417", "visa_stream": null, "visa_applicant": "Primary", "visa_grant_date": "16 July 2025", "visa_expiry_date": "13 November 2035", "work_entitlements": "work entitlements details here", "visa_valid_at": "Thursday March 29, 2025 11:36:16 (AEDT) Canberra, Australia (GMT +1100)", "visa_condition": "visa condition here" }, "error": null, "error_message": null } ] }}Contractor Job History
This endpoint retrieves job history information for a specific employee.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/job_historiesPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve job history for
Query Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of up to the limit of job history records. Each entry in the array is a separate job history object. If there is no job history record, the resulting array will be empty. Likewise, if the target employee is not a contractor, the array will likely be empty
The title of the job position.
Description of the service or role performed.
The date when the job position started.
The date when the job position ended.
The payment frequency for the position.
The name of the bank account.
The BSB (Bank State Branch) code for the bank account.
The bank account number.
The name of the bank.
The bank code identifier.
Additional description or notes about the job position.
The roll number for the bank account.
The country code where the bank is located (e.g., "AU" for Australia).
The specific branch of the bank.
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/job_histories" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "service_description": "UX/UI content", "start_date": "2025-08-11", "end_date": "2025-08-12", "job_title": "Job history", "payment_term": "Fortnightly", "account_name": "AccountName", "bsb": "BSB", "account_number": "123123", "bank_name": "bank name", "bank_code": "bank code", "description": "description", "roll_number": "roll number", "bank_country": "AU", "bank_branch": "bank branch" } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}Employing Entity
This endpoint retrieves a paginated list of employing entities available within the specified organisation.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employing_entitiesPath Parameters
The ID of the organisation to retrieve
Query Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of employing entity objects and pagination information. Each employing entity object includes the unique identifier and name of the entity.
Unique identifier for the employing entity.
Name of the employing entity.
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employing_entities" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "3a41ab5f-fd18-4c99-b475-040a098dac89", "name": "AU" }, { "id": "b42cc588-9485-4b72-9cb2-c232d79038f9", "name": "SG" } ], "page_index": 1, "item_per_page": 20, "total_items": 2, "total_pages": 1 }}Work Location
This endpoint retrieves a paginated list of work locations available within the specified organisation.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/work_locationsPath Parameters
The ID of the organisation to retrieve
Query Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of work location objects and pagination information. Each work location object includes the unique identifier, name, and country code of the location.
Unique identifier for the work location.
Name of the work location.
Country code for the work location (ISO-3166 alpha-2 format, e.g., AU, SG).
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/work_locations" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "b992fc49-7e98-4743-b53b-51bec9cf4dc3", "name": "Sydney Office", "country": "AU" } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}Cost Centre
This endpoint retrieves a paginated list of cost centres available within the specified organisation.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/cost_centresPath Parameters
The ID of the organisation to retrieve
Query Parameters
Current page index
11Number of items per page
20100Response Body
A JSON object with a data property that contains an array of cost centre objects and pagination information. Each cost centre object includes the unique identifier and name of the cost centre.
Unique identifier for the cost centre.
Name of the cost centre.
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/cost_centres" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "7daf1397-338c-4b91-9d46-44e6cd56297a", "name": "Marketing Department" }, { "id": "b992fc49-7e98-4743-b53b-51bec9cf4dc3", "name": "Sales Department" } ], "page_index": 1, "item_per_page": 20, "total_items": 2, "total_pages": 1 }}Webhook
Note
Webhooks access is currently available on a Platinum subscription and above. If this piques your interest, kindly refer to this article on how you can upgrade your subscription here or reach out to us via live chat on the HR platform
Registering a Webhook
Webhook Properties
To register a webhook, visit the My Webhooks page in the Developer Portal then click the Add Webhooks button. The webhook has 3 required fields:
| Field | Description |
|---|---|
| Name | Name of webhook. |
| URL | The URL for the webhook event callback. Please note that for security purposes, we request that you provide HTTPS URIs. |
| Events | The events that will trigger this particular webhook. |
Note
Once a webhook has been set up, you can update your webhook properties through the webhook details page. The new webhook will become active immediately.
Webhook Events
Webhook events that are currently available are:
- Employee Created
- Employee Onboarded
- Employee Updated
- Employee Offboarding
- Leave Request Created
- Leave Request Updated
- Leave Request Approved
- Leave Request Declined
- Leave Request Deleted
- Employee Bank Account Created
- Employee Bank Account Updated
- Employee Bank Account Deleted
- Employment History Created
- Employment History Updated
- Employment History Deleted
Webhook Callback
When an event occurs, it will trigger an HTTP request to the URL configured for the webhook. If the callback URL does not respond with a successful result (i.e. HTTP 200), it will be retried for a maximum of 3 times. If the callback URL still responds unsuccessfully, the webhook event will be marked as failed.
Schema
The type of webhook event
The payload of webhook event
Callback Body
{ "data": { "id": "1c8a8e41-82c8-4311-8115-07994dd28ac2", "approved": true, "end_date": "2020-02-04", "start_date": "2020-02-04", "employee_id": "ba967883-a3db-44a0-b807-bfac746599f7" }, "event": "leave_request_approved"}To see the history of webhook events, visit the Webhook
History
page or Webhook > Event History on the navigation bar from the Developer
Portal.
Verify Webhook Request
To ensure the authenticity and integrity of webhook requests from Employment Hero, you must verify the request signature. This confirms that the request is genuinely from Employment Hero and hasn't been tampered with.
Each webhook request from Employment Hero includes two headers:
| Header | Description |
|---|---|
| X-EmploymentHero-Signature | The SHA256 hash signature of the request. |
| X-EmploymentHero-Timestamp | The timestamp of the request. |
The signature is generated using a hash-based message authentication code (HMAC) with SHA-256, which signs the combination of the request payload and the timestamp.
How to Verify the Signature
- Get Your Secret Key
- Your secret key is available on the webhook configuration page in the Developer Portal. Use this key to generate the hash and verify the request.
- Extract Headers and Payload
- Retrieve the X-EmploymentHero-Signature header from the request.
- Retrieve the X-EmploymentHero-Timestamp header from the request.
- Get the raw JSON payload of the request.
- Concatenate Timestamp and Payload
- Combine the timestamp and the payload with a dot (
.) separator:data = "#{timestamp}.#{json_payload}"
- Generate HMAC SHA256 Hash
- Use your secret key to generate the SHA256 HMAC hash of the concatenated string.
- Compare Signatures
- Compare the generated hash with the value in X-EmploymentHero-Signature.
- If they match, the request is verified.
- If they do not match, reject the request.
require 'openssl'
require 'active_support/security_utils'
def verify_signature(secret_string, timestamp, payload, signature)
data = "#{timestamp}.#{payload}"
secret = Base64.decode64(secret_string)
digest = OpenSSL::HMAC.digest('SHA256', secret, data)
expected_signature = Base64.strict_encode64(digest)
ActiveSupport::SecurityUtils.secure_compare(expected_signature, signature)
endEmployee Data
Schema
The employee id
The gender of the employee
The country of employee (i.e AU, VI, US)
The preferred name of the employee
The job title of the employee
The last name of the employee
The first name of employee
The middle name of the employee
The avatar URL of the employee
The start date of the employee
The external id of employee (Id of payroll system)
The nationality of employee (i.e Australia, United States)
The email of employee account
The birthday of employee
The personal mobile number of employee
Callback Body
{ "data": { "id": "f5e41ec5-b85d-486a-9bd0-ef9b04284c6e", "gender": "male", "country": "AU", "known_as": "New employee", "job_title": "Tii", "last_name": "Please", "first_name": "Yes", "middle_name": "Midle Name", "avatar_url": "/avatar.svg", "start_date": "2020-02-27", "external_id": "123-123-123", "nationality": "Australia", "account_email": "abc@def.com", "date_of_birth": "1980-2-2", "personal_mobile_number": "+2222222222" }, "event": "employee_created"}Leave Request Data
Schema
Unique identifier for the object.
The start date of your employee leave request.
The end date of your employee leave request.
The total hours of leave request.
The total units of leave request.
The unit type of leave request (e.g., days, hours).
Array of objects specifying custom hours for specific dates
The comment of the leave request if an owner or admin has entered a notation
The status of leave request.
The approve status of leave request
The leave balance amount of leave request.
The category name of leave request object. I.E Annual Leave
The reason of employee's leave request.
The ID of employee who requested to leave.
Callback Body
{ "data": { "id": "de00c577-35a1-4cf2-9fe8-832f18d4c544", "reason": null, "status": "Approved", "comment": "", "approved": true, "end_date": "2025-10-22", "unit_type": "days", "start_date": "2025-10-15", "employee_id": "6902b0f2-f53a-466d-a9a0-073028716a3a", "total_hours": 0, "total_units": 6, "hours_per_day": [ { "date": "2025-12-12", "hours": 4 } ], "leave_category_name": "Annual Leave", "leave_balance_amount": 1000 }, "event": "leave_request_approved"}Bank Account Data
Schema
The bank account id
The employee id
The bsb number of bank account
The account name of bank account
The account number of bank account
Determine bank account is primary or not
Callback Body
{ "data": { "id": "78bc2d65-bf9e-434f-8b78-2367f56878ad", "employee_id": "92ab2d65-cd9e-123d-2b71-1234d56878cd", "bsb": "123123", "account_name": "mew123", "account_number": "123123", "primary_account": false }, "event": "bank_account_created"}Employment History Data
Schema
The employment history id
The job title
The start date of employment history
The end date of employment history
Determine employment history is being reviewed or not
Determine employment history is disabled or not
The member id of employment history
The organisation id of employment history
The employment type of employment history (Full-time, Part-time, etc.)
The time when employment history is declined
Callback Body
{ "data": { "id": "4f6c7312-67ab-4775-ab2e-a3761ff56385", "title": "Software Developer", "disabled": false, "end_date": "2021-12-09T00:00:00.000+00:00", "in_review": false, "member_id": "e826e79d-20d4-4b04-add2-8fa3c16cb7d8", "start_date": "2021-02-17T00:00:00.000+00:00", "declined_at": null, "employment_type": null, "organisation_id": "bdfcb02b-fcc3-4f09-8636-c06c14345b86" }, "event": "employment_history_created"}