Pay Detail

Get Pay Details

This endpoint retrieves a list of all pay details for a specific employee.

GET

https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/pay_details

Path Parameters

organisation_iduuidrequired

The ID of the organisation to retrieve

employee_iduuidrequired

The ID of the employee to retrieve

Query Parameters

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

Response 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.

dataobject

itemsobject[]

iduuid

Unique identifier for the object.

effective_fromstring

The effect date of the pay detail.

classificationstring

The name of the classification.

industrial_instrumentstring

The name of the industrial instrument.

pay_rate_templatestring

The name of the pay rate template.

anniversary_datedatetime

The anniversary date of the pay detail.

salarynumber

The salary amount.

salary_typestring

The type of salary.

pay_unitstring

The unit of pay rate.

pay_categorystring

The name of the pay category.

leave_allowance_templatestring

The name of the leave allowance template.

change_reasonstring

The reason of changing pay detail.

commentsstring

The comments.

currencystring

The currency.

hours_per_weekstring

Hours worked per week.

days_per_weekstring

Days worked per week.

full_time_equivalent_unitsstring

Full-time equivalent units.

employee_work_hoursstring

Work hours configuration for the employee.

in_reviewboolean

Indicates if the pay detail is under review.

zero_hour_basedboolean

Indicates the employee is on a zero-hour contract.

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

total_itemsnumber

Total items

total_pagesnumber

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  }}

Create Salary Version

This endpoint creates a new salary version for an employee. It supports updating the award and classification, adjusting salary, and recording a reason for change — all with a configurable effective date.

POST

https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/pay_details/salary_versions

Path Parameters

organisation_iduuidrequired

The ID of the organisation

employee_iduuidrequired

The ID of the employee

Request Body

effective_datestringrequired

Effective date in YYYY-MM-DD format. Must be unique for this employee — the request will return an error if a salary version with the same effective date already exists.

award_iduuid

UUID of the award to assign. Must be provided together with classification_id. Use Get Awards and Classifications to retrieve valid values.

classification_iduuid

UUID of the classification to assign. Must be provided together with award_id. The classification must belong to the specified award.

salarynumber

Salary amount.

salary_typeenum<string>

Salary type.

override_template_rateboolean

When true, the provided salary overrides the rate defined in the award template. Only applicable when award_id and classification_id are set.

anniversary_datestring

Anniversary date in YYYY-MM-DD format. Required for anniversary-based classifications.

pay_category_iduuid

UUID of the pay category to assign. Required for organisations using Employment Hero payroll when no classification_id is provided. Ignored when award_id and classification_id are provided, as the pay category is resolved automatically from the classification.

change_reasonstring

Reason for the salary change.

Response Body

Returns 201 with the newly created salary version when the change is applied immediately.

Returns 202 with { "message": "Update submitted for approval" } when the organisation has a pay rate approval workflow configured — the change is created in a pending state and will take effect once approved.

dataobject

iduuid

Unique identifier for the object.

effective_fromstring

The effect date of the pay detail.

classificationstring

The name of the classification.

industrial_instrumentstring

The name of the industrial instrument.

pay_rate_templatestring

The name of the pay rate template.

anniversary_datedatetime

The anniversary date of the pay detail.

salarynumber

The salary amount.

salary_typestring

The type of salary.

pay_unitstring

The unit of pay rate.

pay_categorystring

The name of the pay category.

leave_allowance_templatestring

The name of the leave allowance template.

change_reasonstring

The reason of changing pay detail.

commentsstring

The comments.

currencystring

The currency.

hours_per_weekstring

Hours worked per week.

days_per_weekstring

Days worked per week.

full_time_equivalent_unitsstring

Full-time equivalent units.

employee_work_hoursstring

Work hours configuration for the employee.

in_reviewboolean

Indicates if the pay detail is under review.

zero_hour_basedboolean

Indicates the employee is on a zero-hour contract.

Example

curl -X POST \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/pay_details/salary_versions" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "effective_date": "2025-08-01",    "award_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",    "classification_id": "b1b2c3d4-e5f6-7890-abcd-ef1234567890",    "change_reason": "Annual review"  }'

Response

