Skip to main content

Toolbox

Toolbox Object

FieldTypeDescription
idsnowflakethe toolbox's id
organisation_idsnowflakethe id of the organisation
workgroup_idsnowflake?the id of the workgroup this toolbox belongs to, or null
workgroupworkgroup objectthe workgroup (full object or partial with only id)
totp_tokenstring?one-time password token for QR sign-in flow (only included when requested)
sign_tokenstring?a JWT token used to sign the toolbox
is_templatebooleanwhether this toolbox is a template
location_idsnowflake?the id of the location where the toolbox was conducted
locationlocation objectthe location (full object or partial with only id)
latitudedouble?the latitude where the toolbox was conducted
longitudedouble?the longitude where the toolbox was conducted
titlestringthe title of the toolbox
sectionsarray<toolbox section>array of sections in this toolbox
topicsarray<toolbox topic>array of top-level topics (those not belonging to a section)
usersarray<toolbox user>array of users who signed this toolbox
archivedbooleanwhether the toolbox has been archived
conducted_atISO8601 timestamp?when the toolbox was conducted
conducted_byuser objectthe user who conducted the toolbox (full object or partial with only id)
archived_atISO8601 timestamp?when the toolbox was archived
archived_byuser objectthe user who archived the toolbox (partial with only id)
created_atISO8601 timestampwhen the toolbox was created
created_byuser objectthe user who created the toolbox (partial with only id)
updated_atISO8601 timestampwhen the toolbox was last updated
updated_byuser objectthe user who last updated the toolbox (partial with only id)
schedulesarray<toolbox schedule>?array of schedules associated with this toolbox, or null

Toolbox Section Object

FieldTypeDescription
idsnowflakethe section's id
organisation_idsnowflakethe id of the organisation
toolbox_idsnowflakethe id of the toolbox this section belongs to
titlestringtitle of the section
orderintegerthe order of the section within the toolbox
topicsarray<toolbox topic>array of topics in this section
created_atISO8601 timestampwhen the section was created
created_byuser objectthe user who created the section (partial with only id)
updated_atISO8601 timestampwhen the section was last updated
updated_byuser objectthe user who last updated the section (partial with only id)

Toolbox Topic Object

FieldTypeDescription
idsnowflakethe topic's id
organisation_idsnowflakethe id of the organisation
toolbox_idsnowflakethe id of the toolbox this topic belongs to
section_idsnowflake?the id of the toolbox section this topic belongs to, or null if top-level
bodystringthe content of the topic
commentsstringcomments on the topic
review_responseboolean?the reviewer's response to the topic
orderintegerthe order of the topic within its section or toolbox
reviewed_atISO8601 timestamp?when the topic was reviewed
reviewed_byuser objectthe user who reviewed the topic (partial with only id)
created_atISO8601 timestampwhen the topic was created
created_byuser objectthe user who created the topic (partial with only id)
updated_atISO8601 timestampwhen the topic was last updated
updated_byuser objectthe user who last updated the topic (partial with only id)

Toolbox User Object

FieldTypeDescription
idsnowflakethe toolbox user's id
toolbox_idsnowflakethe id of the toolbox
user_idsnowflake?the id of the user that signed the toolbox, or null if not a registered user
useruser object?the user that signed the toolbox, or null if not a registered user
first_namestringthe first name supplied when the toolbox was signed
last_namestringthe last name supplied when the toolbox was signed
emailstringthe e-mail supplied when the toolbox was signed
phone_numberstring?the phone number supplied when the toolbox was signed
companystringthe company name supplied when the toolbox was signed
positionstringthe position supplied when the toolbox was signed
signaturestring?the user's signature as an SVG string, or null
signed_atISO8601 timestampwhen the toolbox was signed
signed_methodtoolbox signature methodthe method used to sign the toolbox
Toolbox Signature Methods
ValueNameDescription
declarationDeclarationA declaration is made where there is no evidence
signatureSignatureThe user's signature provided as evidence
toolbox_qrScanned Toolbox's QR CodeThe user scanned a QR code with their app as evidence
user_qrScanned User's QR CodeScanned the user's QR code as evidence
appSelf-Service AppThe user signed via a notification on their own device

Toolbox User Response Object

FieldTypeDescription
response_codetoolbox user response codethe result code of the sign operation
messagestringa human-readable message describing the result
toolbox_idsnowflake?the id of the toolbox, or null
schedule_idsnowflake?the id of the work item schedule associated with the sign, or null
user_idsnowflake?the id of the user, or null
emailstring?the e-mail of the user, or null
phone_numberstring?the phone number of the user, or null
first_namestringthe first name of the user
last_namestringthe last name of the user
companystring?the company of the user, or null
positionstring?the position of the user, or null
signed_atISO8601 timestamp?when the toolbox was signed, or null
signed_methodtoolbox signature method?the method used to sign the toolbox, or null
Toolbox User Response Codes
ValueDescription
toolbox_signedThe toolbox was successfully signed
confirm_detailsThe user must confirm or provide additional details
missing_declarationA declaration or signature is required
user_not_invitedThe user has not been invited to the schedule
user_not_checked_inThe user has not checked in for the schedule

Toolbox Schedule Object

