Employment HeroEmployee
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 marital 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
Note
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": "Group 1" }, { "id": "95df8139-479f-432e-b8f9-112352123e4a", "name": "Group 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 marital 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
Note
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": "Group 1" }, { "id": "95df8139-479f-432e-b8f9-112352123e4a", "name": "Group 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/organisations/:organisation_id/employees/quick_add_employeePath Parameters
The ID of the organisation
Request 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/organisations/:organisation_id/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/organisations/:organisation_id/employees/quick_add_contractorPath Parameters
The ID of the organisation
Request 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/organisations/:organisation_id/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 initiates a comprehensive employee onboarding process using a polling-based approach. This endpoint creates the employee record and starts the onboarding workflow asynchronously, allowing for more complex processing and validation.
The required employee fields depend on the employee's country. This is determined primarily by the provided work_location fields. If the work_location fields are excluded, your organisation's country is used.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/polling_onboard_employeePath Parameters
The ID of the organisation
Request Body
User account attributes for the employee
Employment configuration details
Employee first name
Employee last name
Employee full legal name as it appears on official documents.
ID of the employing entity
Type of employment
Date of birth in YYYY-MM-DD format
Start date in YYYY-MM-DD format
Anniversary Date in YYYY-MM-DD format
Employee job title
Industry standard job title
Currency for salary (e.g., AUD, NZD, GBP, CAD, SGD, MYR)
Employee salary amount
Salary roster period
Length of probation period
ID of the primary manager
ID of the secondary manager
Employee work location details
Array of team IDs the employee belongs to. Required for Singapore.
Note
Primary cost centre ID
Secondary cost centres (comma-separated IDs)
Whether to sync with payroll system
System access date in YYYY-MM-DD format
Number of hours worked per week
Typical work day duration
Full-time equivalent units
Number of days worked per week
Zero hour based flag
Whether employee can clock in/out
Whether salary is annualised
Timesheet synchronization option
ID of the leave allowance template
Whether to automatically pay the employee
Whether employee portal access is enabled
Type of timesheet
Payroll detail information
Type of employment contract
End date in YYYY-MM-DD format. Required when contract_type is Fixed term.
Superannuation contribution amount
UUID of the award to assign to the employee. Must be provided together with classification_id. Use Get Awards and Classifications to retrieve valid values.
UUID of the classification to assign. Must be provided together with award_id. The classification must belong to the specified award.
When true, the provided salary overrides the rate defined in the award template. Only applicable when award_id and classification_id are set.
Whether to trigger onboarding checklists
Vacation pay percentage (0.01 to 100.00)
Vacation pay method
Whether the employee is paid irregularly
Whether to apply rolled up holiday pay
Rolled up holiday pay percentage (0.0 to 100.0)
Apprentice status
NWM (National Wage Minimum) / NLW (National Living Wage) eligibility
Employee code
Pay category ID. Required for Canada. Optional for United Kingdom.
Pay schedule ID. Required for Canada. Optional for United Kingdom.
KiwiSaver attributes (New Zealand only).
Malaysian NRIC details (Malaysia only)
NRIC (National Registration Identity Card) details (Singapore only). Required for Singapore.
Response Body
Initiates the polling-based employee onboarding process. This endpoint creates a new employee record and starts the onboarding workflow with all the provided employment details.
Note: This is a polling-based onboarding process, meaning the actual onboarding completion will be processed asynchronously. You may need to use Polling Onboard Result to track the completion of the onboarding process.
Success message
Polling key to track the onboarding process status
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/polling_onboard_employee" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "user_attributes": { "email": "employee@example.com" }, "first_name": "John", "last_name": "Doe", "full_legal_name": "Johnathan Doe", "employing_entity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "employment_type": "Full-time", "date_of_birth": "1990-01-15", "start_date": "2025-07-02", "anniversary_date": "2026-07-02", "job_title": "3D Artist", "industry_standard_job_title": "3D Visual Artist", "current_salary_version_currency": "AUD", "salary": 1000000, "roster": "Annum", "probation_length": 3, "primary_manager_id": "b1b2c3d4-e5f6-7890-abcd-ef1234567890", "secondary_manager_id": "c1b2c3d4-e5f6-7890-abcd-ef1234567890", "employment_detail": { "remote": "no", "province_of_employment": "Ontario", "confirmed_date": "2025-06-15" }, "work_location": { "id": "b992fc49-7e98-4743-b53b-51bec9cf4dc3", "name": "Sydney", "country": "AU" }, "teams": [ "d1b2c3d4-e5f6-7890-abcd-ef1234567890" ], "cost_centre_id": "f1b2c3d4-e5f6-7890-abcd-ef1234567890", "secondary_cost_centres_list": "g1b2c3d4-e5f6-7890-abcd-ef1234567890,h1b2c3d4-e5f6-7890-abcd-ef1234567890", "sync_with_payroll": true, "system_access_date": "2025-07-02", "hours_per_week": 40, "typical_work_day": 8, "full_time_equivalent_units": 1, "days_per_week": 5, "zero_hour_based": false, "clock_me_in": false, "annualised_salary": false, "timesheet_sync_option": "sync_timesheets_as_exceptions", "leave_allowance_template_id": "i1b2c3d4-e5f6-7890-abcd-ef1234567890", "automatically_pay_employee": false, "employee_portal_access_enabled": true, "timesheet_type": 1, "payroll_detail": { "stp_income_type": "salary_and_wages" }, "contract_type": "Permanent", "end_date": "2026-12-31", "superannuation_amount": 3, "trigger_onboarding_checklists": true, "vacation_pay_percentage": 4, "vacation_pay_method": "bankAccruedVacationPay", "employee_paid_irregularly": false, "apply_rolled_up_holiday_pay": false, "rolled_up_holiday_pay_percentage": 12, "apprentice": "not_an_apprentice", "nwm_nlw_eligibility": "eligible_for_nwm", "code": "EMP001", "pay_category_id": "j1b2c3d4-e5f6-7890-abcd-ef1234567890", "pay_schedule_id": "k1b2c3d4-e5f6-7890-abcd-ef1234567890", "kiwi_saver_attributes": { "employer_enrollment_status": "automatically_enroll", "employer_contribution": 3 }, "my_nric_details": { "residence_type": "malaysian", "residence_status": true, "worker_status": "normal", "income_tax_number": "IT12345678", "religion": "Buddhist", "ethnicity": "Chinese", "dependent_children": 2, "pcb_tax_borne": false, "employee_epf_rate": "11", "socso_type": "employment_injury_and_invalidity_scheme", "eis_exempt": false, "epf_number": "EPF123456789", "identity_card_number": "123456789012", "passport_number": "A12345678", "passport_issuing_country": "MY", "passport_expiry_date": "2030-12-31", "work_pass_type": "employment_pass", "ssfw_number": "SSFW123456", "epf_contribution_type": "member_after_august_1998" }, "nric_details": { "legal_status": "citizen", "nric_fin_number": "S1234567A", "nric_fin_type": "nric", "obtained_residency_date": "2010-01-01", "cpf_contribution_option": "graduated", "obtained_approval_date": "2010-01-01", "expiry_date": "2030-12-31", "nationality": "Singaporean", "ethnicity": "Chinese", "religion": "Buddhist", "covered_by_employment_act": "yes", "employee_group": "executive", "is_exempt_from_skills_dev_levy": false, "is_exempt_from_cpf": false } }'Response
{ "data": { "message": "Onboarding started", "polling_key": "job:onb:wKdLkkPvQey8" }}This endpoint allows you to check the status of an employee onboarding process that was initiated using the Polling Onboard Employee endpoint.
After initiating the onboarding process, you will receive a polling_key in the response. Use this key to poll this endpoint until the onboarding process completes (either successfully or with errors).
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/onboard/polling_status?polling_key={polling_key}Path Parameters
The ID of the organisation
Query Parameters
Polling key returned from the Polling Onboard Employee endpoint
Response Body
Returns the status of the employee onboarding process.
Polling: You should poll this endpoint periodically until the status is either success or failed. The polling interval is at your discretion, but we recommend checking every few seconds.
Status of the onboarding process
Array of error objects if status is failed, null in the case of success
ID of the onboarded employee if status is success, null otherwise
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/onboard/polling_status?polling_key={polling_key}" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "status": "success", "errors": [], "member_id": "b420ee26-41fe-4426-bf00-1cd5dfbefc7e" }}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 marital 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
Note
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": "Group 1" }, { "id": "95df8139-479f-432e-b8f9-112352123e4a", "name": "Group 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
Note
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 marital 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
Note
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": "Group 1" }, { "id": "95df8139-479f-432e-b8f9-112352123e4a", "name": "Group 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 marital 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
Note
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": "Group 1" }, { "id": "95df8139-479f-432e-b8f9-112352123e4a", "name": "Group 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." }}