{  "data": {    "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  }}

Update Work Hours

This endpoint updates the work hours for a specific employee. It supports two mutually exclusive modes — standard aggregate mode (total hours per week) and per-day schedule mode (hours per day of the week). Available for AU and NZ organisations only.

PUT

https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/pay_details/work_hours

Path Parameters

organisation_iduuidrequired

The ID of the organisation

employee_iduuidrequired

The ID of the employee

Request Body

hours_per_weeknumber

Employee's actual weekly hours. Required in standard mode (when work_hour_schedules is absent). Must be ≥ 0.

typical_work_daynumber

Average hours per working day. Required in standard mode. Used to derive days_per_week = hours_per_week / typical_work_day. Must be between 0 and 24 (inclusive).

days_per_weeknumber

Days worked per week. Optional — only accepted when salary_type is "Day". When salary_type is not "Day", this value is ignored and derived automatically as hours_per_week / typical_work_day. Must be between 0 and 7 (inclusive).

full_time_equivalent_unitsnumber

The "full time" hours denominator for FTE calculation. Defaults to the organisation's employment settings value if omitted. When salary_type is "Day", must be greater than 0 and at most 7 (0 < full_time_equivalent_units ≤ 7).

work_hour_schedulesobject[]

Per-day work hour entries. When present, activates per-day schedule mode — hours_per_week and typical_work_day are ignored. At least one entry is required.

Per-day schedule mode

Include work_hour_schedules to set hours per day. Days omitted retain their existing stored values (defaulting to 0.0 if none exist). hours_per_week and typical_work_day are ignored when work_hour_schedules is present.

Single-week example:

{
  "full_time_equivalent_units": 38.0,
  "work_hour_schedules": [
    { "day": "monday",    "hours": 8.0 },
    { "day": "tuesday",   "hours": 8.0 },
    { "day": "wednesday", "hours": 8.0 }
  ]
}

Two-week rotating roster example:

{
  "full_time_equivalent_units": 38.0,
  "work_hour_schedules": [
    { "day": "monday",  "hours": 8.0, "week": "1" },
    { "day": "tuesday", "hours": 8.0, "week": "1" },
    { "day": "monday",  "hours": 7.6, "week": "2" },
    { "day": "friday",  "hours": 7.6, "week": "2" }
  ]
}

Standard aggregate mode

When work_hour_schedules is absent, the endpoint uses aggregate mode. hours_per_week and typical_work_day are required. typical_work_day must be between 0 and 24 (inclusive).

{
  "hours_per_week": 38.0,
  "typical_work_day": 7.6,
  "full_time_equivalent_units": 38.0
}

Day-rate salary (salary_type = "Day") example:

When the employee's salary type is "Day", days_per_week can be supplied directly (0–7 inclusive) and full_time_equivalent_units must be greater than 0 and at most 7.

{
  "hours_per_week": 38.0,
  "typical_work_day": 7.6,
  "days_per_week": 5.0,
  "full_time_equivalent_units": 5.0
}

Response Body

Returns HTTP 200 with the saved work hours object when changes are applied immediately. Returns HTTP 202 (with a message field only) when an approval workflow is triggered — work hours are not saved until approved.

dataobject

hours_per_weeknumber

Total hours worked per week.

typical_work_daynumber

Average hours per working day.

days_per_weeknumber

Days worked per week (derived from hours_per_week / typical_work_day).

full_time_equivalent_unitsnumber

The "full time" hours denominator used for FTE calculation.

zero_hour_basedboolean

Indicates the employee is on a zero-hour contract.

employee_work_hoursenum<string>

Work hours mode applied. standard_daily for aggregate mode; custom_work for per-day schedule mode.

work_hour_schedulesobject[]

Per-day schedule entries. Only present when employee_work_hours is custom_work. All 7 days per week are returned, ordered by week then day.

202 — Pending approval

When the organisation has approval workflows enabled for work hour changes, the endpoint returns 202 instead of 200. Work hours are not saved yet — a change request is created and awaits approval in the Employment Hero UI.

{
  "data": {
    "message": "Request has been sent for approval. All changes to the employee file will be updated once they have been approved."
  }
}

After a 202 response, subsequent PUT calls for the same employee return 422 until the pending approval is resolved (approved or rejected).

Example

curl -X PUT \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/pay_details/work_hours" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "full_time_equivalent_units": 38,    "work_hour_schedules": [      {        "day": "monday",        "hours": 8      },      {        "day": "tuesday",        "hours": 8      },      {        "day": "wednesday",        "hours": 8      }    ]  }'

Response

{  "data": {    "hours_per_week": 24,    "typical_work_day": 8,    "days_per_week": 3,    "full_time_equivalent_units": 38,    "zero_hour_based": false,    "employee_work_hours": "custom_work",    "work_hour_schedules": [      {        "day": "sunday",        "hours": 0,        "week": "1"      },      {        "day": "monday",        "hours": 8,        "week": "1"      },      {        "day": "tuesday",        "hours": 8,        "week": "1"      },      {        "day": "wednesday",        "hours": 8,        "week": "1"      },      {        "day": "thursday",        "hours": 0,        "week": "1"      },      {        "day": "friday",        "hours": 0,        "week": "1"      },      {        "day": "saturday",        "hours": 0,        "week": "1"      }    ]  }}