ThinkSafe Go API

Version 1 reference

Base URL https://thinksafe-go-api-flex.azurewebsites.net/api/v1  ·  Machine-readable: openapi.json (OpenAPI 3.1)

Read your ThinkSafe Go data from your own systems, and write people and sites into it.

Keys

Every request carries an API key in the Authorization header: Authorization: Bearer tsk_live_...

Scopes

Each key carries scopes that say what it may do.

A request the key is not scoped for gets 403 insufficient_scope, with the scope it would need.

Lists

List endpoints return a page at a time: limit (default 100, at most 500) and offset. Each response has a pagination object; keep going while has_more is true.

Writing

Send JSON (up to 64 KB). A field the API does not know is rejected with 400, never silently dropped.

Files

Files are only ever served to a request carrying a valid key. There are no public or long-lived file links: a Safety Data Sheet comes as a link that works for 60 seconds, and site PDFs are generated on request and returned directly.

AI assistants

You can connect an AI assistant such as Claude or ChatGPT to your ThinkSafe Go records, so it can answer questions and prepare summaries from them. The connection uses the Model Context Protocol (MCP).

Errors

Errors are JSON: { "error": "<code>", "details": ["..."] }. The codes used by each endpoint are listed with it.

Formats

Changes

This API only grows. New endpoints and new fields may be added; existing ones are not renamed or removed. Write your integration to ignore fields it does not know.

Reading

Lists and single records. Scope: read.

GET /users

List users scope: read

People with a ThinkSafe Go login in your organisation.

Parameters

NameWhereDescription
limitqueryHow many records to return. Default 100; anything above 500 is treated as 500.
offsetqueryHow many records to skip, for paging.
updated_sincequeryOnly records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z).
statusqueryExact match on status.
rolequeryExact match on role.

Response

200 A page of records, oldest change first.

Each record in data:

FieldTypeDescription
ididUser id.
emailtextLogin email address.
nametextFull name.
phonetext or nullPhone number, where recorded.
roletextworker, supervisor or client_admin. A ThinkSafe support account attached to your organisation appears as thinksafe_admin.
assigned_site_idslist of idIds of the sites recorded against the user.
assigned_form_slugslist of text or nullForm slugs recorded against the user, where per-user form access has been set. Null when not set.
statustextLogin status. One of: active, invited, disabled.
last_login_attimestamp or nullLast sign-in, or null if the user has never signed in.
created_attimestampWhen the record was created.
updated_attimestampWhen the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed.

Errors

GET /sites

List sites scope: read

Work locations (jobs, branches, projects). Sites can be created and updated with a sites:write key.

Parameters

NameWhereDescription
limitqueryHow many records to return. Default 100; anything above 500 is treated as 500.
offsetqueryHow many records to skip, for paging.
updated_sincequeryOnly records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z).
job_numberqueryExact match on job number.
statusqueryactive or archived.

Response

200 A page of records, oldest change first.

Each record in data:

FieldTypeDescription
ididSite id.
nametextSite name.
addresstext or nullStreet address, where recorded.
latitudetext or nullLatitude, where recorded. Returned as a string.
longitudetext or nullLongitude, where recorded. Returned as a string.
statustextactive or archived. One of: active, archived.
site_slugtextShort name used in the address behind the site QR code. Set when the site is created and never changed, so printed QR posters keep working after a rename.
job_numbertext or nullYour job number for the site, where recorded.
sssp_document_set_idid or nullId of the Site-Specific Safety Plan linked to the site, or null. Download the plan with GET /v1/sites/{id}/sssp.
sssp_versionwhole number or nullVersion number of the linked plan, as printed on its cover (v1, v2 and so on). It goes up each time the plan is published. Null when no plan is linked.
sssp_updated_attimestamp or nullWhen the linked plan last changed, published or not. To see whether a plan needs downloading again, compare this and sssp_document_set_id with the values you stored. Null when no plan is linked.
created_attimestampWhen the record was created.
updated_attimestampWhen the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed.

Errors

GET /submissions

List submissions scope: read

Completed forms: incidents, hazard reports, inspections, meetings, inductions and every other record your team submits. This list returns record details only; fetch one record with GET /v1/submissions/{id} for its answers.

Parameters

NameWhereDescription
limitqueryHow many records to return. Default 100; anything above 500 is treated as 500.
offsetqueryHow many records to skip, for paging.
updated_sincequeryOnly records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z).
site_idqueryRecords for one site.
statusqueryopen, in_review, resolved or closed.
submitted_byqueryRecords submitted by one user (user id).
worker_idqueryExact match on worker_id.
form_definition_idqueryRecords of one form (id from /v1/form-definitions).

