Toolbox
Toolbox Object
| Field | Type | Description |
|---|---|---|
| id | snowflake | the toolbox's id |
| organisation_id | snowflake | the id of the organisation |
| workgroup_id | snowflake? | the id of the workgroup this toolbox belongs to, or null |
| workgroup | workgroup object | the workgroup (full object or partial with only id) |
| totp_token | string? | one-time password token for QR sign-in flow (only included when requested) |
| sign_token | string? | a JWT token used to sign the toolbox |
| is_template | boolean | whether this toolbox is a template |
| location_id | snowflake? | the id of the location where the toolbox was conducted |
| location | location object | the location (full object or partial with only id) |
| latitude | double? | the latitude where the toolbox was conducted |
| longitude | double? | the longitude where the toolbox was conducted |
| title | string | the title of the toolbox |
| sections | array<toolbox section> | array of sections in this toolbox |
| topics | array<toolbox topic> | array of top-level topics (those not belonging to a section) |
| users | array<toolbox user> | array of users who signed this toolbox |
| archived | boolean | whether the toolbox has been archived |
| conducted_at | ISO8601 timestamp? | when the toolbox was conducted |
| conducted_by | user object | the user who conducted the toolbox (full object or partial with only id) |
| archived_at | ISO8601 timestamp? | when the toolbox was archived |
| archived_by | user object | the user who archived the toolbox (partial with only id) |
| created_at | ISO8601 timestamp | when the toolbox was created |
| created_by | user object | the user who created the toolbox (partial with only id) |
| updated_at | ISO8601 timestamp | when the toolbox was last updated |
| updated_by | user object | the user who last updated the toolbox (partial with only id) |
| schedules | array<toolbox schedule>? | array of schedules associated with this toolbox, or null |
Toolbox Section Object
| Field | Type | Description |
|---|---|---|
| id | snowflake | the section's id |
| organisation_id | snowflake | the id of the organisation |
| toolbox_id | snowflake | the id of the toolbox this section belongs to |
| title | string | title of the section |
| order | integer | the order of the section within the toolbox |
| topics | array<toolbox topic> | array of topics in this section |
| created_at | ISO8601 timestamp | when the section was created |
| created_by | user object | the user who created the section (partial with only id) |
| updated_at | ISO8601 timestamp | when the section was last updated |
| updated_by | user object | the user who last updated the section (partial with only id) |
Toolbox Topic Object
| Field | Type | Description |
|---|---|---|
| id | snowflake | the topic's id |
| organisation_id | snowflake | the id of the organisation |
| toolbox_id | snowflake | the id of the toolbox this topic belongs to |
| section_id | snowflake? | the id of the toolbox section this topic belongs to, or null if top-level |
| body | string | the content of the topic |
| comments | string | comments on the topic |
| review_response | boolean? | the reviewer's response to the topic |
| order | integer | the order of the topic within its section or toolbox |
| reviewed_at | ISO8601 timestamp? | when the topic was reviewed |
| reviewed_by | user object | the user who reviewed the topic (partial with only id) |
| created_at | ISO8601 timestamp | when the topic was created |
| created_by | user object | the user who created the topic (partial with only id) |
| updated_at | ISO8601 timestamp | when the topic was last updated |
| updated_by | user object | the user who last updated the topic (partial with only id) |
Toolbox User Object
| Field | Type | Description |
|---|---|---|
| id | snowflake | the toolbox user's id |
| toolbox_id | snowflake | the id of the toolbox |
| user_id | snowflake? | the id of the user that signed the toolbox, or null if not a registered user |
| user | user object? | the user that signed the toolbox, or null if not a registered user |
| first_name | string | the first name supplied when the toolbox was signed |
| last_name | string | the last name supplied when the toolbox was signed |
| string | the e-mail supplied when the toolbox was signed | |
| phone_number | string? | the phone number supplied when the toolbox was signed |
| company | string | the company name supplied when the toolbox was signed |
| position | string | the position supplied when the toolbox was signed |
| signature | string? | the user's signature as an SVG string, or null |
| signed_at | ISO8601 timestamp | when the toolbox was signed |
| signed_method | toolbox signature method | the method used to sign the toolbox |
Toolbox Signature Methods
| Value | Name | Description |
|---|---|---|
| declaration | Declaration | A declaration is made where there is no evidence |
| signature | Signature | The user's signature provided as evidence |
| toolbox_qr | Scanned Toolbox's QR Code | The user scanned a QR code with their app as evidence |
| user_qr | Scanned User's QR Code | Scanned the user's QR code as evidence |
| app | Self-Service App | The user signed via a notification on their own device |
Toolbox User Response Object
| Field | Type | Description |
|---|---|---|
| response_code | toolbox user response code | the result code of the sign operation |
| message | string | a human-readable message describing the result |
| toolbox_id | snowflake? | the id of the toolbox, or null |
| schedule_id | snowflake? | the id of the work item schedule associated with the sign, or null |
| user_id | snowflake? | the id of the user, or null |
| string? | the e-mail of the user, or null | |
| phone_number | string? | the phone number of the user, or null |
| first_name | string | the first name of the user |
| last_name | string | the last name of the user |
| company | string? | the company of the user, or null |
| position | string? | the position of the user, or null |
| signed_at | ISO8601 timestamp? | when the toolbox was signed, or null |
| signed_method | toolbox signature method? | the method used to sign the toolbox, or null |
Toolbox User Response Codes
| Value | Description |
|---|---|
| toolbox_signed | The toolbox was successfully signed |
| confirm_details | The user must confirm or provide additional details |
| missing_declaration | A declaration or signature is required |
| user_not_invited | The user has not been invited to the schedule |
| user_not_checked_in | The user has not checked in for the schedule |
Toolbox Schedule Object
| Field | Type | Description |
|---|---|---|
| id | snowflake | the schedule's id |
| toolbox_id | snowflake | the id of the toolbox this schedule belongs to |
| scheduled_start_at | ISO8601 timestamp | the time the toolbox schedule is set to start |
| scheduled_finish_at | ISO8601 timestamp | the time the toolbox schedule is set to finish |
| actual_start_at | ISO8601 timestamp? | the time the toolbox schedule actually started, or null |
| actual_finish_at | ISO8601 timestamp? | the time the toolbox schedule actually finished, or null |
Create Toolbox
POST /organisations/{organisation.id}/toolboxes
Creates a new toolbox in the organisation. Optionally copies sections and topics from an existing template toolbox, or associates the new toolbox with a work item schedule. Requires membership in the organisation.
Returns a 201 Created response with the new toolbox object.
JSON Params
| Field | Type | Description | Default |
|---|---|---|---|
| title | string | the title of the toolbox | |
| is_template | boolean | whether this toolbox is a template | false |
| location_id | snowflake? | the id of the location where the toolbox will be conducted; must belong to the same organisation | null |
| workgroup_id | snowflake? | the id of the workgroup this toolbox belongs to; must belong to the same organisation | null |
| schedule_id | snowflake? | the id of the work item schedule to associate with the toolbox; must not already have a toolbox | null |
| template_id | snowflake? | the id of an existing toolbox to use as a template; sections and topics will be copied | null |
Notes
- If
template_idis provided, all sections and topics from the template are copied to the new toolbox. - If
schedule_idis provided, the schedule must not already be associated with another toolbox.
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (invalid organisation, location, workgroup, schedule, or template) |
| 403 | Forbidden (caller is not a member of the organisation) |
List Toolboxes
GET /organisations/{organisation.id}/toolboxes
Returns an array of toolbox objects for the organisation. Requires membership in the organisation.
All filters and pagination parameters for this method are optional.
Filters
| Field | Type | Description |
|---|---|---|
| is_template | ?boolean | when set, only toolboxes matching this template status are returned |
| title | ?string | filter toolboxes by title (case-insensitive) |
| location | ?string | filter toolboxes by location id |
| workgroup | ?string | filter toolboxes by workgroup id |
| archived | ?boolean | when set, only toolboxes matching this archived status are returned |
Pagination
| Field | Type | Description | Default |
|---|---|---|---|
| start | ?integer | the offset of the first result to return | 0 |
| limit | ?integer | the maximum number of results to return | 50 |
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (organisation not found) |
| 403 | Forbidden (caller is not a member of the organisation) |
Get Toolbox
GET /toolboxes/{toolbox.id}
Returns the toolbox object for the given toolbox id. The response includes toolbox sections, toolbox topics, toolbox users, and toolbox schedules. Requires membership in the organisation that owns the toolbox.
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (invalid toolbox or organisation) |
| 403 | Forbidden (caller is not a member of the organisation) |
| 404 | Not found (toolbox does not exist) |
Update Toolbox
PATCH /toolboxes/{toolbox.id}
Partially update a toolbox. Only the fields provided will be updated. Requires membership in the organisation that owns the toolbox. Archived toolboxes cannot be updated.
JSON Params
| Field | Type | Description |
|---|---|---|
| title | string | the title of the toolbox |
| is_template | boolean | whether this toolbox is a template |
| location_id | snowflake? | the id of the location where the toolbox was conducted; must belong to the same organisation |
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (invalid input, missing organisation, or location not found) |
| 403 | Forbidden (toolbox is archived or insufficient permissions) |
| 404 | Not found (toolbox does not exist) |
Conduct Toolbox
POST /toolboxes/{toolbox.id}/conduct
Marks the toolbox as conducted, recording the conductor's GPS coordinates and timestamp. Requires membership in the organisation that owns the toolbox. A toolbox can only be conducted once and cannot be conducted if it is archived.
JSON Params
| Field | Type | Description |
|---|---|---|
| latitude | double | the latitude where the toolbox was conducted |
| longitude | double | the longitude where the toolbox was conducted |
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (invalid toolbox or organisation) |
| 403 | Forbidden (toolbox is archived, already conducted, or insufficient permissions) |
| 404 | Not found (toolbox does not exist) |
Archive Toolbox
POST /toolboxes/{toolbox.id}/archive
Archives the toolbox. Archived toolboxes cannot be edited. Requires membership in the organisation that owns the toolbox.
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (invalid toolbox or organisation) |
| 403 | Forbidden (toolbox is already archived or insufficient permissions) |
| 404 | Not found (toolbox does not exist) |
Unarchive Toolbox
POST /toolboxes/{toolbox.id}/unarchive
Restores an archived toolbox. Toolboxes can only be unarchived within 24 hours of being archived. Requires membership in the organisation that owns the toolbox.
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (invalid toolbox or organisation) |
| 403 | Forbidden (toolbox is not archived, archived longer than 24 hours ago, or insufficient permissions) |
| 404 | Not found (toolbox does not exist) |
Create Toolbox Section
POST /toolboxes/{toolbox.id}/sections
Creates a new toolbox section in the toolbox. The section is appended at the end of the existing sections. Requires membership in the organisation that owns the toolbox. Archived toolboxes cannot have sections added.
Returns a 201 Created response with the new toolbox section object.
JSON Params
| Field | Type | Description |
|---|---|---|
| title | string | the title of the section |
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (invalid toolbox or organisation) |
| 403 | Forbidden (toolbox is archived or insufficient permissions) |
| 404 | Not found (toolbox does not exist) |
Get Toolbox Section
GET /toolboxes/{toolbox.id}/sections/{section.id}
Returns the toolbox section object for the given section id. The response includes an array of toolbox topics belonging to the section. Requires membership in the organisation that owns the toolbox.
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (invalid section or organisation) |
| 403 | Forbidden (caller is not a member of the organisation) |
| 404 | Not found (section does not exist) |
Update Toolbox Section
PATCH /toolboxes/{toolbox.id}/sections/{section.id}
Updates a toolbox section. Only the fields provided will be updated. Requires membership in the organisation that owns the toolbox. Archived toolboxes cannot have sections updated.
JSON Params
| Field | Type | Description |
|---|---|---|
| title | string | the title of the section |
| order | integer | the new order of the section within the toolbox; other sections will be re-ordered accordingly |
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (invalid toolbox, section, or organisation) |
| 403 | Forbidden (toolbox is archived or insufficient permissions) |
| 404 | Not found (section does not exist) |
Remove Toolbox Section
DELETE /toolboxes/{toolbox.id}/sections/{section.id}
Removes a toolbox section. Only empty sections (those with no topics) can be removed. Requires membership in the organisation that owns the toolbox. Archived toolboxes cannot have sections removed.
Returns a 200 OK response on success.
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (invalid toolbox, section, organisation, or section is not empty) |
| 403 | Forbidden (toolbox is archived or insufficient permissions) |
| 404 | Not found (section does not exist) |
Create Toolbox Topic
POST /toolboxes/{toolbox.id}/topics
Creates a new toolbox topic in the toolbox. The topic is appended at the end of the existing topics within its section (or at the toolbox level if no section is specified). Requires membership in the organisation that owns the toolbox. Archived toolboxes cannot have topics added.
Returns a 201 Created response with the new toolbox topic object.
JSON Params
| Field | Type | Description |
|---|---|---|
| section_id | snowflake? | the id of the toolbox section this topic belongs to, or null for a top-level topic |
| body | string? | the content of the topic (default empty string) |
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (invalid toolbox, organisation, or section) |
| 403 | Forbidden (toolbox is archived or insufficient permissions) |
| 404 | Not found (toolbox does not exist) |
Get Toolbox Topic
GET /toolboxes/{toolbox.id}/topics/{topic.id}
Returns the toolbox topic object for the given topic id. Requires membership in the organisation that owns the toolbox.
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (invalid topic or organisation) |
| 403 | Forbidden (caller is not a member of the organisation) |
| 404 | Not found (topic does not exist) |
Update Toolbox Topic
PATCH /toolboxes/{toolbox.id}/topics/{topic.id}
Updates a toolbox topic. Only the fields provided will be updated. Requires membership in the organisation that owns the toolbox. Archived toolboxes cannot have topics updated.
JSON Params
| Field | Type | Description |
|---|---|---|
| section_id | snowflake? | the id of the toolbox section to move the topic to, or null for a top-level topic |
| body | string? | the content of the topic |
| comments | string? | comments on the topic |
| review_response | boolean? | the reviewer's response to the topic |
| order | integer | the new order of the topic within its section or toolbox; other topics will be re-ordered accordingly |
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (invalid toolbox, topic, section, or organisation) |
| 403 | Forbidden (toolbox is archived or insufficient permissions) |
| 404 | Not found (topic does not exist) |
Remove Toolbox Topic
DELETE /toolboxes/{toolbox.id}/topics/{topic.id}
Removes a toolbox topic. Requires membership in the organisation that owns the toolbox. Archived toolboxes cannot have topics removed.
Returns a 200 OK response on success.
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (invalid toolbox, topic, or organisation) |
| 403 | Forbidden (toolbox is archived or insufficient permissions) |
| 404 | Not found (topic does not exist) |
Sign Toolbox
POST /toolboxes/{toolbox.id}/sign
Records a signature (attendance) for the toolbox. The caller may sign on behalf of a user by providing their details, or sign using their own account. The toolbox must have been conducted before it can be signed. If the toolbox is associated with a work item schedule, the user must be invited to and checked in for that schedule.
Returns a toolbox user response indicating the result of the operation. If the response code is confirm_details, the caller should collect the missing information and retry.
JSON Params
| Field | Type | Description |
|---|---|---|
| user_id | snowflake? | the id of an existing user to sign as |
| string? | the e-mail of the person signing; used to look up an existing user | |
| phone_number | string? | the phone number of the person signing |
| first_name | string? | the first name of the person signing |
| last_name | string? | the last name of the person signing |
| company | string? | the company of the person signing |
| position | string? | the position of the person signing |
| schedule_id | snowflake? | the id of the work item schedule to associate with the sign; if null, signs for the toolbox directly |
| declaration | boolean? | confirmation that the information provided is true |
| signature | string? | the person's signature as an SVG string |
| user_qr_code | string? | a one-time QR code token scanned from the user's device |
| scanned_at | string? | the ISO8601 timestamp when the QR code was scanned (must be within the last 24 hours) |
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (invalid toolbox, organisation, schedule, user details, signature format, or missing declaration) |
| 403 | Forbidden (toolbox is archived, not yet conducted, or insufficient permissions) |
| 404 | Not found (toolbox does not exist) |
Download Toolbox Report
GET /toolboxes/{toolbox.id}/report
Generates and downloads a DOCX report for the toolbox. The report includes the toolbox header, all sections and topics with review responses and comments, and an attendance table with signatures. Requires membership in the organisation that owns the toolbox.
Returns a 200 OK response with Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document.
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (invalid toolbox or organisation) |
| 403 | Forbidden (caller is not a member of the organisation) |
| 404 | Not found (toolbox does not exist) |