Employment HeroLists the unavailability of the organisation's active contractors within a date window. Requires the Contractor Unavailabilities - Read scope and an organisation admin or owner.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/contractor_unavailabilitiesPath Parameters
The ID of the organisation.
Query Parameters
Start of the date window in YYYY-MM-DD format. Records that overlap the window are returned, including records that start before this date.
End of the date window in YYYY-MM-DD format. Must not be before start_date or more than 366 days after it.
If set, only return unavailability of this contractor. Must be the ID of a contractor in the organisation.
Current page index
11Number of items per page
20100Response Body
A paginated list of contractor unavailability records overlapping the requested window. A recurring series appears as one item per occurrence date, all sharing the same id, and total_items counts these expanded items.
Unique identifier of the unavailability. Occurrences of a recurring unavailability share the same ID.
ID of the contractor the unavailability belongs to.
The first day of the unavailability in YYYY-MM-DD format.
The last day of the unavailability in YYYY-MM-DD format (inclusive).
true if the contractor is unavailable for the whole day. Records created through this API are always all-day.
The time of day (HH:MM) when a partial-day unavailability begins. null when all_day is true.
The time of day (HH:MM) when a partial-day unavailability ends. null when all_day is true.
true if the record is, or is one occurrence of, a recurring unavailability. The recurrence pattern itself is not returned.
Optional description of the unavailability.
The status of the record. Always unavailable.
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/contractor_unavailabilities" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "member_id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e", "start_date": "2027-06-01", "end_date": "2027-06-10", "all_day": true, "start_time": null, "end_time": null, "recurring": false, "description": "School holidays", "status": "unavailable" } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}Retrieves a single contractor unavailability record by ID. Requires the Contractor Unavailabilities - Read scope and an organisation admin or owner.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/contractor_unavailabilities/:contractor_unavailability_idPath Parameters
The ID of the organisation.
The ID of the contractor unavailability.
Response Body
The requested contractor unavailability record.
Unique identifier of the unavailability. Occurrences of a recurring unavailability share the same ID.
ID of the contractor the unavailability belongs to.
The first day of the unavailability in YYYY-MM-DD format.
The last day of the unavailability in YYYY-MM-DD format (inclusive).
true if the contractor is unavailable for the whole day. Records created through this API are always all-day.
The time of day (HH:MM) when a partial-day unavailability begins. null when all_day is true.
The time of day (HH:MM) when a partial-day unavailability ends. null when all_day is true.
true if the record is, or is one occurrence of, a recurring unavailability. The recurrence pattern itself is not returned.
Optional description of the unavailability.
The status of the record. Always unavailable.
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/contractor_unavailabilities/:contractor_unavailability_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "member_id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e", "start_date": "2027-06-01", "end_date": "2027-06-10", "all_day": true, "start_time": null, "end_time": null, "recurring": false, "description": "School holidays", "status": "unavailable" }}Creates an all-day unavailability for an active contractor. Requires the Contractor Unavailabilities - Create scope and an organisation admin or owner. The change is recorded in the contractor's audit trail.
Not idempotent
Sending the same request twice creates two records, and a request that times out may still have been processed. Partial-day and recurring unavailability cannot be created.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/contractor_unavailabilitiesPath Parameters
The ID of the organisation.
Request Body
The ID of an active contractor in the organisation.
The first day of the unavailability in YYYY-MM-DD format.
The last day of the unavailability in YYYY-MM-DD format (inclusive). Must not be before start_date or more than 366 days after it.
Defaults to true. Only true is supported; false is rejected.
Optional description. Maximum 500 characters.
Response Body
The newly created contractor unavailability record.
Unique identifier of the unavailability. Occurrences of a recurring unavailability share the same ID.
ID of the contractor the unavailability belongs to.
The first day of the unavailability in YYYY-MM-DD format.
The last day of the unavailability in YYYY-MM-DD format (inclusive).
true if the contractor is unavailable for the whole day. Records created through this API are always all-day.
The time of day (HH:MM) when a partial-day unavailability begins. null when all_day is true.
The time of day (HH:MM) when a partial-day unavailability ends. null when all_day is true.
true if the record is, or is one occurrence of, a recurring unavailability. The recurrence pattern itself is not returned.
Optional description of the unavailability.
The status of the record. Always unavailable.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/contractor_unavailabilities" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "member_id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e", "start_date": "2027-06-01", "end_date": "2027-06-10", "all_day": true, "description": "School holidays" }'Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "member_id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e", "start_date": "2027-06-01", "end_date": "2027-06-10", "all_day": true, "start_time": null, "end_time": null, "recurring": false, "description": "School holidays", "status": "unavailable" }}Updates the dates and/or description of an all-day, non-recurring contractor unavailability; at least one field is required. Recurring and partial-day records cannot be updated, and the last write wins. Requires the Contractor Unavailabilities - Update scope and an organisation admin or owner. The change is recorded in the contractor's audit trail.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/contractor_unavailabilities/:contractor_unavailability_idPath Parameters
The ID of the organisation.
The ID of the contractor unavailability to update.
Request Body
The revised first day in YYYY-MM-DD format. Cannot be null. If end_date is omitted, the existing end date is kept.
The revised last day in YYYY-MM-DD format (inclusive). Cannot be null. If start_date is omitted, the existing start date is kept. The resulting end_date must not be before start_date or more than 366 days after it.
The revised description. Maximum 500 characters. Send an empty string to clear it; null is rejected.
Response Body
The updated contractor unavailability record.
Unique identifier of the unavailability. Occurrences of a recurring unavailability share the same ID.
ID of the contractor the unavailability belongs to.
The first day of the unavailability in YYYY-MM-DD format.
The last day of the unavailability in YYYY-MM-DD format (inclusive).
true if the contractor is unavailable for the whole day. Records created through this API are always all-day.
The time of day (HH:MM) when a partial-day unavailability begins. null when all_day is true.
The time of day (HH:MM) when a partial-day unavailability ends. null when all_day is true.
true if the record is, or is one occurrence of, a recurring unavailability. The recurrence pattern itself is not returned.
Optional description of the unavailability.
The status of the record. Always unavailable.
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/contractor_unavailabilities/:contractor_unavailability_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "end_date": "2027-06-12", "description": "School holidays (extended)" }'Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "member_id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e", "start_date": "2027-06-01", "end_date": "2027-06-12", "all_day": true, "start_time": null, "end_time": null, "recurring": false, "description": "School holidays (extended)", "status": "unavailable" }}Deletes a contractor unavailability record. Requires the Contractor Unavailabilities - Delete scope and an organisation admin or owner. The change is recorded in the contractor's audit trail.
Recurring unavailability
Do not delete recurring unavailability through this API. Manage it in the Employment Hero web app.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/contractor_unavailabilities/:contractor_unavailability_idPath Parameters
The ID of the organisation.
The ID of the contractor unavailability to delete.
Response Body
Returns HTTP 204 No Content on success. Deleting the same ID again fails because the record no longer exists.
Example
curl -X DELETE \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/contractor_unavailabilities/:contractor_unavailability_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
This endpoint does not return a response body.