Response

200 A page of records, oldest change first.

Each record in data:

FieldTypeDescription
ididRecord id.
site_idid or nullSite the record belongs to, where one was chosen.
site_nametext or nullSite name: the linked site's name when there is one, otherwise the location typed on the form.
form_definition_ididWhich form this is. Look it up in /v1/form-definitions.
submitted_byid or nullUser id of the person who submitted the record, where known.
worker_idid or nullRelated worker id, where set.
statustextWhere the record is in its close-out. One of: open, in_review, resolved, closed.
prioritywhole number or nullPriority from 1 to 5, where set.
risk_leveltext or nullRisk level. Only hazard reports set this; it is null on every other form.
reference_numbertext or nullReference shown in the app, for example INC-0020. Can be null on older imported records.
parent_submission_idid or nullId of the record this one was raised from, where there is one.
gps_latitudetext or nullLatitude captured at submission, where available. Returned as a string.
gps_longitudetext or nullLongitude captured at submission, where available. Returned as a string.
submitted_attimestampWhen the form was submitted.
created_attimestampWhen the record was created.
updated_attimestampWhen the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed.

Errors

GET /licences

List licences and dated records scope: read

Licences, training, certificates and other dated records, for people and for plant and equipment (WOF, COF, registration and so on).

Parameters

NameWhereDescription
limitqueryHow many records to return. Default 100; anything above 500 is treated as 500.
offsetqueryHow many records to skip, for paging.
updated_sincequeryOnly records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z).
person_idqueryRecords for one person (id from /v1/people).
statusqueryactive, expiring_soon, expired or archived.
record_typequeryExact match on record_type.
subject_typequeryExact match on subject_type.
user_idqueryRecords linked to one user (user id).

Response

200 A page of records, oldest change first.

Each record in data:

FieldTypeDescription
ididRecord id.
user_idid or nullUser the record is linked to, where there is one.
person_idid or nullPerson the record belongs to (id from /v1/people), where there is one.
worker_nametextName of the person or plant item the record belongs to.
notify_emailtext or nullContact email held on the record, where set.
licence_typetextType of record, for example Full Drivers License, COF or First Aid.
licence_type_othertext or nullFree-text type, where one was entered.
licence_numbertext or nullLicence or certificate number, where recorded.
issuing_authoritytext or nullWho issued it, where recorded.
issue_datetimestamp or nullIssue date, where recorded. Returned as a timestamp at 00:00 UTC on that date (for example 2026-04-01T00:00:00.000Z).
expiry_datetimestamp or nullExpiry date, where there is one. Returned as a timestamp at 00:00 UTC on that date.
no_expirytrue/falseTrue when the record does not expire.
notestext or nullNotes, where recorded.
statustextactive, expiring_soon, expired or archived. One of: active, expiring_soon, expired, archived.
record_typetextKind of record, for example licence.
subject_typetextWhat the record is about, for example person or plant.
competency_leveltext or nullCompetency level, where recorded.
created_attimestampWhen the record was created.
updated_attimestampWhen the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed.

Errors

GET /form-definitions

List form definitions scope: read

The forms available to your organisation: the standard ThinkSafe forms plus your own. Use this to turn a submission's form_definition_id into a form name.

Parameters

NameWhereDescription
limitqueryHow many records to return. Default 100; anything above 500 is treated as 500.
offsetqueryHow many records to skip, for paging.
updated_sincequeryOnly records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z).
slugqueryExact match on slug.
statusqueryactive, draft or archived.
categoryqueryExact match on category.

Response

200 A page of records, oldest change first.

Each record in data:

FieldTypeDescription
ididForm id. Match submissions to forms on this, not on slug.
slugtextShort name of the form. One of your own forms can share a slug with a standard form, so match on id.
nametextForm name as shown in the app.
categorytext or nullCategory the form sits under in the app, where set.
statustextactive, draft or archived. One of: active, draft, archived.
versionwhole numberVersion number of the form.
created_attimestampWhen the record was created.
updated_attimestampWhen the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed.

Errors

GET /assets

List plant and equipment scope: read

The plant and equipment register: vehicles, trailers and other items. Their dated records (WOF, COF, registration and so on) are on /v1/licences.

Parameters

