Employment HeroThis 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" }}