Employment HeroThis endpoint retrieves all benefit assignments for a specific employee. Available for AU, NZ, and UK organisations only.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/employee_benefitsPath Parameters
The ID of the organisation.
The ID of the employee to retrieve benefit assignments for.
Response Body
Returns all benefit assignments for the specified employee. Returns an empty items array when the employee has no benefit assignments.
List of benefit assignments for the employee.
Unique identifier for the employee benefit assignment.
The ID of the benefit definition that was assigned.
The name of the benefit.
The frequency at which the benefit is provided (e.g. monthly, annually).
The date the benefit assignment takes effect.
The date the benefit assignment ends.
The monetary amount for this benefit assignment.
An optional note about this benefit assignment.
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/employee_benefits" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "29c0d67f-8ae3-4508-8ed6-3d041a57b90b", "benefit_id": "bc89b487-ba67-42ed-820f-556825e34c3d", "benefit_name": "Phone Allowance", "frequency": "monthly", "effective_from": "2026-06-19T00:00:00+00:00", "effective_until": "2026-12-31T00:00:00+00:00", "amount": 50, "comment": "Phone allowance for H2 2026." } ] }}This endpoint retrieves paginated benefit assignments across all employees in an organisation. Available for AU, NZ, and UK organisations only.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employee_benefitsPath Parameters
The ID of the organisation.
Query Parameters
Page number (must be a positive integer).
1Number of items per page (1–100).
20Response Body
Returns a paginated list of benefit assignments across all employees in the organisation. Returns an empty items array when no assignments exist.
List of benefit assignments across all employees in the organisation.
The ID of the employee this benefit is assigned to.
Unique identifier for the employee benefit assignment.
The ID of the benefit definition that was assigned.
The name of the benefit.
The frequency at which the benefit is provided (e.g. monthly, annually).
The date the benefit assignment takes effect.
The date the benefit assignment ends.
The monetary amount for this benefit assignment.
An optional note about this benefit assignment.
Current page number.
Number of items per page.
Total number of benefit assignments across all pages.
Total number of pages.
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employee_benefits" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "id": "29c0d67f-8ae3-4508-8ed6-3d041a57b90b", "benefit_id": "bc89b487-ba67-42ed-820f-556825e34c3d", "benefit_name": "Phone Allowance", "frequency": "monthly", "effective_from": "2026-06-19T00:00:00+00:00", "effective_until": "2026-12-31T00:00:00+00:00", "amount": 50, "comment": "Phone allowance for H2 2026." } ], "page": 1, "per_page": 20, "total_count": 1, "total_pages": 1 }}This endpoint assigns a benefit to a specific employee. Available for AU, NZ, and UK organisations only.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/employee_benefitsPath Parameters
The ID of the organisation.
The ID of the employee to assign the benefit to.
Request Body
The ID of the benefit definition to assign. Must belong to the same organisation.
The date the benefit assignment takes effect (YYYY-MM-DD format).
The date the benefit assignment ends (YYYY-MM-DD format).
The monetary amount for this benefit assignment.
An optional note about this benefit assignment.
Response Body
Returns the created employee benefit assignment on 201 Created.
Returns 202 Accepted with { "message": "Update submitted for approval" } when the organisation has a benefit approval workflow configured — the assignment is created in a pending state and will take effect once approved.
Unique identifier for the employee benefit assignment.
The ID of the benefit definition that was assigned.
The date the benefit assignment takes effect.
The date the benefit assignment ends.
The monetary amount for this benefit assignment.
An optional note about this benefit assignment.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/employee_benefits" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "benefit_id": "bc89b487-ba67-42ed-820f-556825e34c3d", "effective_from": "2026-06-19", "effective_until": "2026-12-31", "amount": 50, "comment": "Phone allowance for H2 2026." }'Response
{ "data": { "id": "29c0d67f-8ae3-4508-8ed6-3d041a57b90b", "benefit_id": "bc89b487-ba67-42ed-820f-556825e34c3d", "effective_from": "2026-06-19T00:00:00+00:00", "effective_until": "2026-12-31T00:00:00+00:00", "amount": 50, "comment": "Phone allowance for H2 2026." }}This endpoint updates an existing employee benefit assignment. All fields are optional — only the fields provided in the request body will be updated. Available for AU, NZ, and UK organisations only.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/employee_benefits/:employee_benefit_idPath Parameters
The ID of the organisation.
The ID of the employee.
The ID of the employee benefit assignment to update.
Request Body
The date the benefit assignment takes effect (YYYY-MM-DD format).
The date the benefit assignment ends (YYYY-MM-DD format).
The monetary amount for this benefit assignment.
An optional note about this benefit assignment.
Response Body
Returns the updated employee benefit assignment on 200 OK. All request fields are optional — only fields provided in the request body will be updated. To clear a nullable field (amount, effective_until, comment), pass null explicitly.
Returns 202 Accepted with { "message": "Update submitted for approval" } when the organisation has a benefit approval workflow configured — the update is submitted in a pending state and will take effect once approved.
Unique identifier for the employee benefit assignment.
The ID of the benefit definition that was assigned.
The date the benefit assignment takes effect.
The date the benefit assignment ends.
The monetary amount for this benefit assignment.
An optional note about this benefit assignment.
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/employee_benefits/:employee_benefit_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "effective_from": "2027-06-19", "effective_until": "2027-06-20", "amount": 199.99, "comment": "Updated phone allowance for FY2027." }'Response
{ "data": { "id": "ff8c573b-0afc-4394-b43e-ee2eadbd350f", "benefit_id": "0ba57ae3-b2ec-4a58-be81-488fa438d4f8", "effective_from": "2027-06-19T00:00:00+00:00", "effective_until": "2027-06-20T00:00:00+00:00", "amount": 199.99, "comment": "Updated phone allowance for FY2027." }}This endpoint removes an employee benefit assignment. Available for AU, NZ, and UK organisations only.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/employee_benefits/:employee_benefit_idPath Parameters
The ID of the organisation.
The ID of the employee.
The ID of the employee benefit assignment to remove.
Response Body
Returns 204 No Content when the benefit assignment has been successfully removed.
Returns 202 Accepted with { "message": "Update submitted for approval" } when the organisation has a benefit approval workflow configured — the removal is submitted in a pending state and will take effect once approved.
Returned when the organisation has a benefit approval workflow configured.
Example
curl -X DELETE \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/employee_benefits/:employee_benefit_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "message": "Update submitted for approval" }}