NameWhereDescription
limitqueryHow many records to return. Default 100; anything above 500 is treated as 500.
offsetqueryHow many records to skip, for paging.
updated_sincequeryOnly records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z).
identifierqueryRegistration or serial number. Matches ignoring upper/lower case and spaces.
asset_typequeryExact match on asset_type.
statusqueryactive or archived.

Response

200 A page of records, oldest change first.

Each record in data:

FieldTypeDescription
ididItem id.
nametextMake and model, or a description of the item.
identifiertext or nullRegistration or serial number, where recorded.
asset_typetextType of item, for example vehicle, trailer or other.
statustextactive or archived. One of: active, archived.
assigned_toid or nullId of who the item is assigned to, where set.
yearwhole number or nullYear of manufacture, where recorded.
colourtext or nullColour, where recorded.
created_attimestampWhen the record was created.
updated_attimestampWhen the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed.

Errors

GET /hazardous-substances

List hazardous substances scope: read

The hazardous substance register, with the review status of each Safety Data Sheet. Fetch the SDS file itself with GET /v1/hazardous-substances/{id}/sds.

Parameters

NameWhereDescription
limitqueryHow many records to return. Default 100; anything above 500 is treated as 500.
offsetqueryHow many records to skip, for paging.
updated_sincequeryOnly records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z).
statusqueryExact match on status, for example active to leave out archived substances.

Response

200 A page of records, oldest change first.

Each record in data:

FieldTypeDescription
ididSubstance id.
substance_nametextSubstance name.
hazard_classtext or nullHazard classification, where recorded.
locationtext or nullWhere it is kept, where recorded.
quantitytext or nullQuantity held, as entered.
storage_segregationtext or nullStorage and segregation notes, where recorded.
notestext or nullNotes, where recorded.
sds_review_datedate or nullDate the Safety Data Sheet is due for review (YYYY-MM-DD), where set.
sds_review_statustextno_date (no review date set), overdue (date has passed), due_soon (within 30 days) or current. Worked out against today's date in New Zealand. One of: no_date, overdue, due_soon, current.
days_to_reviewwhole number or nullDays until the review date. Negative when overdue, null when no date is set.
has_sdstrue/falseTrue when a Safety Data Sheet file is held for the substance.
sds_filenametext or nullFile name of the Safety Data Sheet, where one is held.
sds_uploaded_attimestamp or nullWhen the Safety Data Sheet was uploaded, where one is held.
statustextactive or archived.
created_attimestampWhen the record was created.
updated_attimestampWhen the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed.

Errors

GET /people

List people scope: read

The people register: employees, contractors and others, whether or not they have a login. People can be created and updated with a people:write key.

Parameters

NameWhereDescription
limitqueryHow many records to return. Default 100; anything above 500 is treated as 500.
offsetqueryHow many records to skip, for paging.
updated_sincequeryOnly records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z).
external_idqueryExact match on your own id for the person.
emailqueryEmail address. Matches ignoring upper/lower case and surrounding spaces.
statusqueryactive or archived.
worker_typequeryExact match on worker_type.

Response

200 A page of records, oldest change first.

Each record in data:

FieldTypeDescription
ididPerson id.
user_idid or nullThe person's login (user id), if they have one.
external_idtext or nullYour own system's id for the person, where set.
nametextFull name.
job_titletext or nullJob title, where recorded.
worker_typetextType of worker. One of: employee, casual, contractor, apprentice, volunteer, labour_hire, other.
employertext or nullEmployer, where recorded (for example a contractor or labour-hire company).
site_idid or nullSite the person is based at, where set.
phonetext or nullPhone number, where recorded.
emailtext or nullEmail address, where recorded.
start_datedate or nullStart date (YYYY-MM-DD), where recorded.
end_datedate or nullLast day worked (YYYY-MM-DD), where recorded.
emergency_contact_nametext or nullEmergency contact name, where recorded.
emergency_contact_phonetext or nullEmergency contact phone, where recorded.
emergency_contact_relationshiptext or nullEmergency contact relationship, where recorded.
statustextactive or archived. One of: active, archived.
created_attimestampWhen the record was created.
updated_attimestampWhen the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed.

Errors

GET /actions

List actions scope: read

The actions register: corrective and follow-up actions, who each one is assigned to, when it is due and whether it has been closed.

Parameters

NameWhereDescription
limitqueryHow many records to return. Default 100; anything above 500 is treated as 500.
offsetqueryHow many records to skip, for paging.
updated_sincequeryOnly records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z).
statusqueryExact match on status: open, in_progress or closed.
priorityqueryExact match on priority: low, medium, high or critical.
overduequerytrue for actions past their due date and not closed; false for all others.
assigned_to_user_idqueryActions assigned to one user (user id).

