Induction

Inductions allow organisations to define safety, compliance, or procedural forms that users must complete. Each induction consists of a revision history of questions and an optional PDF attachment. Users are assigned inductions via user induction records, and their completed responses are stored as induction record objects.

Induction Object

Field	Type	Description
id	snowflake	the induction's id
organisation_id	snowflake	the organisation's id
revision_id	snowflake	the current revision's id
revision_hash	hash	hash of the current revision
created_at	ISO8601 timestamp	when the induction was created
created_by	user	who created the induction (see Object or Id)
updated_at	ISO8601 timestamp	when the induction was last updated
updated_by	user	who last updated the induction (see Object or Id)

Induction Revision Object

Field	Type	Description
id	snowflake	the revision's id
organisation_id	snowflake	the organisation's id
hash	hash	cryptographic hash of the revision content
induction_id	snowflake	the induction's id
name	string	the revision's name (max 200 characters)
revision	string	the revision number or label (max 20 characters)
description	string	a description of the revision
valid_for	integer	number of seconds the induction is valid for
content_type	string	MIME type of the attached PDF document
length	integer	size in bytes of the attached PDF document
file_name	string	original file name of the attached PDF document
file_hash	hash	SHA-256 hash of the attached PDF document file
questions	array<induction question>	list of questions for this revision
updated_at	ISO8601 timestamp	when the revision was last updated
updated_by	user	who last updated the revision (see Object or Id)

Induction Question Object

Field	Type	Description
id	snowflake	the question's id
hash	hash	cryptographic hash of the question content
induction_id	snowflake	the induction's id
question	string	the question text
explanation	string	an explanation or instruction for the question
type	question type	the type of the question
enum_values	array<question enum value>	list of enum values (for enum-type questions only)
answer	induction record answer	the answer to the question (only included when questions are returned with a record)
updated_at	ISO8601 timestamp	when the question was last updated
updated_by	user	who last updated the question (see Object or Id)

Question Type

Value	Description
string	free-text string input
number	numeric input
boolean	true/false boolean input
enum	enumeration selection from a fixed list of values
date_time	date and time input
date	date input
time	time input
timespan	time span/duration input
system	system-generated value
user	user selection input
initials	user initials input
signature	digital signature input
image	image upload input
file	file upload input

Question Enum Value Object

Field	Type	Description
id	snowflake	the enum value's id
value	string	the stored value for the enum value
induction_question_id	snowflake	the question's id this value belongs to
updated_at	ISO8601 timestamp	when the enum value was last updated
updated_by	user	who last updated the enum value (see Object or Id)

Induction Record Object

Field	Type	Description
id	snowflake	the record's id
induction_id	snowflake	the induction's id
induction_hash	hash	hash of the induction revision this record is valid for
user	user	the user who completed the induction (see Object or Id)
email	string	the user's e-mail at time of induction
first_name	string	the user's first name at time of induction
last_name	string	the user's last name at time of induction
position	string	the user's position at time of induction
company	string	the user's company at time of induction
inducted_at	ISO8601 timestamp	when the induction was completed
expires_at	ISO8601 timestamp	when the induction record expires
questions	array<induction question>	list of questions answered in this record

Induction Record Answer Object

Field	Type	Description
type	question type	the type of the answer
enum_id	snowflake	the id of the selected enum value (for enum-type answers only)
value	object	the answer value

User Induction Object

Field	Type	Description
id	snowflake	the user induction's id
induction_id	snowflake	the induction's id
induction_hash	hash	hash of the induction revision this assignment is for
user	user	the user assigned this induction (see Object or Id)
due_at	ISO8601 timestamp	when the induction is due to be completed
created_by	user	who assigned this induction (see Object or Id)
created_at	ISO8601 timestamp	when the induction was assigned
induction	induction	the induction object
record	induction record	the completed induction record (if completed)

Get Induction

GET /inductions/{induction.id}

Returns the induction object for the given induction id. Requires membership in the organisation that owns the induction. If the caller has the MANAGE_INDUCTIONS permission for the organisation, the response will additionally include the full list of induction question objects embedded in the current induction revision.

Error Responses

Status Code	Description
400	The organisation was not found
403	The user is not a member of the organisation
404	The induction was not found

List Induction Revisions

GET /inductions/{induction.id}/revisions

Returns an array of induction revision objects for the given induction, ordered by updated_at ascending. Requires membership in the organisation that owns the induction.

Error Responses

Status Code	Description
400	The organisation was not found
403	The user is not a member of the organisation
404	The induction was not found

Get Induction Revision

GET /inductions/{induction.id}/revisions/{revision.hash}

Returns the induction revision object for the given induction and revision hash. Requires membership in the organisation that owns the induction. If the caller has the MANAGE_INDUCTIONS permission, the response will additionally include the full list of induction question objects for this revision.

Error Responses

Status Code	Description
400	The organisation was not found
403	The user is not a member of the organisation
404	The induction was not found
404	The revision was not found

Update Induction

PATCH /inductions/{induction.id}

Updates an induction, creating a new induction revision. Requires the MANAGE_INDUCTIONS permission for the organisation.

This endpoint accepts either application/json or multipart/form-data content types.

Parameters

