Employment HeroThis endpoint retrieves all form categories for the organisation. Results include both built-in system categories and organisation-specific custom categories, ordered with system categories first then alphabetically by name.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/form_categoriesPath Parameters
The ID of the organisation
Query Parameters
Current page index
11Number of items per page
20100Response Body
Unique identifier for the form category.
The name of the form category.
Whether this is a built-in system category. System categories cannot be modified or deleted.
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/form_categories" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "name": "Compliance", "is_system": true }, { "id": "d2e3f4a5-b6c7-8901-bcde-f12345678901", "name": "Onboarding", "is_system": false } ], "page_index": 1, "item_per_page": 20, "total_items": 2, "total_pages": 1 }}This endpoint creates a new custom form category for the organisation. An organisation can have a maximum of 20 custom categories. Category names must be unique within the organisation (case-insensitive) and cannot exceed 20 characters.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/form_categoriesPath Parameters
The ID of the organisation
Request Body
The name of the form category. Must be unique within the organisation and cannot exceed 20 characters.
Response Body
Returns the created form category with a 201 status code.
Unique identifier for the form category.
The name of the form category.
Whether this is a built-in system category. System categories cannot be modified or deleted.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/form_categories" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "name": "Onboarding" }'Response
{ "data": { "id": "d2e3f4a5-b6c7-8901-bcde-f12345678901", "name": "Onboarding", "is_system": false }}This endpoint renames a custom form category for the organisation. Category names must be unique within the organisation (case-insensitive) and cannot exceed 20 characters. System categories (e.g. Benefit, Compliance, Performance) cannot be renamed and will return a 403 error.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/form_categories/:form_category_idPath Parameters
The ID of the organisation
The ID of the form category to update
Request Body
The new name for the form category. Must be unique within the organisation (case-insensitive) and cannot exceed 20 characters.
Response Body
Returns the updated form category with a 200 status code.
Unique identifier for the form category.
The name of the form category.
Whether this is a built-in system category. System categories cannot be modified or deleted.
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/form_categories/:form_category_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "name": "Onboarding" }'Response
{ "data": { "id": "d2e3f4a5-b6c7-8901-bcde-f12345678901", "name": "Onboarding", "is_system": false }}This endpoint permanently deletes a custom form category. System categories (e.g. Benefit, Compliance, Performance) cannot be deleted and will return a 403 error. Categories currently assigned to one or more forms or templates cannot be deleted and will return a 422 error.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/form_categories/:form_category_idPath Parameters
The ID of the organisation.
The ID of the form category to delete. System categories cannot be deleted.
Response Body
Returns HTTP 204 No Content on success. No response body is included.
Example
curl -X DELETE \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/form_categories/:form_category_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
This endpoint does not return a response body.