Response

200 A page of records, oldest change first.

Each record in data:

FieldTypeDescription
ididAction id.
descriptiontext or nullWhat needs to be done.
statustextStatus of the action: open, in_progress or closed. closed means it has been completed; the others are still outstanding.
prioritytext or nullPriority, where set: low, medium, high or critical.
due_datedate or nullDate the action is due (YYYY-MM-DD), where set.
overduetrue/falseTrue when the due date has passed and the action is not closed. Worked out against the current date in New Zealand.
assigned_to_nametext or nullName of the person the action is assigned to, where assigned.
assigned_to_user_idid or nullUser id of the person the action is assigned to, where they have a login.
closed_attimestamp or nullWhen the action was closed, where it has been.
closure_notestext or nullNotes recorded when the action was closed, where given.
submission_idid or nullThe submission the action was raised from, where there is one; fetch one record with GET /v1/submissions/{id}.
reference_numbertext or nullReference number of that submission, for example INC-0003.
form_nametext or nullName of the form that submission was made on.
site_nametext or nullSite that submission relates to, where recorded.
created_attimestampWhen the record was created.
updated_attimestampWhen the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed.

Errors

GET /contractors

List contractors scope: read

The contractor register: each contractor with its pre-qualification status, approval dates and the expiry of the documents it has supplied. Empty when contractor management is not switched on for your organisation.

Parameters

NameWhereDescription
limitqueryHow many records to return. Default 100; anything above 500 is treated as 500.
offsetqueryHow many records to skip, for paging.
updated_sincequeryOnly records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z).
statusqueryExact match on status, for example approved.
tradequeryExact match on trade.

Response

200 A page of records, oldest change first.

Each record in data:

FieldTypeDescription
ididContractor id.
nametextContractor name.
tradetext or nullTrade, where recorded.
scopetext or nullScope of work, where recorded.
statustextinvited (pre-qualification not yet returned), submitted (returned and awaiting a decision), approved, approved_conditions (approved with conditions) or declined. One of: invited, submitted, approved, approved_conditions, declined.
approved_untildate or nullDate the approval runs to (YYYY-MM-DD), where set.
approval_expiredtrue/falseTrue when the contractor was approved and the approved-until date has passed. Worked out against the current date in New Zealand.
conditionstext or nullConditions attached to the approval, where given.
contact_nametext or nullName of the contact person at the contractor, where recorded.
reviewed_attimestamp or nullWhen the approval decision was made, where one has been.
next_document_expirydate or nullEarliest expiry date among the current documents (YYYY-MM-DD), where any has one.
expired_documentswhole numberHow many current documents have passed their expiry date.
expiring_documentswhole numberHow many current documents expire within the next 30 days.
documentslist of textCurrent documents held for the contractor, one line each: type | label | expiry date. The files themselves are not available here.
created_attimestampWhen the record was created.
updated_attimestampWhen the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed.

Errors

GET /submissions/{id}

Get one submission with its answers scope: read

One record with its answers, labelled the way your team sees them in the app, including any changes your organisation has made to the form. Photos and signatures are not included.

Parameters

NameWhereDescription
id requiredpathSubmission id.

Response

200 The record.

Fields of data:

FieldTypeDescription
ididRecord id.
site_idid or nullSite the record belongs to, where one was chosen.
site_nametext or nullSite name: the linked site's name when there is one, otherwise the location typed on the form.
form_definition_ididWhich form this is. Look it up in /v1/form-definitions.
submitted_byid or nullUser id of the person who submitted the record, where known.
worker_idid or nullRelated worker id, where set.
statustextWhere the record is in its close-out. One of: open, in_review, resolved, closed.
prioritywhole number or nullPriority from 1 to 5, where set.
risk_leveltext or nullRisk level. Only hazard reports set this; it is null on every other form.
reference_numbertext or nullReference shown in the app, for example INC-0020. Can be null on older imported records.
parent_submission_idid or nullId of the record this one was raised from, where there is one.
gps_latitudetext or nullLatitude captured at submission, where available. Returned as a string.
gps_longitudetext or nullLongitude captured at submission, where available. Returned as a string.
submitted_attimestampWhen the form was submitted.
created_attimestampWhen the record was created.
updated_attimestampWhen the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed.
form_slugtext or nullShort name of the form.
form_nametext or nullForm name as shown in the app.
answerslist of objectThe answers, in form order, labelled as your team sees them. Photos and signatures are not included.