FieldTypeDescription
idsnowflakethe schedule's id
toolbox_idsnowflakethe id of the toolbox this schedule belongs to
scheduled_start_atISO8601 timestampthe time the toolbox schedule is set to start
scheduled_finish_atISO8601 timestampthe time the toolbox schedule is set to finish
actual_start_atISO8601 timestamp?the time the toolbox schedule actually started, or null
actual_finish_atISO8601 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
FieldTypeDescriptionDefault
titlestringthe title of the toolbox
is_templatebooleanwhether this toolbox is a templatefalse
location_idsnowflake?the id of the location where the toolbox will be conducted; must belong to the same organisationnull
workgroup_idsnowflake?the id of the workgroup this toolbox belongs to; must belong to the same organisationnull
schedule_idsnowflake?the id of the work item schedule to associate with the toolbox; must not already have a toolboxnull
template_idsnowflake?the id of an existing toolbox to use as a template; sections and topics will be copiednull
Notes
  • If template_id is provided, all sections and topics from the template are copied to the new toolbox.
  • If schedule_id is provided, the schedule must not already be associated with another toolbox.
Error Responses
Status CodeDescription
400Bad request (invalid organisation, location, workgroup, schedule, or template)
403Forbidden (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
FieldTypeDescription
is_template?booleanwhen set, only toolboxes matching this template status are returned
title?stringfilter toolboxes by title (case-insensitive)
location?stringfilter toolboxes by location id
workgroup?stringfilter toolboxes by workgroup id
archived?booleanwhen set, only toolboxes matching this archived status are returned
Pagination
FieldTypeDescriptionDefault
start?integerthe offset of the first result to return0
limit?integerthe maximum number of results to return50
Error Responses
Status CodeDescription
400Bad request (organisation not found)
403Forbidden (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 CodeDescription
400Bad request (invalid toolbox or organisation)
403Forbidden (caller is not a member of the organisation)
404Not 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
FieldTypeDescription
titlestringthe title of the toolbox
is_templatebooleanwhether this toolbox is a template
location_idsnowflake?the id of the location where the toolbox was conducted; must belong to the same organisation
Error Responses
Status CodeDescription
400Bad request (invalid input, missing organisation, or location not found)
403Forbidden (toolbox is archived or insufficient permissions)
404Not 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
FieldTypeDescription
latitudedoublethe latitude where the toolbox was conducted
longitudedoublethe longitude where the toolbox was conducted
Error Responses
Status CodeDescription
400Bad request (invalid toolbox or organisation)
403Forbidden (toolbox is archived, already conducted, or insufficient permissions)
404Not 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 CodeDescription
400Bad request (invalid toolbox or organisation)
403Forbidden (toolbox is already archived or insufficient permissions)
404Not 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 CodeDescription
400Bad request (invalid toolbox or organisation)
403Forbidden (toolbox is not archived, archived longer than 24 hours ago, or insufficient permissions)
404Not 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
FieldTypeDescription
titlestringthe title of the section
Error Responses
Status CodeDescription
400Bad request (invalid toolbox or organisation)
403Forbidden (toolbox is archived or insufficient permissions)
404Not 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 CodeDescription
400Bad request (invalid section or organisation)
403Forbidden (caller is not a member of the organisation)
404Not 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
FieldTypeDescription
titlestringthe title of the section
orderintegerthe new order of the section within the toolbox; other sections will be re-ordered accordingly
Error Responses
Status CodeDescription
400Bad request (invalid toolbox, section, or organisation)
403Forbidden (toolbox is archived or insufficient permissions)
404Not 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 CodeDescription
400Bad request (invalid toolbox, section, organisation, or section is not empty)
403Forbidden (toolbox is archived or insufficient permissions)
404Not 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
FieldTypeDescription
section_idsnowflake?the id of the toolbox section this topic belongs to, or null for a top-level topic
bodystring?the content of the topic (default empty string)
Error Responses
Status CodeDescription
400Bad request (invalid toolbox, organisation, or section)
403Forbidden (toolbox is archived or insufficient permissions)
404Not 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 CodeDescription
400Bad request (invalid topic or organisation)
403Forbidden (caller is not a member of the organisation)
404Not 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
FieldTypeDescription
section_idsnowflake?the id of the toolbox section to move the topic to, or null for a top-level topic
bodystring?the content of the topic
commentsstring?comments on the topic
review_responseboolean?the reviewer's response to the topic
orderintegerthe new order of the topic within its section or toolbox; other topics will be re-ordered accordingly
Error Responses
Status CodeDescription
400Bad request (invalid toolbox, topic, section, or organisation)
403Forbidden (toolbox is archived or insufficient permissions)
404Not 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 CodeDescription
400Bad request (invalid toolbox, topic, or organisation)
403Forbidden (toolbox is archived or insufficient permissions)
404Not 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
FieldTypeDescription
user_idsnowflake?the id of an existing user to sign as
emailstring?the e-mail of the person signing; used to look up an existing user
phone_numberstring?the phone number of the person signing
first_namestring?the first name of the person signing
last_namestring?the last name of the person signing
companystring?the company of the person signing
positionstring?the position of the person signing
schedule_idsnowflake?the id of the work item schedule to associate with the sign; if null, signs for the toolbox directly
declarationboolean?confirmation that the information provided is true
signaturestring?the person's signature as an SVG string
user_qr_codestring?a one-time QR code token scanned from the user's device
scanned_atstring?the ISO8601 timestamp when the QR code was scanned (must be within the last 24 hours)
Error Responses
Status CodeDescription
400Bad request (invalid toolbox, organisation, schedule, user details, signature format, or missing declaration)
403Forbidden (toolbox is archived, not yet conducted, or insufficient permissions)
404Not 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 CodeDescription
400Bad request (invalid toolbox or organisation)
403Forbidden (caller is not a member of the organisation)
404Not found (toolbox does not exist)