Employment HeroReturns a paginated list of labour rules for the organisation. Optionally filter by work_site_id to retrieve rules for a specific work site. When work_site_id is omitted, rules for all work sites the caller can see are returned.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/labour_rulesPath Parameters
The ID of the organisation.
Query Parameters
Filter labour rules to a specific work site. When omitted, returns rules for all work sites the caller can see.
Page number (1-based). Defaults to 1.
Number of results per page. Defaults to 20. Maximum 100.
Response Body
Returns a paginated list of labour rules for the organisation.
Paginated list of labour rules.
Array of labour rule objects.
Number of items per page.
Current page number.
Total number of matching labour rules.
Total number of pages.
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/labour_rules" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Weekend Lunch Rush", "coverage_type": "linear", "metric_type": "gross_sales", "metric_reporting_type_id": null, "metric_forecasted": false, "coverage_definition": { "minimum_headcount": 2, "step_headcount": 1, "per_dollar_step_size": 500, "maximum_headcount": null }, "run_time_type": "within_operating_hours", "start_buffer_amount": 0.5, "start_buffer_direction": "before", "end_buffer_amount": 0.5, "end_buffer_direction": "after", "work_site": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "City Store" }, "hr_positions": [ { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Floor Staff" } ], "disabled": false, "disabled_reason": null } ], "item_per_page": 20, "page_index": 1, "total_items": 1, "total_pages": 1 }}Returns the full details of a single labour rule by ID, including its disabled and disabled_reason state. Disabled rules remain readable.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/labour_rules/:idPath Parameters
The ID of the organisation.
The ID of the labour rule.
Response Body
Returns the full details of the specified labour rule.
Unique identifier for the labour rule.
Name of the labour rule. Must be unique within the organisation.
How headcount coverage is determined. "linear" adds headcount in steps as the metric value grows; "range" picks headcount from a step table.
The sales metric used to calculate required headcount.
ID of the reporting type (e.g. a specific sales category or order type). Required when metrictype is "category" or "ordertype".
Whether the metric uses forecasted data rather than actual data.
Definition of coverage requirements. Shape depends on coverage_type — see create/update docs for details.
When the labour rule is active. "anytime" applies at any time; "withinoperating_hours" applies only within the work site's operating hours.
Buffer duration (in hours, in 0.5-hour increments) before the start of operating hours. Only valid when runtimetype is "withinoperatinghours".
Whether the start buffer extends before or after the operating hours start. Only valid when runtimetype is "withinoperatinghours".
Buffer duration (in hours, in 0.5-hour increments) after the end of operating hours. Only valid when runtimetype is "withinoperatinghours".
Whether the end buffer extends before or after the operating hours end. Only valid when runtimetype is "withinoperatinghours".
The work site this labour rule belongs to.
Positions currently assigned to this labour rule.
Whether the labour rule currently cannot take effect — either its work site is archived, or every position assigned to it is archived/deleted. Disabled rules remain readable, updatable and deletable.
Reason the rule is disabled. Null when the rule is active.
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/labour_rules/:id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Weekend Lunch Rush", "coverage_type": "linear", "metric_type": "gross_sales", "metric_reporting_type_id": null, "metric_forecasted": false, "coverage_definition": { "minimum_headcount": 2, "step_headcount": 1, "per_dollar_step_size": 500, "maximum_headcount": null }, "run_time_type": "within_operating_hours", "start_buffer_amount": 0.5, "start_buffer_direction": "before", "end_buffer_amount": 0.5, "end_buffer_direction": "after", "work_site": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "City Store" }, "hr_positions": [ { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Floor Staff" } ], "disabled": false, "disabled_reason": null }}Creates a new labour rule for a work site. The fields each coverage_type requires are listed in the coverage_definition parameter.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/labour_rulesPath Parameters
The ID of the organisation.
Request Body
ID of the work site this labour rule belongs to.
Name of the labour rule. Must be unique within the organisation.
How headcount coverage is determined. "linear" adds headcount in steps as the metric value grows; "range" picks headcount from a step table.
The sales metric used to calculate required headcount.
ID of the reporting type. Required when metrictype is "category" or "ordertype".
Whether to use forecasted metric data rather than actual data.
Coverage requirements definition. Shape depends on coverage_type:
linear — requires: minimum_headcount (positive number), step_headcount (positive number), per_dollar_step_size (positive number). Optional: maximum_headcount (positive number ≥ minimumheadcount). Headcount = minimum_headcount + step_headcount × floor(metric value ÷ per_dollar_step_size), capped at `maximumheadcount` when set.
range — requires: steps array with at least 2 objects, each with headcount (> 0), from (≥ 0), and to (> from, or null on the last step).
IDs of positions to assign to the new rule. Defaults to none when omitted.
When the labour rule is active. "anytime" applies at any time; "withinoperating_hours" applies only within the work site's configured operating hours.
Buffer duration in hours (0.5-hour increments) before or after operating hours start. Only valid when runtimetype is "withinoperatinghours".
Direction of the start buffer relative to operating hours start. Only valid when runtimetype is "withinoperatinghours".
Buffer duration in hours (0.5-hour increments) before or after operating hours end. Only valid when runtimetype is "withinoperatinghours".
Direction of the end buffer relative to operating hours end. Only valid when runtimetype is "withinoperatinghours".
Response Body
Returns the full details of the newly created labour rule.
Unique identifier for the labour rule.
Name of the labour rule. Must be unique within the organisation.
How headcount coverage is determined. "linear" adds headcount in steps as the metric value grows; "range" picks headcount from a step table.
The sales metric used to calculate required headcount.
ID of the reporting type (e.g. a specific sales category or order type). Required when metrictype is "category" or "ordertype".
Whether the metric uses forecasted data rather than actual data.
Definition of coverage requirements. Shape depends on coverage_type — see create/update docs for details.
When the labour rule is active. "anytime" applies at any time; "withinoperating_hours" applies only within the work site's operating hours.
Buffer duration (in hours, in 0.5-hour increments) before the start of operating hours. Only valid when runtimetype is "withinoperatinghours".
Whether the start buffer extends before or after the operating hours start. Only valid when runtimetype is "withinoperatinghours".
Buffer duration (in hours, in 0.5-hour increments) after the end of operating hours. Only valid when runtimetype is "withinoperatinghours".
Whether the end buffer extends before or after the operating hours end. Only valid when runtimetype is "withinoperatinghours".
The work site this labour rule belongs to.
Positions currently assigned to this labour rule.
Whether the labour rule currently cannot take effect — either its work site is archived, or every position assigned to it is archived/deleted. Disabled rules remain readable, updatable and deletable.
Reason the rule is disabled. Null when the rule is active.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/labour_rules" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "work_site_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Weekend Lunch Rush", "coverage_type": "linear", "metric_type": "gross_sales", "metric_forecasted": false, "coverage_definition": { "minimum_headcount": 2, "step_headcount": 1, "per_dollar_step_size": 500 }, "hr_position_ids": [ "c3d4e5f6-a7b8-9012-cdef-123456789012" ], "run_time_type": "within_operating_hours", "start_buffer_amount": 0.5, "start_buffer_direction": "before", "end_buffer_amount": 0.5, "end_buffer_direction": "after" }'Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Weekend Lunch Rush", "coverage_type": "linear", "metric_type": "gross_sales", "metric_reporting_type_id": null, "metric_forecasted": false, "coverage_definition": { "minimum_headcount": 2, "step_headcount": 1, "per_dollar_step_size": 500, "maximum_headcount": null }, "run_time_type": "within_operating_hours", "start_buffer_amount": 0.5, "start_buffer_direction": "before", "end_buffer_amount": 0.5, "end_buffer_direction": "after", "work_site": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "City Store" }, "hr_positions": [ { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Floor Staff" } ], "disabled": false, "disabled_reason": null }}Partially updates an existing labour rule. All fields are optional — only the fields present in the request body are updated; every other field (including work_site_id) keeps its current value.
coverage_definition is fully replaced when provided; partial updates to it are not supported.
hr_position_ids has special omit-vs-empty semantics:
- Omit the key to leave the rule's current position assignments untouched.
- Pass an explicit
[]to clear every assignment. - Pass a list of position IDs to replace the assignments with exactly that list.
Re-assigning an active position to a rule that was disabled only because all of its positions were archived or deleted re-enables it. A disabled rule can still be updated.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/labour_rules/:idPath Parameters
The ID of the organisation.
The ID of the labour rule to update.
Request Body
ID of the work site to move the rule to. Omit to keep the current work site.
Updated name. Must be unique within the organisation.
How headcount coverage is determined.
The sales metric used to calculate required headcount.
ID of the reporting type. Required when metrictype is "category" or "ordertype".
Whether to use forecasted metric data.
Full replacement of the coverage definition. Shape depends on coverage_type — see create docs for details.
Omit to leave current assignments untouched; pass [] to clear them; pass a list of IDs to replace the assignments with exactly that list.
When the labour rule is active.
Buffer duration in hours (0.5-hour increments) at the start of operating hours. Only valid when runtimetype is "withinoperatinghours".
Direction of the start buffer.
Buffer duration in hours (0.5-hour increments) at the end of operating hours.
Direction of the end buffer.
Response Body
Returns the full details of the updated labour rule.
Unique identifier for the labour rule.
Name of the labour rule. Must be unique within the organisation.
How headcount coverage is determined. "linear" adds headcount in steps as the metric value grows; "range" picks headcount from a step table.
The sales metric used to calculate required headcount.
ID of the reporting type (e.g. a specific sales category or order type). Required when metrictype is "category" or "ordertype".
Whether the metric uses forecasted data rather than actual data.
Definition of coverage requirements. Shape depends on coverage_type — see create/update docs for details.
When the labour rule is active. "anytime" applies at any time; "withinoperating_hours" applies only within the work site's operating hours.
Buffer duration (in hours, in 0.5-hour increments) before the start of operating hours. Only valid when runtimetype is "withinoperatinghours".
Whether the start buffer extends before or after the operating hours start. Only valid when runtimetype is "withinoperatinghours".
Buffer duration (in hours, in 0.5-hour increments) after the end of operating hours. Only valid when runtimetype is "withinoperatinghours".
Whether the end buffer extends before or after the operating hours end. Only valid when runtimetype is "withinoperatinghours".
The work site this labour rule belongs to.
Positions currently assigned to this labour rule.
Whether the labour rule currently cannot take effect — either its work site is archived, or every position assigned to it is archived/deleted. Disabled rules remain readable, updatable and deletable.
Reason the rule is disabled. Null when the rule is active.
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/labour_rules/:id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "name": "Weekend Lunch Rush — Updated", "coverage_definition": { "minimum_headcount": 3, "step_headcount": 1, "per_dollar_step_size": 400 } }'Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Weekend Lunch Rush — Updated", "coverage_type": "linear", "metric_type": "gross_sales", "metric_reporting_type_id": null, "metric_forecasted": false, "coverage_definition": { "minimum_headcount": 3, "step_headcount": 1, "per_dollar_step_size": 400 }, "run_time_type": "within_operating_hours", "start_buffer_amount": 0.5, "start_buffer_direction": "before", "end_buffer_amount": 0.5, "end_buffer_direction": "after", "work_site": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "City Store" }, "hr_positions": [ { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Floor Staff" } ], "disabled": false, "disabled_reason": null }}Permanently deletes a labour rule. This action cannot be undone. Positions assigned to the rule are unassigned, not deleted. A disabled rule can still be deleted.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/labour_rules/:idPath Parameters
The ID of the organisation.
The ID of the labour rule to delete.
Response Body
Returns HTTP 204 No Content on success. The labour rule is permanently deleted.
Example
curl -X DELETE \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/labour_rules/:id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
This endpoint does not return a response body.
Returns the sales/labour metrics available to build a labour rule against for a work site. Use this to populate the metric selector when creating or editing a labour rule. The work_site_id query parameter is required.
gross_sales (actual and forecasted) and transaction_count are always available. net_sales, category and forecasted variants only appear once the work site has an active POS connection from a supporting provider.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/labour_rules/metricsPath Parameters
The ID of the organisation.
Query Parameters
The ID of the work site to retrieve available metrics for. Required.
Response Body
Returns the metrics available for building a labour rule at the specified work site.
List of metrics available for building a labour rule at the work site.
The metric type. Use as metric_type when creating or updating a labour rule.
Set for category metrics — the POS category ID. Use as metric_reporting_type_id when creating or updating a labour rule.
Whether this metric uses forecasted data rather than actual data. Use as metric_forecasted.
Human-readable label for the metric.
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/labour_rules/metrics" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": [ { "type": "gross_sales", "reporting_type_id": null, "forecasted": false, "label": "Sales (Actual)" }, { "type": "gross_sales", "reporting_type_id": null, "forecasted": true, "label": "Sales (Forecasted)" }, { "type": "transaction_count", "reporting_type_id": null, "forecasted": false, "label": "Transaction count (Actual)" } ]}