Errors

Files

Documents and PDFs. Scope: read.

GET /hazardous-substances/{id}/sds

Get a Safety Data Sheet scope: read

By default this redirects (302) to a link to the file that works for 60 seconds. With json=1 it returns that link in JSON instead, which is the safer choice if your HTTP client forwards the Authorization header when it follows a redirect.

Parameters

NameWhereDescription
id requiredpathHazardous substance id.
jsonquerySend json=1 to get a JSON response instead of the default.

Response

200 With json=1: the short-lived link.

Fields of data:

FieldTypeDescription
urltextA link to the file. It stops working after expires_in seconds, so fetch it straight away.
expires_inwhole numberSeconds until the link expires.
filenametextFile name.
content_typetextFile type, for example application/pdf.

Errors

GET /sites/{id}/qr-poster

Download a site QR poster scope: read

The printable A4 sign-in poster for the site, with its QR code. It is the same PDF as Print poster in the app, made fresh on each request.

Parameters

NameWhereDescription
id requiredpathSite id.
jsonquerySend json=1 to get a JSON response instead of the default.

Response

200 The PDF. With json=1, a JSON object holding the PDF base64 encoded.

Fields of data:

FieldTypeDescription
filenametextFile name.
content_typetextAlways application/pdf.
size_byteswhole numberSize of the PDF in bytes, before base64 encoding.
content_base64textThe PDF, base64 encoded.
sssp_versionwhole numberSSSP download only. Version number of the plan, as printed on its cover.
sssp_updated_attimestampSSSP download only. When the plan last changed, published or not.

Errors

GET /sites/{id}/sssp

Download the Site-Specific Safety Plan linked to a site scope: read

The Site-Specific Safety Plan linked to the site, as a PDF. It is the same PDF as in the app, made fresh on each request, so it always reflects the current plan. A site has a plan when sssp_document_set_id is not null.

Parameters

NameWhereDescription
id requiredpathSite id.
jsonquerySend json=1 to get a JSON response instead of the default.

Response

200 The PDF. With json=1, a JSON object holding the PDF base64 encoded.

Fields of data:

FieldTypeDescription
filenametextFile name.
content_typetextAlways application/pdf.
size_byteswhole numberSize of the PDF in bytes, before base64 encoding.
content_base64textThe PDF, base64 encoded.
sssp_versionwhole numberSSSP download only. Version number of the plan, as printed on its cover.
sssp_updated_attimestampSSSP download only. When the plan last changed, published or not.

Errors

Writing

Create and update people and sites. Scope: people:write or sites:write.

POST /sites

Create a site scope: sites:write

Creates a site exactly as Add site does in the app: it is active straight away and its QR poster is ready to download. This always creates a new site, because two sites can share a job number. To make a retry safe, send an Idempotency-Key such as your job id; to check first, list sites with the job_number filter.

Parameters

NameWhereDescription
Idempotency-KeyheaderYour own unique id for this request (for example your job or record id). Sending the same key again returns the original response instead of repeating the write.

Request body (JSON)

FieldTypeDescription
name requiredtextSite name. Up to 255 characters.
addresstext or nullStreet address, where recorded. Send null or an empty string to leave it blank. Up to 500 characters.
job_numbertext or nullYour job number for the site, where recorded. Send null or an empty string to leave it blank. A number is accepted and stored as text. Up to 100 characters.

Response

201 The site that was created.

Fields of data:

FieldTypeDescription
ididSite id.
nametextSite name.
addresstext or nullStreet address, where recorded.
latitudetext or nullLatitude, where recorded. Returned as a string.
longitudetext or nullLongitude, where recorded. Returned as a string.
statustextactive or archived. One of: active, archived.
site_slugtextShort name used in the address behind the site QR code. Set when the site is created and never changed, so printed QR posters keep working after a rename.
job_numbertext or nullYour job number for the site, where recorded.
sssp_document_set_idid or nullId of the Site-Specific Safety Plan linked to the site, or null. Download the plan with GET /v1/sites/{id}/sssp.
sssp_versionwhole number or nullVersion number of the linked plan, as printed on its cover (v1, v2 and so on). It goes up each time the plan is published. Null when no plan is linked.
sssp_updated_attimestamp or nullWhen the linked plan last changed, published or not. To see whether a plan needs downloading again, compare this and sssp_document_set_id with the values you stored. Null when no plan is linked.
created_attimestampWhen the record was created.
updated_attimestampWhen the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed.

