Employment HeroThis endpoint retrieves a paginated list of form templates for the organisation.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/form_templatesPath Parameters
The ID of the organisation.
Query Parameters
Current page index
11Number of items per page
20100Response Body
Unique identifier for the form template.
The name of the form template.
A description of the form template.
Unique identifier of the category the form template belongs to.
The name of the category the form template belongs to.
Whether this is a system-managed template. System templates cannot be updated or deleted.
The date and time the form template was created.
The date and time the form template was last updated.
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_templates" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Employee Onboarding Checklist", "description": "Standard onboarding form template for new employees.", "category_id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "category_name": "HR", "is_system": false, "created_at": "2024-01-15T09:00:00+10:00", "updated_at": "2024-03-20T14:30:00+10:00" } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}This endpoint retrieves a single form template including its full structure of sections and questions.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/form_templates/:template_idPath Parameters
The ID of the organisation.
The ID of the form template.
Response Body
Unique identifier for the form template.
The name of the form template.
A description of the form template.
Unique identifier of the category the form template belongs to.
The name of the category the form template belongs to.
Whether this is a system-managed template. System templates cannot be updated or deleted.
The date and time the form template was created.
The date and time the form template was last updated.
Who is allowed to submit the form. Always includes self.
Who can view the submitted response in the employee file.
The sections and questions of the form template.
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/form_templates/:template_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Employee Onboarding Checklist", "description": "Standard onboarding form template for new employees.", "category_id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "category_name": "HR", "is_system": false, "created_at": "2024-01-15T09:00:00+10:00", "updated_at": "2024-03-20T14:30:00+10:00", "submission_policies": [ "self", "primary_manager" ], "employee_file_view_policies": [ "affected_employee", "primary_manager" ], "sections": [ { "id": "section-1", "name": "Personal Details", "description": null, "questions": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "key": "ks-key-0000-0000-000000000001", "text": "What is your full name?", "description": "Please enter your legal full name.", "type": "short_text", "required": true, "visibility_condition": null }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "key": "ks-key-0000-0000-000000000002", "text": "What is your employment type?", "description": null, "type": "dropdown", "required": false, "visibility_condition": null, "options": [ { "id": "d4e5f6a7-b8c9-0123-def0-234567890123", "text": "Full-time" }, { "id": "e5f6a7b8-c9d0-1234-ef01-345678901234", "text": "Part-time" } ] } ] } ] }}Create a new form template with sections and questions.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/form_templatesPath Parameters
The ID of the organisation.
Request Body
The name of the form template. Must be unique within the organisation (max 255 characters).
An optional description of the form template.
The ID of the category to assign to this template. Must belong to the organisation.
The sections of the form template. At least one section is required.
Additional roles allowed to submit the form on behalf of the affected employee. self submission is always enabled and does not need to be specified.
Who can view submitted responses for this template in the employee file.
Question type requirements
| Question type | selection_options | statement | default_to_submitter |
|---|---|---|---|
short_text, long_text, number, date, date_time | Not applicable | Not applicable | Not applicable |
multiple_choice | Required — minimum 2 options | Not applicable | Not applicable |
dropdown | Required — minimum 2 options | Not applicable | Not applicable |
checkboxes | Required — minimum 1 option | Not applicable | Not applicable |
file_upload, signature | Not applicable | Not applicable | Not applicable |
acknowledgment | Not applicable | The text the employee must confirm | Not applicable |
employee_picker | Not applicable | Not applicable | Optional — defaults to false |
Option text within selection_options cannot be blank.
Conditional visibility
Questions can be conditionally shown or hidden based on the answer to another question using the visibility_condition field. To use this:
- Assign a
keyto the source question (the one being watched). - On the dependent question, set
visibility_condition.source_question_keyto that key. - Choose an
operatorvalid for the source question's type (see table below). - Set
valueto the answer value to compare against.
The source_question_key must match a key present elsewhere in the sections payload. Questions can reference source questions across different sections.
Valid operators by source question type:
| Source question type | Valid operators | Valid value |
|---|---|---|
short_text | equals, contains | Any string |
long_text | equals, contains | Any string |
number | equals, greater_than, less_than, greater_than_or_equal, less_than_or_equal | Numeric string (e.g. "5") |
date | equals, before, after | Date string in YYYY-MM-DD format |
date_time | equals, before, after | Date string in YYYY-MM-DD format |
multiple_choice | equals | Option text |
dropdown | equals, is_one_of | Option text; array of option texts for is_one_of |
checkboxes | includes | Option text |
employee_picker | equals, is_one_of | Employee UUID; array of UUIDs for is_one_of |
acknowledgment | is | "true" (acknowledged) |
file_upload | is | Not validated by the API |
signature | is | Not validated by the API |
Response Body
Returns the full detail of the newly created form template, including all sections and questions.
Unique identifier for the form template.
The name of the form template.
A description of the form template.
Unique identifier of the category the form template belongs to.
The name of the category the form template belongs to.
Whether this is a system-managed template. System templates cannot be updated or deleted.
The date and time the form template was created.
The date and time the form template was last updated.
Who is allowed to submit the form. Always includes self.
Who can view the submitted response in the employee file.
The sections and questions of the form template.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/form_templates" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "name": "Employee Onboarding Checklist", "description": "Standard onboarding form template for new employees.", "category_id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "sections": [ { "name": "Personal Details", "questions": [ { "text": "How many overtime hours did you work this week?", "type": "number", "required": true, "key": "q-overtime-hours" }, { "text": "Please provide a reason for your overtime.", "type": "short_text", "required": false, "key": "q-overtime-reason", "visibility_condition": { "source_question_key": "q-overtime-hours", "operator": "greater_than_or_equal", "value": "5" } }, { "text": "What is your employment type?", "type": "multiple_choice", "required": false, "selection_options": [ { "text": "Full-time" }, { "text": "Part-time" }, { "text": "Casual" } ] }, { "text": "Which benefits would you like to enrol in?", "type": "checkboxes", "required": false, "selection_options": [ { "text": "Health Insurance" }, { "text": "Gym Membership" } ] }, { "text": "Code of conduct acknowledgment", "type": "acknowledgment", "required": true, "statement": "I confirm that I have read and agree to the company code of conduct." } ] } ], "submission_policies": [ "primary_manager" ], "employee_file_view_policies": [ "affected_employee", "primary_manager" ] }'Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Employee Onboarding Checklist", "description": "Standard onboarding form template for new employees.", "category_id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "category_name": "HR", "is_system": false, "created_at": "2024-01-15T09:00:00+10:00", "updated_at": "2024-03-20T14:30:00+10:00", "submission_policies": [ "self", "primary_manager" ], "employee_file_view_policies": [ "affected_employee", "primary_manager" ], "sections": [ { "id": "section-1", "name": "Personal Details", "description": null, "questions": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "key": "ks-key-0000-0000-000000000001", "text": "What is your full name?", "description": "Please enter your legal full name.", "type": "short_text", "required": true, "visibility_condition": null }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "key": "ks-key-0000-0000-000000000002", "text": "What is your employment type?", "description": null, "type": "dropdown", "required": false, "visibility_condition": null, "options": [ { "id": "d4e5f6a7-b8c9-0123-def0-234567890123", "text": "Full-time" }, { "id": "e5f6a7b8-c9d0-1234-ef01-345678901234", "text": "Part-time" } ] } ] } ] }}This endpoint updates an existing form template. All fields are optional — only provided fields are updated. System templates cannot be modified.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/form_templates/:template_idPath Parameters
The ID of the organisation.
The ID of the form template to update. System templates cannot be updated.
Request Body
The name of the form template. Must be unique within the organisation (max 255 characters).
A description of the form template.
The ID of the category to assign to this template. Must belong to the organisation.
The sections of the form template. When provided, replaces all existing sections entirely. At least one section is required. Omit this field to leave existing sections unchanged.
Additional roles allowed to submit the form on behalf of the affected employee. self submission is always enabled and does not need to be specified. Pass an empty array to clear all additional policies.
Who can view submitted responses for this template in the employee file. Pass an empty array to clear all policies.
Sections replacement behaviour
When sections is included in the request, the entire sections structure is replaced. All existing sections and questions are discarded and rebuilt from the provided payload. Omit sections entirely to leave the existing structure unchanged.
Question type requirements
| Question type | selection_options | statement | default_to_submitter |
|---|---|---|---|
short_text, long_text, number, date, date_time | Not applicable | Not applicable | Not applicable |
multiple_choice | Required — minimum 2 options | Not applicable | Not applicable |
dropdown | Required — minimum 2 options | Not applicable | Not applicable |
checkboxes | Required — minimum 1 option | Not applicable | Not applicable |
file_upload, signature | Not applicable | Not applicable | Not applicable |
acknowledgment | Not applicable | The text the employee must confirm | Not applicable |
employee_picker | Not applicable | Not applicable | Optional — defaults to false |
Option text within selection_options cannot be blank.
Conditional visibility
Questions can be conditionally shown or hidden based on the answer to another question using the visibility_condition field. To use this:
- Assign a
keyto the source question (the one being watched). - On the dependent question, set
visibility_condition.source_question_keyto that key. - Choose an
operatorvalid for the source question's type (see table below). - Set
valueto the answer value to compare against.
The source_question_key must match a key present elsewhere in the sections payload. Questions can reference source questions across different sections.
Valid operators by source question type:
| Source question type | Valid operators | Valid value |
|---|---|---|
short_text | equals, contains | Any string |
long_text | equals, contains | Any string |
number | equals, greater_than, less_than, greater_than_or_equal, less_than_or_equal | Numeric string (e.g. "5") |
date | equals, before, after | Date string in YYYY-MM-DD format |
date_time | equals, before, after | Date string in YYYY-MM-DD format |
multiple_choice | equals | Option text |
dropdown | equals, is_one_of | Option text; array of option texts for is_one_of |
checkboxes | includes | Option text |
employee_picker | equals, is_one_of | Employee UUID; array of UUIDs for is_one_of |
acknowledgment | is | "true" (acknowledged) |
file_upload | is | Not validated by the API |
signature | is | Not validated by the API |
Response Body
Returns the full updated form template, including all sections and questions.
Unique identifier for the form template.
The name of the form template.
A description of the form template.
Unique identifier of the category the form template belongs to.
The name of the category the form template belongs to.
Whether this is a system-managed template. System templates cannot be updated or deleted.
The date and time the form template was created.
The date and time the form template was last updated.
Who is allowed to submit the form. Always includes self.
Who can view the submitted response in the employee file.
The sections and questions of the form template.
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/form_templates/:template_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "name": "Employee Onboarding Checklist (Revised)", "sections": [ { "name": "Employment Details", "questions": [ { "text": "What is your employment type?", "type": "dropdown", "required": true, "key": "employment-type", "selection_options": [ { "text": "Full-time" }, { "text": "Part-time" }, { "text": "Casual" } ] }, { "text": "How many hours per week?", "type": "number", "required": true, "key": "weekly-hours", "visibility_condition": { "source_question_key": "employment-type", "operator": "equals", "value": "Part-time" } } ] } ], "submission_policies": [ "primary_manager" ] }'Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Employee Onboarding Checklist", "description": "Standard onboarding form template for new employees.", "category_id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "category_name": "HR", "is_system": false, "created_at": "2024-01-15T09:00:00+10:00", "updated_at": "2024-03-20T14:30:00+10:00", "submission_policies": [ "self", "primary_manager" ], "employee_file_view_policies": [ "affected_employee", "primary_manager" ], "sections": [ { "id": "section-1", "name": "Personal Details", "description": null, "questions": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "key": "ks-key-0000-0000-000000000001", "text": "What is your full name?", "description": "Please enter your legal full name.", "type": "short_text", "required": true, "visibility_condition": null }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "key": "ks-key-0000-0000-000000000002", "text": "What is your employment type?", "description": null, "type": "dropdown", "required": false, "visibility_condition": null, "options": [ { "id": "d4e5f6a7-b8c9-0123-def0-234567890123", "text": "Full-time" }, { "id": "e5f6a7b8-c9d0-1234-ef01-345678901234", "text": "Part-time" } ] } ] } ] }}This endpoint permanently deletes a form template. System templates cannot be deleted.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/form_templates/:template_idPath Parameters
The ID of the organisation.
The ID of the form template to delete. System templates 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_templates/:template_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
This endpoint does not return a response body.