Employment HeroThis endpoint retrieves a paginated list of forms for the organisation, including both basic forms and request forms. Use the form_type field to tell them apart, or the form_type query parameter to return only one type.
Request forms
Request forms are returned only when the caller has permission to manage
request forms, and they include additional fields such as board_id and
default_priority. Fields that apply to only one form type are omitted from
the other type. Request forms are read-only in the API.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/formsPath Parameters
The ID of the organisation
Query Parameters
Filter by form status
Filter by category ID
Filter by form type
Current page index
11Number of items per page
20100Response Body
Unique identifier for the custom form.
The name of the custom form.
The current status of the custom form.
The type of the form. basic_form is a standard custom form; request_form is a request form managed from the Employment Hero platform.
Unique identifier of the category the form belongs to. Only present when form_type is basic_form.
The name of the category the form belongs to. Only present when form_type is basic_form.
A description of the custom form.
The date and time the form was created.
The date and time the form was last updated.
The ID of the request board that submitted requests are sent to. Only present when form_type is request_form.
The name of the request board that submitted requests are sent to. Only present when form_type is request_form.
When the handling team is notified about submitted requests. Only present when form_type is request_form.
Whether the request form can be submitted through a public link. Only present when form_type is request_form.
The path of the public submission link. null unless public_sharing_enabled is true. Only present when form_type is request_form.
Whether submitted requests appear in the employee file of the requester. Only present when form_type is request_form.
The priority given to requests submitted through this form by default. Only present when form_type is request_form.
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/forms" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Employee Onboarding Checklist", "status": "active", "form_type": "basic_form", "category_id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "category_name": "HR", "description": "Standard onboarding form for new employees.", "created_at": "2024-01-15T09:00:00+10:00", "updated_at": "2024-03-20T14:30:00+10:00" }, { "id": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e", "name": "IT Equipment Request", "status": "active", "form_type": "request_form", "description": "Request new equipment from the IT team.", "created_at": "2024-02-10T09:00:00+10:00", "updated_at": "2024-02-10T09:00:00+10:00", "board_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b", "board_name": "IT Support", "notification_policy": "each_response", "public_sharing_enabled": false, "public_url": null, "show_in_employee_file": true, "default_priority": "medium" } ], "page_index": 1, "item_per_page": 20, "total_items": 2, "total_pages": 1 }}This endpoint retrieves a single form, including its sections and questions. It works for both basic forms and request forms; check form_type to see which one was returned.
Request forms
For a request form the response includes the request-form fields (such as
board_id and notification_policy) and omits the fields that only apply to
basic forms (category_id, category_name, submission_policies and
employee_file_view_policies). The caller needs permission to manage request
forms, otherwise a 403 is returned.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_idPath Parameters
The ID of the organisation
The ID of the custom form to retrieve
Response Body
Unique identifier for the custom form.
The name of the custom form.
The current status of the custom form.
The type of the form. basic_form is a standard custom form; request_form is a request form managed from the Employment Hero platform.
Unique identifier of the category the form belongs to. Only present when form_type is basic_form.
The name of the category the form belongs to. Only present when form_type is basic_form.
A description of the custom form.
The date and time the form was created.
The date and time the form was last updated.
The ID of the request board that submitted requests are sent to. Only present when form_type is request_form.
The name of the request board that submitted requests are sent to. Only present when form_type is request_form.
When the handling team is notified about submitted requests. Only present when form_type is request_form.
Whether the request form can be submitted through a public link. Only present when form_type is request_form.
The path of the public submission link. null unless public_sharing_enabled is true. Only present when form_type is request_form.
Whether submitted requests appear in the employee file of the requester. Only present when form_type is request_form.
The priority given to requests submitted through this form by default. Only present when form_type is request_form.
Who is allowed to submit the form. Always includes self. Only present when form_type is basic_form.
Who can view the submitted response in the employee file. Only present when form_type is basic_form.
The sections and questions of the form.
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Employee Onboarding Checklist", "status": "active", "form_type": "basic_form", "category_id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "category_name": "HR", "description": "Standard onboarding form for new employees.", "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", "text": "What is your employment type?", "description": "", "type": "dropdown", "required": true, "key": "q-employment-type", "visibility_condition": null, "options": [ { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "text": "Full-time" }, { "id": "d4e5f6a7-b8c9-0123-def0-234567890123", "text": "Part-time" } ] }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "text": "How many hours per week?", "description": "", "type": "number", "required": false, "key": "q-weekly-hours", "visibility_condition": { "source_question_key": "q-employment-type", "operator": "equals", "value": "Part-time" } } ] } ] }}This endpoint creates a new custom form with its sections and questions. Forms are published immediately by default; set draft to true to save the form without publishing it.
Note
When publishing (draft is false), access is required. Drafts ignore
access and notification settings.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/formsPath Parameters
The ID of the organisation.
Request Body
The name of the form. Must be unique within the organisation (max 255 characters).
An optional description of the form.
The ID of the category to assign to this form. Must belong to the organisation.
When true, the form is created in draft state and is not published. When false (the default), the form is published immediately and access becomes required.
The sections of the form. At least one section is required.
Who the form is assigned to. Required when publishing (draft is false); ignored for drafts. Provide all_members, or any combination of the specific recipient lists.
The date when the form expires, in YYYY-MM-DD format. Must be in the future.
Who is notified that the form has been assigned to them when it is published.
The specific assignees to notify on publish. Required when assignees_notification_policy is specific. Must be a subset of access.
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 form in the employee file.
Response notification policies. Use this array form when configuring multiple notification triggers; it does not include none.
Recipients to notify about responses, grouped by type. Used together with notification_policies.
Draft versus published forms
Set draft to true to save the form without publishing it. Draft forms ignore access and notification settings.
To publish immediately, set draft to false (the default). When publishing, access (who receives the form) is required.
Response Body
Returns HTTP 201 Created with the full detail of the newly created form, including all sections and questions.
Unique identifier for the custom form.
The name of the custom form.
The current status of the custom form.
The type of the form. basic_form is a standard custom form; request_form is a request form managed from the Employment Hero platform.
Unique identifier of the category the form belongs to. Only present when form_type is basic_form.
The name of the category the form belongs to. Only present when form_type is basic_form.
A description of the custom form.
The date and time the form was created.
The date and time the form was last updated.
The ID of the request board that submitted requests are sent to. Only present when form_type is request_form.
The name of the request board that submitted requests are sent to. Only present when form_type is request_form.
When the handling team is notified about submitted requests. Only present when form_type is request_form.
Whether the request form can be submitted through a public link. Only present when form_type is request_form.
The path of the public submission link. null unless public_sharing_enabled is true. Only present when form_type is request_form.
Whether submitted requests appear in the employee file of the requester. Only present when form_type is request_form.
The priority given to requests submitted through this form by default. Only present when form_type is request_form.
Who is allowed to submit the form. Always includes self. Only present when form_type is basic_form.
Who can view the submitted response in the employee file. Only present when form_type is basic_form.
The sections and questions of the form.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/forms" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "name": "Employee Onboarding Checklist", "description": "Standard onboarding form for new employees.", "category_id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "draft": false, "sections": [ { "name": "Personal Details", "questions": [ { "text": "What is your employment type?", "type": "dropdown", "required": true, "key": "q-employment-type", "selection_options": [ { "text": "Full-time" }, { "text": "Part-time" } ] }, { "text": "How many hours per week?", "type": "number", "required": false, "key": "q-weekly-hours", "visibility_condition": { "source_question_key": "q-employment-type", "operator": "equals", "value": "Part-time" } } ] } ], "access": { "all_members": false, "employee_ids": [ "6664453a-c118-48f1-897e-3df62d45bd84" ] }, "assignees_notification_policy": "all", "submission_policies": [ "primary_manager" ], "employee_file_view_policies": [ "affected_employee", "primary_manager" ] }'Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Employee Onboarding Checklist", "status": "active", "form_type": "basic_form", "category_id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "category_name": "HR", "description": "Standard onboarding form for new employees.", "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", "text": "What is your employment type?", "description": "", "type": "dropdown", "required": true, "key": "q-employment-type", "visibility_condition": null, "options": [ { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "text": "Full-time" }, { "id": "d4e5f6a7-b8c9-0123-def0-234567890123", "text": "Part-time" } ] }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "text": "How many hours per week?", "description": "", "type": "number", "required": false, "key": "q-weekly-hours", "visibility_condition": { "source_question_key": "q-employment-type", "operator": "equals", "value": "Part-time" } } ] } ] }}This endpoint updates an existing form. All fields are optional — only the fields you provide are changed. Note that including sections replaces the form's entire section and question structure.
Request forms
Request forms cannot be changed through the API. Calling this endpoint for a
request form returns a 422 error: This form is a request form, and cannot be updated via API.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_idPath Parameters
The ID of the organisation the form belongs to.
The ID of the form to update.
Request Body
The name of the form. Must be unique within the organisation (max 255 characters).
A description of the form.
The ID of the category to assign to this form. Must belong to the organisation.
The sections of the form. Draft forms only — returns 422 if the form is active, completed, or archived. 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 form in the employee file. Pass an empty array to clear all policies.
Response notification policies. Pass an empty array to disable response notifications.
Recipients to notify about responses, grouped by type. Used together with notification_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.
Response Body
Returns the full updated form, including all sections and questions.
Unique identifier for the custom form.
The name of the custom form.
The current status of the custom form.
The type of the form. basic_form is a standard custom form; request_form is a request form managed from the Employment Hero platform.
Unique identifier of the category the form belongs to. Only present when form_type is basic_form.
The name of the category the form belongs to. Only present when form_type is basic_form.
A description of the custom form.
The date and time the form was created.
The date and time the form was last updated.
The ID of the request board that submitted requests are sent to. Only present when form_type is request_form.
The name of the request board that submitted requests are sent to. Only present when form_type is request_form.
When the handling team is notified about submitted requests. Only present when form_type is request_form.
Whether the request form can be submitted through a public link. Only present when form_type is request_form.
The path of the public submission link. null unless public_sharing_enabled is true. Only present when form_type is request_form.
Whether submitted requests appear in the employee file of the requester. Only present when form_type is request_form.
The priority given to requests submitted through this form by default. Only present when form_type is request_form.
Who is allowed to submit the form. Always includes self. Only present when form_type is basic_form.
Who can view the submitted response in the employee file. Only present when form_type is basic_form.
The sections and questions of the form.
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "name": "Employee Onboarding Checklist", "sections": [ { "name": "Personal Details", "questions": [ { "text": "What is your employment type?", "type": "dropdown", "required": true, "key": "q-employment-type", "selection_options": [ { "text": "Full-time" }, { "text": "Part-time" } ] }, { "text": "How many hours per week?", "type": "number", "required": false, "key": "q-weekly-hours", "visibility_condition": { "source_question_key": "q-employment-type", "operator": "equals", "value": "Part-time" } } ] } ], "submission_policies": [ "primary_manager" ] }'Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Employee Onboarding Checklist", "status": "active", "form_type": "basic_form", "category_id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "category_name": "HR", "description": "Standard onboarding form for new employees.", "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", "text": "What is your employment type?", "description": "", "type": "dropdown", "required": true, "key": "q-employment-type", "visibility_condition": null, "options": [ { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "text": "Full-time" }, { "id": "d4e5f6a7-b8c9-0123-def0-234567890123", "text": "Part-time" } ] }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "text": "How many hours per week?", "description": "", "type": "number", "required": false, "key": "q-weekly-hours", "visibility_condition": { "source_question_key": "q-employment-type", "operator": "equals", "value": "Part-time" } } ] } ] }}This endpoint permanently deletes a form along with all of its associated data.
Note
This action cannot be undone. Only draft and active forms that have no
submitted responses can be deleted. Forms in completed or archived status,
or forms that already have responses, cannot be deleted.
Request forms
Request forms cannot be changed through the API. Calling this endpoint for a
request form returns a 422 error: This form is a request form, and cannot be updated via API.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_idPath Parameters
The ID of the organisation the form belongs to.
The ID of the form to delete. Only draft and active forms that have no submitted responses can be deleted; completed and archived forms, or forms with responses, cannot.
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/forms/:form_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
This endpoint does not return a response body.
Publishes a draft form, transitioning it from draft to active. Publishing grants access to the employees, contractors, teams, and/or work locations specified in access, and can optionally configure submission-notification routing in the same call.
Note
Only forms in draft status can be published. Publishing a form that is
already active, completed, or archived returns a 422 error.
Request forms
Request forms cannot be changed through the API. Calling this endpoint for a
request form returns a 422 error: This form is a request form, and cannot be updated via API.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_id/publishPath Parameters
The ID of the organisation the form belongs to.
The ID of the form to publish. The form must currently be in draft status.
Request Body
Who is granted access to the form. Must specify all_members: true, or at least one of employee_ids, contractor_ids, group_ids, work_location_ids.
Give every employee and contractor in the organisation access to the form.
Employee UUIDs to grant access to.
Contractor UUIDs to grant access to.
Group UUIDs to grant access to.
Work location UUIDs to grant access to.
Who to notify that the form has been assigned to them.
Who to notify when assignees_notification_policy is specific. Required in that case, and must be a subset of access.
The date access to the form ends, in YYYY-MM-DD format. Cannot be in the past.
Submission notification routing policies — when to notify recipients of a form submission. Omit to leave any existing routing configuration unchanged, or pass [] to explicitly clear it.
Who receives submission notifications.
Response Body
Returns the form with status set to active on success.
Unique identifier for the custom form.
The name of the custom form.
The current status of the custom form.
The type of the form. basic_form is a standard custom form; request_form is a request form managed from the Employment Hero platform.
Unique identifier of the category the form belongs to. Only present when form_type is basic_form.
The name of the category the form belongs to. Only present when form_type is basic_form.
A description of the custom form.
The date and time the form was created.
The date and time the form was last updated.
The ID of the request board that submitted requests are sent to. Only present when form_type is request_form.
The name of the request board that submitted requests are sent to. Only present when form_type is request_form.
When the handling team is notified about submitted requests. Only present when form_type is request_form.
Whether the request form can be submitted through a public link. Only present when form_type is request_form.
The path of the public submission link. null unless public_sharing_enabled is true. Only present when form_type is request_form.
Whether submitted requests appear in the employee file of the requester. Only present when form_type is request_form.
The priority given to requests submitted through this form by default. Only present when form_type is request_form.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_id/publish" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "access": { "employee_ids": [ "0139ebb7-6f3e-4bc0-954e-9e50614fccd1" ] }, "assignees_notification_policy": "specific", "assignees_notification_list": { "employee_ids": [ "0139ebb7-6f3e-4bc0-954e-9e50614fccd1" ] }, "end_date": "2026-12-31", "notification_policies": [ "each_response", "daily_summary" ], "notification_recipients": { "member_ids": [ "3f7f1c8d-2f0a-4d3c-9c7c-2ecb1d3d1c7b" ], "roles": [ "admins_owners" ] } }'Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Employee Onboarding Checklist", "status": "active", "form_type": "basic_form", "category_id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "category_name": "HR", "description": "Standard onboarding form for new employees.", "created_at": "2024-01-15T09:00:00+10:00", "updated_at": "2024-03-20T14:30:00+10:00" }}Assigns an active form to the specified employees, contractors, teams, and/or work locations as a to-do task, creating a completion request for each assignee. Optionally notify assignees by email that the form has been assigned to them.
Note
Only forms in active status can be assigned. Assigning a form that is
draft, completed, or archived returns a 422 error.
Request forms
Request forms cannot be changed through the API. Calling this endpoint for a
request form returns a 422 error: This form is a request form, and cannot be updated via API.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_id/assignPath Parameters
The ID of the organisation the form belongs to.
The ID of the form to assign. The form must currently be in active status.
Request Body
Who to create a to-do assignment for. Must specify all_members: true, or at least one of employee_ids, contractor_ids, group_ids, work_location_ids.
Assign every employee and contractor in the organisation.
Employee UUIDs to assign.
Contractor UUIDs to assign.
Group UUIDs to assign.
Work location UUIDs to assign.
Who to notify that the form has been assigned to them.
Response Body
Returns HTTP 200 OK on success.
Indicates the assignment was created successfully.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_id/assign" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "assignees": { "employee_ids": [ "0139ebb7-6f3e-4bc0-954e-9e50614fccd1" ] }, "assignees_notification_policy": "all" }'Response
{ "data": { "success": true }}Closes an active form, stopping it from accepting new submissions. Existing responses are preserved.
Note
Only forms in active status can be closed. Closing a form that is draft,
completed, or archived returns a 422 error.
Request forms
Request forms cannot be changed through the API. Calling this endpoint for a
request form returns a 422 error: This form is a request form, and cannot be updated via API.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_id/closePath Parameters
The ID of the organisation the form belongs to.
The ID of the form to close. The form must currently be in active status.
Response Body
Returns HTTP 200 OK on success.
Indicates the form was closed successfully.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_id/close" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "success": true }}Archives an active or completed form, moving it out of the active lifecycle while preserving all existing responses.
Note
Only forms in active or completed status with at least one response can be
archived. Archiving a draft or already-archived form, or a form with zero
responses, returns a 422 error.
Request forms
Request forms cannot be changed through the API. Calling this endpoint for a
request form returns a 422 error: This form is a request form, and cannot be updated via API.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_id/archivePath Parameters
The ID of the organisation the form belongs to.
The ID of the form to archive. The form must currently be in active or completed status, and have at least one response.
Response Body
Returns HTTP 200 OK on success.
Indicates the form was archived successfully.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_id/archive" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "success": true }}This endpoint retrieves a paginated list of received responses for a form. It works for both basic forms and request forms; each response includes a form_type field.
Request forms
Responses to a request form can be listed only by callers with permission to manage request forms.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_id/responsesPath Parameters
The ID of the organisation
The ID of the custom form
Query Parameters
Filter by approval status
Filter by the UUID of the member who submitted the response
Return responses submitted at or after this time
Return responses submitted at or before this time
Current page index
11Number of items per page
20100Response Body
Unique identifier for the form response.
The ID of the custom form this response belongs to.
The ID of the member the response is about (the affected employee).
The ID of the member who submitted the response. May differ from member_id when submitted on behalf of another member.
The approval status of the response.
The date and time the response was submitted.
The type of the form this response belongs to: basic_form or request_form.
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/forms/:form_id/responses" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "form_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "member_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "submitter_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "status": "approved", "submitted_at": "2024-04-01T10:00:00+10:00", "form_type": "basic_form" } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}This endpoint retrieves a single form response, including all submitted answers. The response includes a form_type field showing whether it belongs to a basic form or a request form.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_id/responses/:response_idPath Parameters
The ID of the organisation
The ID of the custom form
The ID of the form response to retrieve
Response Body
Unique identifier for the form response.
The ID of the custom form this response belongs to.
The ID of the member the response is about (the affected employee).
The ID of the member who submitted the response. May differ from member_id when submitted on behalf of another member.
The approval status of the response.
The date and time the response was submitted.
The type of the form this response belongs to: basic_form or request_form.
The answers for all questions in the form. Includes empty answers for unanswered questions.
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_id/responses/:response_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "form_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "member_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "submitter_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "status": "approved", "submitted_at": "2024-04-01T10:00:00+10:00", "form_type": "basic_form", "answers": [ { "question_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "text": "What is your full name?", "description": "Please enter your legal full name.", "question_type": "short_text", "answer_value": [ "Jane Smith" ] }, { "question_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "text": "Please sign to acknowledge", "description": "", "question_type": "signature", "signed": true }, { "question_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "text": "Employment type", "description": "", "question_type": "dropdown", "answer_value": [] }, { "question_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "text": "Start date", "description": "", "question_type": "date", "answer_value": [ "2026-05-08" ] }, { "question_id": "e5f6a7b8-c9d0-1234-ef01-345678901234", "text": "Interview time", "description": "", "question_type": "date_time", "answer_value": [ "2026-05-08T09:30:00+10:00" ] }, { "question_id": "f6a7b8c9-d0e1-2345-f012-456789012345", "text": "Upload your resume", "description": "", "question_type": "file_upload", "answer_value": [ "https://files.cdn.ehrocks.com/private/resume.pdf?Expires=1778585222&Signature=example&Key-Pair-Id=K1RS1L24D262S5" ] } ] }}This endpoint approves a pending form response.
Request forms
Request forms cannot be changed through the API. Calling this endpoint for a
request form returns a 422 error: This form is a request form, and cannot be updated via API.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_id/responses/:response_id/approvePath Parameters
The ID of the organisation
The ID of the custom form
The ID of the form response to approve
Response Body
Returns a 200 status on successful approval. Returns 404 if the response is not found, 403 if approval is forbidden, or 422 if the response is not pending.
Indicates if the response was successfully approved
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_id/responses/:response_id/approve" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "success": true }}This endpoint declines a pending form response with a reason.
Request forms
Request forms cannot be changed through the API. Calling this endpoint for a
request form returns a 422 error: This form is a request form, and cannot be updated via API.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_id/responses/:response_id/declinePath Parameters
The ID of the organisation
The ID of the custom form
The ID of the form response to decline
Request Body
The reason the response is being declined
Response Body
Returns a 200 status on successful decline. Returns 404 if the response is not found, 403 if decline is forbidden, 400 if reason is missing, or 422 if the response is not pending.
Indicates if the response was successfully declined
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_id/responses/:response_id/decline" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "reason": "Does not meet requirements" }'Response
{ "data": { "success": true }}This endpoint retrieves a paginated list of members assigned to a specific form along with their completion status.
Request forms
Request forms do not have form assignments. Calling this endpoint for a
request form returns a 422 error: This form is a request form, and does not have form assignments.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/forms/:form_id/assignmentsPath Parameters
The ID of the organisation
The ID of the form
Query Parameters
Filter assignments by completion status. Multiple values can be provided.
Current page index
11Number of items per page
20100Response Body
A paginated list of members assigned to the form along with their completion status.
Unique identifier for the member.
Full name of the member.
The date and time the form was assigned to the member.
The completion status of the form assignment.
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/forms/:form_id/assignments" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "member_id": "6664453a-c118-48f1-897e-3df62d45bd84", "member_name": "John Doe", "assigned_at": "2024-03-15T09:00:00+10:00", "status": "completed" }, { "member_id": "b992fc49-7e98-4743-b53b-51bec9cf4dc3", "member_name": "Jane Smith", "assigned_at": "2024-03-16T10:30:00+10:00", "status": "pending" } ], "page_index": 1, "item_per_page": 20, "total_items": 2, "total_pages": 1 }}This endpoint retrieves a paginated list of form responses for a specific member, covering both basic forms and request forms. Each item includes a form_type field, and the form_type query parameter limits the results to one type.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/members/:member_id/form_responsesPath Parameters
The ID of the organisation
The ID of the member
Query Parameters
Filter by approval statuses. Multiple values can be provided.
Return responses submitted on or after this date (YYYY-MM-DD)
Return responses submitted on or before this date (YYYY-MM-DD)
Filter responses by the type of the form they belong to.
Sort order for the results. Prefix with - for descending order.
Current page index
11Number of items per page
20100Response Body
A paginated list of form responses submitted by or about the specified member.
The ID of the custom form.
The name of the custom form.
The type of the form: basic_form or request_form.
The ID of the form response.
The approval status of the form response.
The date and time the response was submitted (RFC3339).
The date and time the response was last updated (RFC3339).
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/members/:member_id/form_responses" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "form_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "form_name": "Employee Onboarding Checklist", "form_type": "basic_form", "response_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "status": "submitted", "submitted_at": "2024-04-01T10:00:00+10:00", "updated_at": "2024-04-01T10:00:00+10:00" } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}