Alongside data:

FieldTypeDescription
actiontextWhat happened. One of: created, updated.

Errors

POST /people

Create or update a person scope: people:write

Finds the person by external_id; failing that, by email when exactly one person has that email; otherwise creates them. Send external_id or email every time, and name when creating. end_date is the last day worked: once that day has passed (New Zealand date) the person is archived, their dated records are archived and their worker or supervisor login is switched off, which frees the seat. A future end_date is simply stored and takes effect overnight after that day.

Parameters

NameWhereDescription
Idempotency-KeyheaderYour own unique id for this request (for example your job or record id). Sending the same key again returns the original response instead of repeating the write.

Request body (JSON)

FieldTypeDescription
external_idtext or nullYour own system's id for the person, where set. Send null or an empty string to clear it. A number is accepted and stored as text. Up to 100 characters.
nametextFull name. Up to 150 characters.
job_titletext or nullJob title, where recorded. Send null or an empty string to clear it. Up to 100 characters.
worker_typetextType of worker. One of: employee, casual, contractor, apprentice, volunteer, labour_hire, other.
employertext or nullEmployer, where recorded (for example a contractor or labour-hire company). Send null or an empty string to clear it. Up to 150 characters.
phonetext or nullPhone number, where recorded. Send null or an empty string to clear it. Up to 50 characters.
emailemail or nullEmail address, where recorded. Send null or an empty string to clear it. Up to 255 characters.
start_datedate or nullStart date (YYYY-MM-DD), where recorded. Send null or an empty string to clear it.
end_datedate or nullLast day worked (YYYY-MM-DD), where recorded. Send null or an empty string to clear it.
emergency_contact_nametext or nullEmergency contact name, where recorded. Send null or an empty string to clear it. Up to 150 characters.
emergency_contact_phonetext or nullEmergency contact phone, where recorded. Send null or an empty string to clear it. Up to 50 characters.
emergency_contact_relationshiptext or nullEmergency contact relationship, where recorded. Send null or an empty string to clear it. Up to 60 characters.
invitetrue/falseSend true to give the person a ThinkSafe Go login and email them an invitation (the link lasts 7 days). This uses one of your seats. If the person has a login that was switched off, it is switched back on and a fresh invitation is sent. The person is always saved; when no login is created the response says why.
roletextRole for the login when invite is true. One of: worker, supervisor.
login_enabledtrue/falseSwitch the person's existing login off (false) or back on (true) without archiving them. Applies to worker and supervisor logins. Switching on uses a seat.
driver_licenceobjectCreate or update a driver licence record for the person. ThinkSafe then sends the expiry reminders. Learner, Restricted, Full and International or Overseas driver licences are one record per person that is renamed as they progress, so an upgrade never leaves the old stage sending reminders (the type name must contain driver or driving). Any other type matches an existing record with the same type name, ignoring upper and lower case. Changing the expiry date restarts the reminders.
FieldTypeDescription
licence_type requiredtextName of the licence, for example Full Drivers License. Up to 100 characters.
licence_numbertext or nullLicence number. Up to 100 characters.
issue_datedate or nullYYYY-MM-DD. Send null to clear it.
expiry_datedate or nullYYYY-MM-DD. Send null to clear it.

Response

200 An existing person was updated. 201 A new person was created.

Fields of data:

FieldTypeDescription
ididPerson id.
user_idid or nullThe person's login (user id), if they have one.
external_idtext or nullYour own system's id for the person, where set.
nametextFull name.
job_titletext or nullJob title, where recorded.
worker_typetextType of worker. One of: employee, casual, contractor, apprentice, volunteer, labour_hire, other.
employertext or nullEmployer, where recorded (for example a contractor or labour-hire company).
site_idid or nullSite the person is based at, where set.
phonetext or nullPhone number, where recorded.
emailtext or nullEmail address, where recorded.
start_datedate or nullStart date (YYYY-MM-DD), where recorded.
end_datedate or nullLast day worked (YYYY-MM-DD), where recorded.
emergency_contact_nametext or nullEmergency contact name, where recorded.
emergency_contact_phonetext or nullEmergency contact phone, where recorded.
emergency_contact_relationshiptext or nullEmergency contact relationship, where recorded.
statustextactive or archived. One of: active, archived.
created_attimestampWhen the record was created.
updated_attimestampWhen the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed.