Field	Type	Description
name	string	the induction form's name (max 200 characters)
revision	string	the revision number or label (max 20 characters)
description	string	a description of the induction form
valid_for	integer	number of seconds the induction record is valid for
attachment	?file	optional PDF attachment (replaces the existing attachment if provided)
questions	?array<update induction question>	list of questions for this induction form

Update Induction Question

Field	Type	Description
id	?snowflake	the question's id (omit for new questions)
question	string	the question text
explanation	string	an explanation or instruction for the question
type	question type	the type of the question (must be string, boolean, or enum)
answer	string	the answer or default value for the question
values	?array<update enum value>	list of enum values (required when type is enum)

Update Induction Enum Value

Field	Type	Description
id	?snowflake	the enum value's id (omit for new values)
value	string	the enum value text
nonce	?string	optional nonce to reference this value as the answer

Notes

• Questions can only be answered as a string, boolean, or enumeration (multiple choice).
• For enum-type questions, the answer field can reference an enum value by its nonce (for new values) or by its id (for existing values).
• The existing PDF attachment is retained unless a new attachment is provided.
• Modifying an enum value's text creates a new enum value with a new id.

Error Responses

Status Code	Description
400	The organisation was not found
400	Invalid question type (must be string, boolean, or enum)
400	The enum value id does not belong to this question
403	The user lacks the MANAGE_INDUCTIONS permission
404	The induction was not found

Assign Induction to User

POST /inductions/{induction.id}/users/{user.id}

Assigns an induction to a user. Returns the user induction object. Requires the MANAGE_INDUCTIONS permission for the organisation, or the caller may assign the induction to themselves if they are a member of the organisation. If the user already has this induction assigned, returns the existing user induction without creating a duplicate.

JSON Params

Field	Type	Description
due_at	?integer	unix timestamp when the induction is due to be completed

Error Responses

Status Code	Description
400	The organisation was not found
400	The user is not a member of the organisation
403	The user lacks the MANAGE_INDUCTIONS permission and is not assigning to themselves
404	The induction was not found

Remove Induction from User

DELETE /inductions/{induction.id}/users/{user.id}

Removes an induction assignment from a user. Requires the MANAGE_INDUCTIONS permission for the organisation, or the caller may remove the induction from themselves if they are a member of the organisation. Returns 200 OK if the assignment was removed, or 200 OK if no assignment existed.

Error Responses

Status Code	Description
400	The organisation was not found
403	The user lacks the MANAGE_INDUCTIONS permission and is not removing from themselves
404	The induction was not found

Get User Induction

GET /inductions/{induction.id}/users/{user.id}

Returns the user induction object for the given induction and user. The response includes the most recent induction record if the user has completed this induction. Requires the MANAGE_INDUCTIONS permission for the organisation.

Error Responses

Status Code	Description
400	The organisation was not found
403	The user lacks the MANAGE_INDUCTIONS permission
404	The user induction was not found

List Induction Users

GET /inductions/{induction.id}/users

Returns an array of user induction objects for all users assigned to the induction. Each response includes the most recent induction record if the user has completed this induction. Requires the MANAGE_INDUCTIONS permission for the organisation.

Error Responses

Status Code	Description
400	The organisation was not found
403	The user lacks the MANAGE_INDUCTIONS permission
404	The induction was not found

List Induction Records

GET /inductions/{induction.id}/revisions/{revision.hash}/records

Returns an array of induction record objects for the given induction revision, ordered by inducted_at ascending. Requires the MANAGE_INDUCTIONS permission for the organisation.

Error Responses

Status Code	Description
400	The organisation was not found
403	The user lacks the MANAGE_INDUCTIONS permission
404	The induction was not found
404	The revision was not found

Export Induction Records (CSV)

GET /inductions/{induction.id}/revisions/{revision.hash}/records/export-csv

Returns the induction records for the given revision as a CSV file. The response includes the following columns: first name, last name, position, company, inducted at, and expires at. Timestamps are formatted according to the caller's timezone. Requires the MANAGE_INDUCTIONS permission for the organisation.

Error Responses

Status Code	Description
400	The organisation was not found
403	The user lacks the MANAGE_INDUCTIONS permission
404	The induction was not found
404	The revision was not found

Export Induction Records (XLSX)

GET /inductions/{induction.id}/revisions/{revision.hash}/records/export-xlsx

Returns the induction records for the given revision as an XLSX spreadsheet file. The response includes the following columns: first name, last name, position, company, inducted at, and expires at. Timestamps are formatted according to the caller's timezone. Requires the MANAGE_INDUCTIONS permission for the organisation.

Error Responses

Status Code	Description
400	The organisation was not found
403	The user lacks the MANAGE_INDUCTIONS permission
404	The induction was not found
404	The revision was not found

Get Induction Attachment

GET /inductions/{induction.id}/attachments/{file.hash}

Returns the attached PDF file for the given induction revision. The response is streamed with the appropriate Content-Type header and a Content-Disposition header specifying the original file name.

Error Responses

Status Code	Description
404	The induction was not found
404	The revision with the given file hash was not found

Get Induction Record

GET /induction-records/{induction-record.id}

Returns the induction record for the given record id, including the full list of induction question objects for the associated revision. Requires the MANAGE_INDUCTIONS permission for the organisation that owns the induction.

Error Responses

Status Code	Description
400	The organisation was not found
403	The user lacks the MANAGE_INDUCTIONS permission
404	The induction record was not found
404	The revision was not found