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_...
- Keys are issued by ThinkSafe on request. A key is shown once, when it is issued; ThinkSafe keeps only a hash of it.
- A key belongs to one organisation and can only ever see or change that organisation's data.
- A key can be revoked at any time and stops working immediately.
Scopes
Each key carries scopes that say what it may do.
read: every GET endpoint.people:write: create and update people.sites:write: create and update sites.
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.
- Records come oldest change first. To pick up only what has changed, send
updated_sincewith the time of your last sync. - Filters are exact matches on the fields listed for each endpoint. Query parameters the API does not know are ignored.
- Sample data that comes with a trial account is never returned.
Writing
Send JSON (up to 64 KB). A field the API does not know is rejected with 400, never silently dropped.
- Send an
Idempotency-Keyheader with your own unique id for the request (8 to 200 letters, digits or_ - : .). If the same key arrives again with the same body, you get the original response back with the headerIdempotent-Replayed: trueand nothing is written twice. The same key with a different body gets 422. - Every write is recorded in your organisation's audit log against the key that made it.
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.
- PDF generation is limited to 600 requests an hour per key (429
rate_limitedbeyond that). Each PDF takes a few seconds.
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).
- Address:
https://mcp.go.thinksafe.co.nz/api/v1/mcp - Sign-in, option 1: your ThinkSafe Go login. Add the address above as a connector in an AI assistant that supports MCP sign-in, such as Claude or ChatGPT, and choose its sign-in option. You are sent to ThinkSafe Go to log in and approve the connection. An organisation admin must do this, and ThinkSafe switches the feature on for your organisation first: ask us.
- Sign-in, option 2: an API key, sent as the header
Authorization: Bearer tsk_live_.... In Claude, add a custom connector, choose No sign-in, and add the key as anauthorizationrequest header. - Read-only. The assistant can look at records. It cannot create, change or delete anything, whatever scopes the key has.
- It sees every record in your organisation that this API returns, not just what one user can see in the app. A sign-in connection belongs to the admin who approved it and stops working if that person is removed or is no longer an admin. Give a key only to people who should see everything, and ask ThinkSafe for a separate key for each connection so one can be switched off without affecting the others.
- Each request returns at most 100 records, and each connection is limited to 1200 requests an hour. Every request is recorded in your audit log.
- Your records are sent to the AI provider you choose, under your own account with them. Check how that provider handles your data before you connect.
- An AI can misread or miscount. Check anything important against the records in ThinkSafe Go; answers should quote reference numbers so that you can.
Errors
Errors are JSON: { "error": "<code>", "details": ["..."] }. The codes used by each endpoint are listed with it.
Formats
- Ids are UUIDs. Timestamps are ISO 8601 in UTC.
- Latitude and longitude values are returned as strings, not numbers.
- Dates on people and hazardous substances are
YYYY-MM-DD. Dates on/licencesare returned as timestamps at 00:00 UTC on that date.
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
| Name | Where | Description |
|---|---|---|
limit | query | How many records to return. Default 100; anything above 500 is treated as 500. |
offset | query | How many records to skip, for paging. |
updated_since | query | Only records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z). |
status | query | Exact match on status. |
role | query | Exact match on role. |
Response
200 A page of records, oldest change first.
Each record in data:
| Field | Type | Description |
|---|---|---|
id | id | User id. |
email | text | Login email address. |
name | text | Full name. |
phone | text or null | Phone number, where recorded. |
role | text | worker, supervisor or client_admin. A ThinkSafe support account attached to your organisation appears as thinksafe_admin. |
assigned_site_ids | list of id | Ids of the sites recorded against the user. |
assigned_form_slugs | list of text or null | Form slugs recorded against the user, where per-user form access has been set. Null when not set. |
status | text | Login status. One of: active, invited, disabled. |
last_login_at | timestamp or null | Last sign-in, or null if the user has never signed in. |
created_at | timestamp | When the record was created. |
updated_at | timestamp | When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed. |
Errors
- 400
invalid_parameters: a bad limit, offset or updated_since.detailssays which. - 401
invalid_or_missing_api_key: no key, an unknown key or a revoked key. - 403
insufficient_scope: the key does not have thereadscope.
GET /sites
List sites scope: read
Work locations (jobs, branches, projects). Sites can be created and updated with a sites:write key.
Parameters
| Name | Where | Description |
|---|---|---|
limit | query | How many records to return. Default 100; anything above 500 is treated as 500. |
offset | query | How many records to skip, for paging. |
updated_since | query | Only records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z). |
job_number | query | Exact match on job number. |
status | query | active or archived. |
Response
200 A page of records, oldest change first.
Each record in data:
| Field | Type | Description |
|---|---|---|
id | id | Site id. |
name | text | Site name. |
address | text or null | Street address, where recorded. |
latitude | text or null | Latitude, where recorded. Returned as a string. |
longitude | text or null | Longitude, where recorded. Returned as a string. |
status | text | active or archived. One of: active, archived. |
site_slug | text | Short 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_number | text or null | Your job number for the site, where recorded. |
sssp_document_set_id | id or null | Id of the Site-Specific Safety Plan linked to the site, or null. Download the plan with GET /v1/sites/{id}/sssp. |
sssp_version | whole number or null | Version 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_at | timestamp or null | When 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_at | timestamp | When the record was created. |
updated_at | timestamp | When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed. |
Errors
- 400
invalid_parameters: a bad limit, offset or updated_since.detailssays which. - 401
invalid_or_missing_api_key: no key, an unknown key or a revoked key. - 403
insufficient_scope: the key does not have thereadscope.
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
| Name | Where | Description |
|---|---|---|
limit | query | How many records to return. Default 100; anything above 500 is treated as 500. |
offset | query | How many records to skip, for paging. |
updated_since | query | Only records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z). |
site_id | query | Records for one site. |
status | query | open, in_review, resolved or closed. |
submitted_by | query | Records submitted by one user (user id). |
worker_id | query | Exact match on worker_id. |
form_definition_id | query | Records of one form (id from /v1/form-definitions). |
Response
200 A page of records, oldest change first.
Each record in data:
| Field | Type | Description |
|---|---|---|
id | id | Record id. |
site_id | id or null | Site the record belongs to, where one was chosen. |
site_name | text or null | Site name: the linked site's name when there is one, otherwise the location typed on the form. |
form_definition_id | id | Which form this is. Look it up in /v1/form-definitions. |
submitted_by | id or null | User id of the person who submitted the record, where known. |
worker_id | id or null | Related worker id, where set. |
status | text | Where the record is in its close-out. One of: open, in_review, resolved, closed. |
priority | whole number or null | Priority from 1 to 5, where set. |
risk_level | text or null | Risk level. Only hazard reports set this; it is null on every other form. |
reference_number | text or null | Reference shown in the app, for example INC-0020. Can be null on older imported records. |
parent_submission_id | id or null | Id of the record this one was raised from, where there is one. |
gps_latitude | text or null | Latitude captured at submission, where available. Returned as a string. |
gps_longitude | text or null | Longitude captured at submission, where available. Returned as a string. |
submitted_at | timestamp | When the form was submitted. |
created_at | timestamp | When the record was created. |
updated_at | timestamp | When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed. |
Errors
- 400
invalid_parameters: a bad limit, offset or updated_since.detailssays which. - 401
invalid_or_missing_api_key: no key, an unknown key or a revoked key. - 403
insufficient_scope: the key does not have thereadscope.
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
| Name | Where | Description |
|---|---|---|
limit | query | How many records to return. Default 100; anything above 500 is treated as 500. |
offset | query | How many records to skip, for paging. |
updated_since | query | Only records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z). |
person_id | query | Records for one person (id from /v1/people). |
status | query | active, expiring_soon, expired or archived. |
record_type | query | Exact match on record_type. |
subject_type | query | Exact match on subject_type. |
user_id | query | Records linked to one user (user id). |
Response
200 A page of records, oldest change first.
Each record in data:
| Field | Type | Description |
|---|---|---|
id | id | Record id. |
user_id | id or null | User the record is linked to, where there is one. |
person_id | id or null | Person the record belongs to (id from /v1/people), where there is one. |
worker_name | text | Name of the person or plant item the record belongs to. |
notify_email | text or null | Contact email held on the record, where set. |
licence_type | text | Type of record, for example Full Drivers License, COF or First Aid. |
licence_type_other | text or null | Free-text type, where one was entered. |
licence_number | text or null | Licence or certificate number, where recorded. |
issuing_authority | text or null | Who issued it, where recorded. |
issue_date | timestamp or null | Issue date, where recorded. Returned as a timestamp at 00:00 UTC on that date (for example 2026-04-01T00:00:00.000Z). |
expiry_date | timestamp or null | Expiry date, where there is one. Returned as a timestamp at 00:00 UTC on that date. |
no_expiry | true/false | True when the record does not expire. |
notes | text or null | Notes, where recorded. |
status | text | active, expiring_soon, expired or archived. One of: active, expiring_soon, expired, archived. |
record_type | text | Kind of record, for example licence. |
subject_type | text | What the record is about, for example person or plant. |
competency_level | text or null | Competency level, where recorded. |
created_at | timestamp | When the record was created. |
updated_at | timestamp | When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed. |
Errors
- 400
invalid_parameters: a bad limit, offset or updated_since.detailssays which. - 401
invalid_or_missing_api_key: no key, an unknown key or a revoked key. - 403
insufficient_scope: the key does not have thereadscope.
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
| Name | Where | Description |
|---|---|---|
limit | query | How many records to return. Default 100; anything above 500 is treated as 500. |
offset | query | How many records to skip, for paging. |
updated_since | query | Only records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z). |
slug | query | Exact match on slug. |
status | query | active, draft or archived. |
category | query | Exact match on category. |
Response
200 A page of records, oldest change first.
Each record in data:
| Field | Type | Description |
|---|---|---|
id | id | Form id. Match submissions to forms on this, not on slug. |
slug | text | Short name of the form. One of your own forms can share a slug with a standard form, so match on id. |
name | text | Form name as shown in the app. |
category | text or null | Category the form sits under in the app, where set. |
status | text | active, draft or archived. One of: active, draft, archived. |
version | whole number | Version number of the form. |
created_at | timestamp | When the record was created. |
updated_at | timestamp | When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed. |
Errors
- 400
invalid_parameters: a bad limit, offset or updated_since.detailssays which. - 401
invalid_or_missing_api_key: no key, an unknown key or a revoked key. - 403
insufficient_scope: the key does not have thereadscope.
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
| Name | Where | Description |
|---|---|---|
limit | query | How many records to return. Default 100; anything above 500 is treated as 500. |
offset | query | How many records to skip, for paging. |
updated_since | query | Only records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z). |
identifier | query | Registration or serial number. Matches ignoring upper/lower case and spaces. |
asset_type | query | Exact match on asset_type. |
status | query | active or archived. |
Response
200 A page of records, oldest change first.
Each record in data:
| Field | Type | Description |
|---|---|---|
id | id | Item id. |
name | text | Make and model, or a description of the item. |
identifier | text or null | Registration or serial number, where recorded. |
asset_type | text | Type of item, for example vehicle, trailer or other. |
status | text | active or archived. One of: active, archived. |
assigned_to | id or null | Id of who the item is assigned to, where set. |
year | whole number or null | Year of manufacture, where recorded. |
colour | text or null | Colour, where recorded. |
created_at | timestamp | When the record was created. |
updated_at | timestamp | When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed. |
Errors
- 400
invalid_parameters: a bad limit, offset or updated_since.detailssays which. - 401
invalid_or_missing_api_key: no key, an unknown key or a revoked key. - 403
insufficient_scope: the key does not have thereadscope.
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
| Name | Where | Description |
|---|---|---|
limit | query | How many records to return. Default 100; anything above 500 is treated as 500. |
offset | query | How many records to skip, for paging. |
updated_since | query | Only records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z). |
status | query | Exact match on status, for example active to leave out archived substances. |
Response
200 A page of records, oldest change first.
Each record in data:
| Field | Type | Description |
|---|---|---|
id | id | Substance id. |
substance_name | text | Substance name. |
hazard_class | text or null | Hazard classification, where recorded. |
location | text or null | Where it is kept, where recorded. |
quantity | text or null | Quantity held, as entered. |
storage_segregation | text or null | Storage and segregation notes, where recorded. |
notes | text or null | Notes, where recorded. |
sds_review_date | date or null | Date the Safety Data Sheet is due for review (YYYY-MM-DD), where set. |
sds_review_status | text | no_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_review | whole number or null | Days until the review date. Negative when overdue, null when no date is set. |
has_sds | true/false | True when a Safety Data Sheet file is held for the substance. |
sds_filename | text or null | File name of the Safety Data Sheet, where one is held. |
sds_uploaded_at | timestamp or null | When the Safety Data Sheet was uploaded, where one is held. |
status | text | active or archived. |
created_at | timestamp | When the record was created. |
updated_at | timestamp | When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed. |
Errors
- 400
invalid_parameters: a bad limit, offset or updated_since.detailssays which. - 401
invalid_or_missing_api_key: no key, an unknown key or a revoked key. - 403
insufficient_scope: the key does not have thereadscope.
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
| Name | Where | Description |
|---|---|---|
limit | query | How many records to return. Default 100; anything above 500 is treated as 500. |
offset | query | How many records to skip, for paging. |
updated_since | query | Only records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z). |
external_id | query | Exact match on your own id for the person. |
email | query | Email address. Matches ignoring upper/lower case and surrounding spaces. |
status | query | active or archived. |
worker_type | query | Exact match on worker_type. |
Response
200 A page of records, oldest change first.
Each record in data:
| Field | Type | Description |
|---|---|---|
id | id | Person id. |
user_id | id or null | The person's login (user id), if they have one. |
external_id | text or null | Your own system's id for the person, where set. |
name | text | Full name. |
job_title | text or null | Job title, where recorded. |
worker_type | text | Type of worker. One of: employee, casual, contractor, apprentice, volunteer, labour_hire, other. |
employer | text or null | Employer, where recorded (for example a contractor or labour-hire company). |
site_id | id or null | Site the person is based at, where set. |
phone | text or null | Phone number, where recorded. |
email | text or null | Email address, where recorded. |
start_date | date or null | Start date (YYYY-MM-DD), where recorded. |
end_date | date or null | Last day worked (YYYY-MM-DD), where recorded. |
emergency_contact_name | text or null | Emergency contact name, where recorded. |
emergency_contact_phone | text or null | Emergency contact phone, where recorded. |
emergency_contact_relationship | text or null | Emergency contact relationship, where recorded. |
status | text | active or archived. One of: active, archived. |
created_at | timestamp | When the record was created. |
updated_at | timestamp | When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed. |
Errors
- 400
invalid_parameters: a bad limit, offset or updated_since.detailssays which. - 401
invalid_or_missing_api_key: no key, an unknown key or a revoked key. - 403
insufficient_scope: the key does not have thereadscope.
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
| Name | Where | Description |
|---|---|---|
limit | query | How many records to return. Default 100; anything above 500 is treated as 500. |
offset | query | How many records to skip, for paging. |
updated_since | query | Only records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z). |
status | query | Exact match on status: open, in_progress or closed. |
priority | query | Exact match on priority: low, medium, high or critical. |
overdue | query | true for actions past their due date and not closed; false for all others. |
assigned_to_user_id | query | Actions assigned to one user (user id). |
Response
200 A page of records, oldest change first.
Each record in data:
| Field | Type | Description |
|---|---|---|
id | id | Action id. |
description | text or null | What needs to be done. |
status | text | Status of the action: open, in_progress or closed. closed means it has been completed; the others are still outstanding. |
priority | text or null | Priority, where set: low, medium, high or critical. |
due_date | date or null | Date the action is due (YYYY-MM-DD), where set. |
overdue | true/false | True when the due date has passed and the action is not closed. Worked out against the current date in New Zealand. |
assigned_to_name | text or null | Name of the person the action is assigned to, where assigned. |
assigned_to_user_id | id or null | User id of the person the action is assigned to, where they have a login. |
closed_at | timestamp or null | When the action was closed, where it has been. |
closure_notes | text or null | Notes recorded when the action was closed, where given. |
submission_id | id or null | The submission the action was raised from, where there is one; fetch one record with GET /v1/submissions/{id}. |
reference_number | text or null | Reference number of that submission, for example INC-0003. |
form_name | text or null | Name of the form that submission was made on. |
site_name | text or null | Site that submission relates to, where recorded. |
created_at | timestamp | When the record was created. |
updated_at | timestamp | When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed. |
Errors
- 400
invalid_parameters: a bad limit, offset or updated_since.detailssays which. - 401
invalid_or_missing_api_key: no key, an unknown key or a revoked key. - 403
insufficient_scope: the key does not have thereadscope.
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
| Name | Where | Description |
|---|---|---|
limit | query | How many records to return. Default 100; anything above 500 is treated as 500. |
offset | query | How many records to skip, for paging. |
updated_since | query | Only records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z). |
status | query | Exact match on status, for example approved. |
trade | query | Exact match on trade. |
Response
200 A page of records, oldest change first.
Each record in data:
| Field | Type | Description |
|---|---|---|
id | id | Contractor id. |
name | text | Contractor name. |
trade | text or null | Trade, where recorded. |
scope | text or null | Scope of work, where recorded. |
status | text | invited (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_until | date or null | Date the approval runs to (YYYY-MM-DD), where set. |
approval_expired | true/false | True when the contractor was approved and the approved-until date has passed. Worked out against the current date in New Zealand. |
conditions | text or null | Conditions attached to the approval, where given. |
contact_name | text or null | Name of the contact person at the contractor, where recorded. |
reviewed_at | timestamp or null | When the approval decision was made, where one has been. |
next_document_expiry | date or null | Earliest expiry date among the current documents (YYYY-MM-DD), where any has one. |
expired_documents | whole number | How many current documents have passed their expiry date. |
expiring_documents | whole number | How many current documents expire within the next 30 days. |
documents | list of text | Current documents held for the contractor, one line each: type | label | expiry date. The files themselves are not available here. |
created_at | timestamp | When the record was created. |
updated_at | timestamp | When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed. |
Errors
- 400
invalid_parameters: a bad limit, offset or updated_since.detailssays which. - 401
invalid_or_missing_api_key: no key, an unknown key or a revoked key. - 403
insufficient_scope: the key does not have thereadscope.
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
| Name | Where | Description |
|---|---|---|
id required | path | Submission id. |
Response
200 The record.
Fields of data:
| Field | Type | Description |
|---|---|---|
id | id | Record id. |
site_id | id or null | Site the record belongs to, where one was chosen. |
site_name | text or null | Site name: the linked site's name when there is one, otherwise the location typed on the form. |
form_definition_id | id | Which form this is. Look it up in /v1/form-definitions. |
submitted_by | id or null | User id of the person who submitted the record, where known. |
worker_id | id or null | Related worker id, where set. |
status | text | Where the record is in its close-out. One of: open, in_review, resolved, closed. |
priority | whole number or null | Priority from 1 to 5, where set. |
risk_level | text or null | Risk level. Only hazard reports set this; it is null on every other form. |
reference_number | text or null | Reference shown in the app, for example INC-0020. Can be null on older imported records. |
parent_submission_id | id or null | Id of the record this one was raised from, where there is one. |
gps_latitude | text or null | Latitude captured at submission, where available. Returned as a string. |
gps_longitude | text or null | Longitude captured at submission, where available. Returned as a string. |
submitted_at | timestamp | When the form was submitted. |
created_at | timestamp | When the record was created. |
updated_at | timestamp | When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed. |
form_slug | text or null | Short name of the form. |
form_name | text or null | Form name as shown in the app. |
answers | list of object | The answers, in form order, labelled as your team sees them. Photos and signatures are not included. |
Errors
- 401
invalid_or_missing_api_key: no key, an unknown key or a revoked key. - 403
insufficient_scope: the key does not have thereadscope. - 404
not_found: no such record in your organisation.
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
| Name | Where | Description |
|---|---|---|
id required | path | Hazardous substance id. |
json | query | Send json=1 to get a JSON response instead of the default. |
Response
200 With json=1: the short-lived link.
Fields of data:
| Field | Type | Description |
|---|---|---|
url | text | A link to the file. It stops working after expires_in seconds, so fetch it straight away. |
expires_in | whole number | Seconds until the link expires. |
filename | text | File name. |
content_type | text | File type, for example application/pdf. |
Errors
- 401
invalid_or_missing_api_key: no key, an unknown key or a revoked key. - 403
insufficient_scope: the key does not have thereadscope. - 404
not_found: no such substance in your organisation.no_sds_on_file: the substance has no Safety Data Sheet.
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
| Name | Where | Description |
|---|---|---|
id required | path | Site id. |
json | query | Send 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:
| Field | Type | Description |
|---|---|---|
filename | text | File name. |
content_type | text | Always application/pdf. |
size_bytes | whole number | Size of the PDF in bytes, before base64 encoding. |
content_base64 | text | The PDF, base64 encoded. |
sssp_version | whole number | SSSP download only. Version number of the plan, as printed on its cover. |
sssp_updated_at | timestamp | SSSP download only. When the plan last changed, published or not. |
Errors
- 401
invalid_or_missing_api_key: no key, an unknown key or a revoked key. - 403
insufficient_scope: the key does not have thereadscope. - 404
not_found: no such site in your organisation. - 429
rate_limited: more than 600 PDF requests in the hour for this key.
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
| Name | Where | Description |
|---|---|---|
id required | path | Site id. |
json | query | Send 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:
| Field | Type | Description |
|---|---|---|
filename | text | File name. |
content_type | text | Always application/pdf. |
size_bytes | whole number | Size of the PDF in bytes, before base64 encoding. |
content_base64 | text | The PDF, base64 encoded. |
sssp_version | whole number | SSSP download only. Version number of the plan, as printed on its cover. |
sssp_updated_at | timestamp | SSSP download only. When the plan last changed, published or not. |
Errors
- 401
invalid_or_missing_api_key: no key, an unknown key or a revoked key. - 403
insufficient_scope: the key does not have thereadscope. - 404
not_found: no such site in your organisation.no_sssp_linked: the site has no plan linked. - 429
rate_limited: more than 600 PDF requests in the hour for this key.
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
| Name | Where | Description |
|---|---|---|
Idempotency-Key | header | Your 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)
| Field | Type | Description |
|---|---|---|
name required | text | Site name. Up to 255 characters. |
address | text or null | Street address, where recorded. Send null or an empty string to leave it blank. Up to 500 characters. |
job_number | text or null | Your 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:
| Field | Type | Description |
|---|---|---|
id | id | Site id. |
name | text | Site name. |
address | text or null | Street address, where recorded. |
latitude | text or null | Latitude, where recorded. Returned as a string. |
longitude | text or null | Longitude, where recorded. Returned as a string. |
status | text | active or archived. One of: active, archived. |
site_slug | text | Short 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_number | text or null | Your job number for the site, where recorded. |
sssp_document_set_id | id or null | Id of the Site-Specific Safety Plan linked to the site, or null. Download the plan with GET /v1/sites/{id}/sssp. |
sssp_version | whole number or null | Version 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_at | timestamp or null | When 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_at | timestamp | When the record was created. |
updated_at | timestamp | When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed. |
Alongside data:
| Field | Type | Description |
|---|---|---|
action | text | What happened. One of: created, updated. |
Errors
- 400
invalid_parameters(a field is wrong or unknown;detailslists each problem),invalid_body(not JSON, or over the size limit) orinvalid_idempotency_key. - 401
invalid_or_missing_api_key: no key, an unknown key or a revoked key. - 403
insufficient_scope: the key does not have thesites:writescope. - 409
conflict: another request changed the same record at the same moment. Send it again. - 422
idempotency_key_reused: this Idempotency-Key was already used with a different body.
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
| Name | Where | Description |
|---|---|---|
Idempotency-Key | header | Your 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)
| Field | Type | Description | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
external_id | text or null | Your 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. | |||||||||||||||
name | text | Full name. Up to 150 characters. | |||||||||||||||
job_title | text or null | Job title, where recorded. Send null or an empty string to clear it. Up to 100 characters. | |||||||||||||||
worker_type | text | Type of worker. One of: employee, casual, contractor, apprentice, volunteer, labour_hire, other. | |||||||||||||||
employer | text or null | Employer, where recorded (for example a contractor or labour-hire company). Send null or an empty string to clear it. Up to 150 characters. | |||||||||||||||
phone | text or null | Phone number, where recorded. Send null or an empty string to clear it. Up to 50 characters. | |||||||||||||||
email | email or null | Email address, where recorded. Send null or an empty string to clear it. Up to 255 characters. | |||||||||||||||
start_date | date or null | Start date (YYYY-MM-DD), where recorded. Send null or an empty string to clear it. | |||||||||||||||
end_date | date or null | Last day worked (YYYY-MM-DD), where recorded. Send null or an empty string to clear it. | |||||||||||||||
emergency_contact_name | text or null | Emergency contact name, where recorded. Send null or an empty string to clear it. Up to 150 characters. | |||||||||||||||
emergency_contact_phone | text or null | Emergency contact phone, where recorded. Send null or an empty string to clear it. Up to 50 characters. | |||||||||||||||
emergency_contact_relationship | text or null | Emergency contact relationship, where recorded. Send null or an empty string to clear it. Up to 60 characters. | |||||||||||||||
invite | true/false | Send 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. | |||||||||||||||
role | text | Role for the login when invite is true. One of: worker, supervisor. | |||||||||||||||
login_enabled | true/false | Switch 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_licence | object | Create 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.
|
Response
200 An existing person was updated. 201 A new person was created.
Fields of data:
| Field | Type | Description |
|---|---|---|
id | id | Person id. |
user_id | id or null | The person's login (user id), if they have one. |
external_id | text or null | Your own system's id for the person, where set. |
name | text | Full name. |
job_title | text or null | Job title, where recorded. |
worker_type | text | Type of worker. One of: employee, casual, contractor, apprentice, volunteer, labour_hire, other. |
employer | text or null | Employer, where recorded (for example a contractor or labour-hire company). |
site_id | id or null | Site the person is based at, where set. |
phone | text or null | Phone number, where recorded. |
email | text or null | Email address, where recorded. |
start_date | date or null | Start date (YYYY-MM-DD), where recorded. |
end_date | date or null | Last day worked (YYYY-MM-DD), where recorded. |
emergency_contact_name | text or null | Emergency contact name, where recorded. |
emergency_contact_phone | text or null | Emergency contact phone, where recorded. |
emergency_contact_relationship | text or null | Emergency contact relationship, where recorded. |
status | text | active or archived. One of: active, archived. |
created_at | timestamp | When the record was created. |
updated_at | timestamp | When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed. |
Alongside data:
| Field | Type | Description | |||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
action | text | What happened. One of: created, updated. | |||||||||||||||||||||||||||||||||
invite | object | Present when invite was sent in the request.
| |||||||||||||||||||||||||||||||||
login | object | Present when the request changed the state of the person's login.
| |||||||||||||||||||||||||||||||||
driver_licence | object | Present when driver_licence was sent in the request.
|
Errors
- 400
invalid_parameters(a field is wrong or unknown;detailslists each problem),invalid_body(not JSON, or over the size limit) orinvalid_idempotency_key. - 401
invalid_or_missing_api_key: no key, an unknown key or a revoked key. - 403
insufficient_scope: the key does not have thepeople:writescope. - 409
ambiguous_email: several people share this email, so update by id instead.external_id_mismatch: the person with this email is linked to a different external_id.conflict: a concurrent change; send it again. - 422
idempotency_key_reused: this Idempotency-Key was already used with a different body.
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
| Name | Where | Description |
|---|---|---|
id required | path | Site id. |
Idempotency-Key | header | Your 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)
| Field | Type | Description |
|---|---|---|
name | text | Site name. Up to 255 characters. |
address | text or null | Street address, where recorded. Send null or an empty string to leave it blank. Up to 500 characters. |
job_number | text or null | Your 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. |
status | text | Set 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:
| Field | Type | Description |
|---|---|---|
id | id | Site id. |
name | text | Site name. |
address | text or null | Street address, where recorded. |
latitude | text or null | Latitude, where recorded. Returned as a string. |
longitude | text or null | Longitude, where recorded. Returned as a string. |
status | text | active or archived. One of: active, archived. |
site_slug | text | Short 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_number | text or null | Your job number for the site, where recorded. |
sssp_document_set_id | id or null | Id of the Site-Specific Safety Plan linked to the site, or null. Download the plan with GET /v1/sites/{id}/sssp. |
sssp_version | whole number or null | Version 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_at | timestamp or null | When 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_at | timestamp | When the record was created. |
updated_at | timestamp | When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed. |
Alongside data:
| Field | Type | Description |
|---|---|---|
action | text | What happened. One of: created, updated. |
Errors
- 400
invalid_parameters(a field is wrong or unknown;detailslists each problem),invalid_body(not JSON, or over the size limit) orinvalid_idempotency_key. - 401
invalid_or_missing_api_key: no key, an unknown key or a revoked key. - 403
insufficient_scope: the key does not have thesites:writescope. - 404
not_found: no such record in your organisation. - 409
conflict: another request changed the same record at the same moment. Send it again. - 422
idempotency_key_reused: this Idempotency-Key was already used with a different body.
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
| Name | Where | Description |
|---|---|---|
id required | path | Person id. |
Idempotency-Key | header | Your 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)
| Field | Type | Description | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
external_id | text or null | Your 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. | |||||||||||||||
name | text | Full name. Up to 150 characters. | |||||||||||||||
job_title | text or null | Job title, where recorded. Send null or an empty string to clear it. Up to 100 characters. | |||||||||||||||
worker_type | text | Type of worker. One of: employee, casual, contractor, apprentice, volunteer, labour_hire, other. | |||||||||||||||
employer | text or null | Employer, where recorded (for example a contractor or labour-hire company). Send null or an empty string to clear it. Up to 150 characters. | |||||||||||||||
phone | text or null | Phone number, where recorded. Send null or an empty string to clear it. Up to 50 characters. | |||||||||||||||
email | email or null | Email address, where recorded. Send null or an empty string to clear it. Up to 255 characters. | |||||||||||||||
start_date | date or null | Start date (YYYY-MM-DD), where recorded. Send null or an empty string to clear it. | |||||||||||||||
end_date | date or null | Last day worked (YYYY-MM-DD), where recorded. Send null or an empty string to clear it. | |||||||||||||||
emergency_contact_name | text or null | Emergency contact name, where recorded. Send null or an empty string to clear it. Up to 150 characters. | |||||||||||||||
emergency_contact_phone | text or null | Emergency contact phone, where recorded. Send null or an empty string to clear it. Up to 50 characters. | |||||||||||||||
emergency_contact_relationship | text or null | Emergency contact relationship, where recorded. Send null or an empty string to clear it. Up to 60 characters. | |||||||||||||||
invite | true/false | Send 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. | |||||||||||||||
role | text | Role for the login when invite is true. One of: worker, supervisor. | |||||||||||||||
login_enabled | true/false | Switch 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_licence | object | Create 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.
|
Response
200 The person after the change.
Fields of data:
| Field | Type | Description |
|---|---|---|
id | id | Person id. |
user_id | id or null | The person's login (user id), if they have one. |
external_id | text or null | Your own system's id for the person, where set. |
name | text | Full name. |
job_title | text or null | Job title, where recorded. |
worker_type | text | Type of worker. One of: employee, casual, contractor, apprentice, volunteer, labour_hire, other. |
employer | text or null | Employer, where recorded (for example a contractor or labour-hire company). |
site_id | id or null | Site the person is based at, where set. |
phone | text or null | Phone number, where recorded. |
email | text or null | Email address, where recorded. |
start_date | date or null | Start date (YYYY-MM-DD), where recorded. |
end_date | date or null | Last day worked (YYYY-MM-DD), where recorded. |
emergency_contact_name | text or null | Emergency contact name, where recorded. |
emergency_contact_phone | text or null | Emergency contact phone, where recorded. |
emergency_contact_relationship | text or null | Emergency contact relationship, where recorded. |
status | text | active or archived. One of: active, archived. |
created_at | timestamp | When the record was created. |
updated_at | timestamp | When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed. |
Alongside data:
| Field | Type | Description | |||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
action | text | What happened. One of: created, updated. | |||||||||||||||||||||||||||||||||
invite | object | Present when invite was sent in the request.
| |||||||||||||||||||||||||||||||||
login | object | Present when the request changed the state of the person's login.
| |||||||||||||||||||||||||||||||||
driver_licence | object | Present when driver_licence was sent in the request.
|
Errors
- 400
invalid_parameters(a field is wrong or unknown;detailslists each problem),invalid_body(not JSON, or over the size limit) orinvalid_idempotency_key. - 401
invalid_or_missing_api_key: no key, an unknown key or a revoked key. - 403
insufficient_scope: the key does not have thepeople:writescope. - 404
not_found: no such record in your organisation. - 409
conflict: another request changed the same record at the same moment. Send it again. - 422
idempotency_key_reused: this Idempotency-Key was already used with a different body.