Alongside data:

FieldTypeDescription
actiontextWhat happened. One of: created, updated.
inviteobjectPresent when invite was sent in the request.
FieldTypeDescription
senttrue/falseTrue when an invitation email was sent.
reenabledtrue/falseTrue when an existing switched-off login was switched back on.
user_ididThe login that was created or switched back on.
roletextRole of the login.
reasontextWhen sent is false, why. For example already_has_login, seat_limit_reached, no_email, email_in_use or person_is_leaver.
loginobjectPresent when the request changed the state of the person's login.
FieldTypeDescription
enabledtrue/falseWhether the login is now on.
disabledtrue/falseTrue when the login was switched off because the person has left.
changedtrue/falseWhether anything changed.
user_ididThe login affected.
reasontextWhen nothing changed, why. For example no_login or role_not_managed.
driver_licenceobjectPresent when driver_licence was sent in the request.
FieldTypeDescription
savedtrue/falseTrue when the licence record was created or updated.
actiontextcreated or updated.
ididThe licence record (see /v1/licences).
licence_typetextType now on the record.
previous_typetextThe earlier type, when a driver licence moved to a new stage.
licence_numbertext or nullLicence number.
issue_datetext or nullIssue date.
expiry_datetext or nullExpiry date (YYYY-MM-DD).
statustextactive, expiring_soon or expired.
reasontextWhen saved is false, why. For example multiple_matching_records or person_is_leaver.

Errors

PATCH /sites/{id}

Rename, update or archive a site scope: sites:write

Send only the fields you want to change. Renaming a site does not change its QR code, so posters already printed keep working. Set status to archived when the job is complete.

Parameters

NameWhereDescription
id requiredpathSite id.
Idempotency-KeyheaderYour own unique id for this request (for example your job or record id). Sending the same key again returns the original response instead of repeating the write.

Request body (JSON)

FieldTypeDescription
nametextSite name. Up to 255 characters.
addresstext or nullStreet address, where recorded. Send null or an empty string to leave it blank. Up to 500 characters.
job_numbertext or nullYour job number for the site, where recorded. Send null or an empty string to leave it blank. A number is accepted and stored as text. Up to 100 characters.
statustextSet to archived when the job is finished, or back to active to reopen it. One of: active, archived.

Response

200 The site after the change.

Fields of data:

FieldTypeDescription
ididSite id.
nametextSite name.
addresstext or nullStreet address, where recorded.
latitudetext or nullLatitude, where recorded. Returned as a string.
longitudetext or nullLongitude, where recorded. Returned as a string.
statustextactive or archived. One of: active, archived.
site_slugtextShort name used in the address behind the site QR code. Set when the site is created and never changed, so printed QR posters keep working after a rename.
job_numbertext or nullYour job number for the site, where recorded.
sssp_document_set_idid or nullId of the Site-Specific Safety Plan linked to the site, or null. Download the plan with GET /v1/sites/{id}/sssp.
sssp_versionwhole number or nullVersion number of the linked plan, as printed on its cover (v1, v2 and so on). It goes up each time the plan is published. Null when no plan is linked.
sssp_updated_attimestamp or nullWhen the linked plan last changed, published or not. To see whether a plan needs downloading again, compare this and sssp_document_set_id with the values you stored. Null when no plan is linked.
created_attimestampWhen the record was created.
updated_attimestampWhen the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed.

Alongside data:

FieldTypeDescription
actiontextWhat happened. One of: created, updated.

Errors

PATCH /people/{id}

Update a person by id scope: people:write

Send only the fields you want to change. Use this when people share an email address. The same end_date, invite, login_enabled and driver_licence behaviour applies as when creating or updating by external_id.

Parameters

NameWhereDescription
id requiredpathPerson id.
Idempotency-KeyheaderYour own unique id for this request (for example your job or record id). Sending the same key again returns the original response instead of repeating the write.

Request body (JSON)

FieldTypeDescription
external_idtext or nullYour own system's id for the person, where set. Send null or an empty string to clear it. A number is accepted and stored as text. Up to 100 characters.
nametextFull name. Up to 150 characters.
job_titletext or nullJob title, where recorded. Send null or an empty string to clear it. Up to 100 characters.
worker_typetextType of worker. One of: employee, casual, contractor, apprentice, volunteer, labour_hire, other.
employertext or nullEmployer, where recorded (for example a contractor or labour-hire company). Send null or an empty string to clear it. Up to 150 characters.
phonetext or nullPhone number, where recorded. Send null or an empty string to clear it. Up to 50 characters.
emailemail or nullEmail address, where recorded. Send null or an empty string to clear it. Up to 255 characters.
start_datedate or nullStart date (YYYY-MM-DD), where recorded. Send null or an empty string to clear it.
end_datedate or nullLast day worked (YYYY-MM-DD), where recorded. Send null or an empty string to clear it.
emergency_contact_nametext or nullEmergency contact name, where recorded. Send null or an empty string to clear it. Up to 150 characters.
emergency_contact_phonetext or nullEmergency contact phone, where recorded. Send null or an empty string to clear it. Up to 50 characters.
emergency_contact_relationshiptext or nullEmergency contact relationship, where recorded. Send null or an empty string to clear it. Up to 60 characters.
invitetrue/falseSend true to give the person a ThinkSafe Go login and email them an invitation (the link lasts 7 days). This uses one of your seats. If the person has a login that was switched off, it is switched back on and a fresh invitation is sent. The person is always saved; when no login is created the response says why.
roletextRole for the login when invite is true. One of: worker, supervisor.
login_enabledtrue/falseSwitch the person's existing login off (false) or back on (true) without archiving them. Applies to worker and supervisor logins. Switching on uses a seat.
driver_licenceobjectCreate or update a driver licence record for the person. ThinkSafe then sends the expiry reminders. Learner, Restricted, Full and International or Overseas driver licences are one record per person that is renamed as they progress, so an upgrade never leaves the old stage sending reminders (the type name must contain driver or driving). Any other type matches an existing record with the same type name, ignoring upper and lower case. Changing the expiry date restarts the reminders.
FieldTypeDescription
licence_type requiredtextName of the licence, for example Full Drivers License. Up to 100 characters.
licence_numbertext or nullLicence number. Up to 100 characters.
issue_datedate or nullYYYY-MM-DD. Send null to clear it.
expiry_datedate or nullYYYY-MM-DD. Send null to clear it.

Response

200 The person after the change.

Fields of data:

FieldTypeDescription
ididPerson id.
user_idid or nullThe person's login (user id), if they have one.
external_idtext or nullYour own system's id for the person, where set.
nametextFull name.
job_titletext or nullJob title, where recorded.
worker_typetextType of worker. One of: employee, casual, contractor, apprentice, volunteer, labour_hire, other.
employertext or nullEmployer, where recorded (for example a contractor or labour-hire company).
site_idid or nullSite the person is based at, where set.
phonetext or nullPhone number, where recorded.
emailtext or nullEmail address, where recorded.
start_datedate or nullStart date (YYYY-MM-DD), where recorded.
end_datedate or nullLast day worked (YYYY-MM-DD), where recorded.
emergency_contact_nametext or nullEmergency contact name, where recorded.
emergency_contact_phonetext or nullEmergency contact phone, where recorded.
emergency_contact_relationshiptext or nullEmergency contact relationship, where recorded.
statustextactive or archived. One of: active, archived.
created_attimestampWhen the record was created.
updated_attimestampWhen the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed.

Alongside data:

FieldTypeDescription
actiontextWhat happened. One of: created, updated.
inviteobjectPresent when invite was sent in the request.
FieldTypeDescription
senttrue/falseTrue when an invitation email was sent.
reenabledtrue/falseTrue when an existing switched-off login was switched back on.
user_ididThe login that was created or switched back on.
roletextRole of the login.
reasontextWhen sent is false, why. For example already_has_login, seat_limit_reached, no_email, email_in_use or person_is_leaver.
loginobjectPresent when the request changed the state of the person's login.
FieldTypeDescription
enabledtrue/falseWhether the login is now on.
disabledtrue/falseTrue when the login was switched off because the person has left.
changedtrue/falseWhether anything changed.
user_ididThe login affected.
reasontextWhen nothing changed, why. For example no_login or role_not_managed.
driver_licenceobjectPresent when driver_licence was sent in the request.
FieldTypeDescription
savedtrue/falseTrue when the licence record was created or updated.
actiontextcreated or updated.
ididThe licence record (see /v1/licences).
licence_typetextType now on the record.
previous_typetextThe earlier type, when a driver licence moved to a new stage.
licence_numbertext or nullLicence number.
issue_datetext or nullIssue date.
expiry_datetext or nullExpiry date (YYYY-MM-DD).
statustextactive, expiring_soon or expired.
reasontextWhen saved is false, why. For example multiple_matching_records or person_is_leaver.

Errors