{
  "openapi": "3.1.0",
  "info": {
    "title": "ThinkSafe Go API",
    "version": "1",
    "description": "Read your ThinkSafe Go data from your own systems, and write people and sites into it.\n\n## Keys\nEvery request carries an API key in the Authorization header: `Authorization: Bearer tsk_live_...`\n- Keys are issued by ThinkSafe on request. A key is shown once, when it is issued; ThinkSafe keeps only a hash of it.\n- A key belongs to one organisation and can only ever see or change that organisation's data.\n- A key can be revoked at any time and stops working immediately.\n\n## Scopes\nEach key carries scopes that say what it may do.\n- `read`: every GET endpoint.\n- `people:write`: create and update people.\n- `sites:write`: create and update sites.\nA request the key is not scoped for gets 403 `insufficient_scope`, with the scope it would need.\n\n## Lists\nList 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.\n- Records come oldest change first. To pick up only what has changed, send `updated_since` with the time of your last sync.\n- Filters are exact matches on the fields listed for each endpoint. Query parameters the API does not know are ignored.\n- Sample data that comes with a trial account is never returned.\n\n## Writing\nSend JSON (up to 64 KB). A field the API does not know is rejected with 400, never silently dropped.\n- Send an `Idempotency-Key` header 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 header `Idempotent-Replayed: true` and nothing is written twice. The same key with a different body gets 422.\n- Every write is recorded in your organisation's audit log against the key that made it.\n\n## Files\nFiles 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.\n- PDF generation is limited to 600 requests an hour per key (429 `rate_limited` beyond that). Each PDF takes a few seconds.\n\n## AI assistants\nYou 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).\n- Address: `https://mcp.go.thinksafe.co.nz/api/v1/mcp`\n- 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.\n- 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 an `authorization` request header.\n- Read-only. The assistant can look at records. It cannot create, change or delete anything, whatever scopes the key has.\n- 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.\n- 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.\n- 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.\n- An AI can misread or miscount. Check anything important against the records in ThinkSafe Go; answers should quote reference numbers so that you can.\n\n## Errors\nErrors are JSON: `{ \"error\": \"<code>\", \"details\": [\"...\"] }`. The codes used by each endpoint are listed with it.\n\n## Formats\n- Ids are UUIDs. Timestamps are ISO 8601 in UTC.\n- Latitude and longitude values are returned as strings, not numbers.\n- Dates on people and hazardous substances are `YYYY-MM-DD`. Dates on `/licences` are returned as timestamps at 00:00 UTC on that date.\n\n## Changes\nThis 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."
  },
  "servers": [
    {
      "url": "https://thinksafe-go-api-flex.azurewebsites.net/api/v1"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "tags": [
    {
      "name": "Reading",
      "description": "Lists and single records. Scope: read."
    },
    {
      "name": "Files",
      "description": "Documents and PDFs. Scope: read."
    },
    {
      "name": "Writing",
      "description": "Create and update people and sites. Scope: people:write or sites:write."
    }
  ],
  "paths": {
    "/users": {
      "get": {
        "operationId": "list_users",
        "tags": [
          "Reading"
        ],
        "summary": "List users",
        "description": "People with a ThinkSafe Go login in your organisation.",
        "x-required-scope": "read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            },
            "description": "How many records to return. Default 100; anything above 500 is treated as 500."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "How many records to skip, for paging."
          },
          {
            "name": "updated_since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Only records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z)."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact match on status."
          },
          {
            "name": "role",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact match on role."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of records, oldest change first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/User"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`invalid_parameters`: a bad limit, offset or updated_since. `details` says which.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`invalid_or_missing_api_key`: no key, an unknown key or a revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`: the key does not have the `read` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sites": {
      "get": {
        "operationId": "list_sites",
        "tags": [
          "Reading"
        ],
        "summary": "List sites",
        "description": "Work locations (jobs, branches, projects). Sites can be created and updated with a sites:write key.",
        "x-required-scope": "read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            },
            "description": "How many records to return. Default 100; anything above 500 is treated as 500."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "How many records to skip, for paging."
          },
          {
            "name": "updated_since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Only records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z)."
          },
          {
            "name": "job_number",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact match on job number."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "active or archived."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of records, oldest change first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Site"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`invalid_parameters`: a bad limit, offset or updated_since. `details` says which.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`invalid_or_missing_api_key`: no key, an unknown key or a revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`: the key does not have the `read` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "create_site",
        "tags": [
          "Writing"
        ],
        "summary": "Create a site",
        "x-required-scope": "sites:write",
        "description": "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": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 200,
              "pattern": "^[A-Za-z0-9_\\-:.]{8,200}$"
            },
            "description": "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."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SiteCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The site that was created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiteWriteResult"
                }
              }
            }
          },
          "400": {
            "description": "`invalid_parameters` (a field is wrong or unknown; `details` lists each problem), `invalid_body` (not JSON, or over the size limit) or `invalid_idempotency_key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`invalid_or_missing_api_key`: no key, an unknown key or a revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`: the key does not have the `sites:write` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`conflict`: another request changed the same record at the same moment. Send it again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "`idempotency_key_reused`: this Idempotency-Key was already used with a different body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/submissions": {
      "get": {
        "operationId": "list_submissions",
        "tags": [
          "Reading"
        ],
        "summary": "List submissions",
        "description": "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.",
        "x-required-scope": "read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            },
            "description": "How many records to return. Default 100; anything above 500 is treated as 500."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "How many records to skip, for paging."
          },
          {
            "name": "updated_since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Only records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z)."
          },
          {
            "name": "site_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Records for one site."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "open, in_review, resolved or closed."
          },
          {
            "name": "submitted_by",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Records submitted by one user (user id)."
          },
          {
            "name": "worker_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact match on worker_id."
          },
          {
            "name": "form_definition_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Records of one form (id from /v1/form-definitions)."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of records, oldest change first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Submission"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`invalid_parameters`: a bad limit, offset or updated_since. `details` says which.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`invalid_or_missing_api_key`: no key, an unknown key or a revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`: the key does not have the `read` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/licences": {
      "get": {
        "operationId": "list_licences",
        "tags": [
          "Reading"
        ],
        "summary": "List licences and dated records",
        "description": "Licences, training, certificates and other dated records, for people and for plant and equipment (WOF, COF, registration and so on).",
        "x-required-scope": "read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            },
            "description": "How many records to return. Default 100; anything above 500 is treated as 500."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "How many records to skip, for paging."
          },
          {
            "name": "updated_since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Only records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z)."
          },
          {
            "name": "person_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Records for one person (id from /v1/people)."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "active, expiring_soon, expired or archived."
          },
          {
            "name": "record_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact match on record_type."
          },
          {
            "name": "subject_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact match on subject_type."
          },
          {
            "name": "user_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Records linked to one user (user id)."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of records, oldest change first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Licence"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`invalid_parameters`: a bad limit, offset or updated_since. `details` says which.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`invalid_or_missing_api_key`: no key, an unknown key or a revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`: the key does not have the `read` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/form-definitions": {
      "get": {
        "operationId": "list_form_definitions",
        "tags": [
          "Reading"
        ],
        "summary": "List form definitions",
        "description": "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.",
        "x-required-scope": "read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            },
            "description": "How many records to return. Default 100; anything above 500 is treated as 500."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "How many records to skip, for paging."
          },
          {
            "name": "updated_since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Only records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z)."
          },
          {
            "name": "slug",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact match on slug."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "active, draft or archived."
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact match on category."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of records, oldest change first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/FormDefinition"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`invalid_parameters`: a bad limit, offset or updated_since. `details` says which.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`invalid_or_missing_api_key`: no key, an unknown key or a revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`: the key does not have the `read` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/assets": {
      "get": {
        "operationId": "list_assets",
        "tags": [
          "Reading"
        ],
        "summary": "List plant and equipment",
        "description": "The plant and equipment register: vehicles, trailers and other items. Their dated records (WOF, COF, registration and so on) are on /v1/licences.",
        "x-required-scope": "read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            },
            "description": "How many records to return. Default 100; anything above 500 is treated as 500."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "How many records to skip, for paging."
          },
          {
            "name": "updated_since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Only records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z)."
          },
          {
            "name": "identifier",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Registration or serial number. Matches ignoring upper/lower case and spaces."
          },
          {
            "name": "asset_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact match on asset_type."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "active or archived."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of records, oldest change first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Asset"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`invalid_parameters`: a bad limit, offset or updated_since. `details` says which.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`invalid_or_missing_api_key`: no key, an unknown key or a revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`: the key does not have the `read` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/hazardous-substances": {
      "get": {
        "operationId": "list_hazardous_substances",
        "tags": [
          "Reading"
        ],
        "summary": "List hazardous substances",
        "description": "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.",
        "x-required-scope": "read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            },
            "description": "How many records to return. Default 100; anything above 500 is treated as 500."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "How many records to skip, for paging."
          },
          {
            "name": "updated_since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Only records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z)."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact match on status, for example active to leave out archived substances."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of records, oldest change first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/HazardousSubstance"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`invalid_parameters`: a bad limit, offset or updated_since. `details` says which.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`invalid_or_missing_api_key`: no key, an unknown key or a revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`: the key does not have the `read` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/people": {
      "get": {
        "operationId": "list_people",
        "tags": [
          "Reading"
        ],
        "summary": "List people",
        "description": "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.",
        "x-required-scope": "read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            },
            "description": "How many records to return. Default 100; anything above 500 is treated as 500."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "How many records to skip, for paging."
          },
          {
            "name": "updated_since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Only records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z)."
          },
          {
            "name": "external_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact match on your own id for the person."
          },
          {
            "name": "email",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Email address. Matches ignoring upper/lower case and surrounding spaces."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "active or archived."
          },
          {
            "name": "worker_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact match on worker_type."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of records, oldest change first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Person"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`invalid_parameters`: a bad limit, offset or updated_since. `details` says which.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`invalid_or_missing_api_key`: no key, an unknown key or a revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`: the key does not have the `read` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "upsert_person",
        "tags": [
          "Writing"
        ],
        "summary": "Create or update a person",
        "x-required-scope": "people:write",
        "description": "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": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 200,
              "pattern": "^[A-Za-z0-9_\\-:.]{8,200}$"
            },
            "description": "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."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PersonWrite"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "An existing person was updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PersonWriteResult"
                }
              }
            }
          },
          "201": {
            "description": "A new person was created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PersonWriteResult"
                }
              }
            }
          },
          "400": {
            "description": "`invalid_parameters` (a field is wrong or unknown; `details` lists each problem), `invalid_body` (not JSON, or over the size limit) or `invalid_idempotency_key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`invalid_or_missing_api_key`: no key, an unknown key or a revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`: the key does not have the `people:write` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`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.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "`idempotency_key_reused`: this Idempotency-Key was already used with a different body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/actions": {
      "get": {
        "operationId": "list_actions",
        "tags": [
          "Reading"
        ],
        "summary": "List actions",
        "description": "The actions register: corrective and follow-up actions, who each one is assigned to, when it is due and whether it has been closed.",
        "x-required-scope": "read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            },
            "description": "How many records to return. Default 100; anything above 500 is treated as 500."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "How many records to skip, for paging."
          },
          {
            "name": "updated_since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Only records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z)."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact match on status: open, in_progress or closed."
          },
          {
            "name": "priority",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact match on priority: low, medium, high or critical."
          },
          {
            "name": "overdue",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "true for actions past their due date and not closed; false for all others."
          },
          {
            "name": "assigned_to_user_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Actions assigned to one user (user id)."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of records, oldest change first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Actions"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`invalid_parameters`: a bad limit, offset or updated_since. `details` says which.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`invalid_or_missing_api_key`: no key, an unknown key or a revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`: the key does not have the `read` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/contractors": {
      "get": {
        "operationId": "list_contractors",
        "tags": [
          "Reading"
        ],
        "summary": "List contractors",
        "description": "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.",
        "x-required-scope": "read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            },
            "description": "How many records to return. Default 100; anything above 500 is treated as 500."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "How many records to skip, for paging."
          },
          {
            "name": "updated_since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Only records changed after this time (ISO 8601, for example 2026-11-01T00:00:00Z)."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact match on status, for example approved."
          },
          {
            "name": "trade",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact match on trade."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of records, oldest change first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Contractors"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`invalid_parameters`: a bad limit, offset or updated_since. `details` says which.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`invalid_or_missing_api_key`: no key, an unknown key or a revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`: the key does not have the `read` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/submissions/{id}": {
      "get": {
        "operationId": "get_submission",
        "tags": [
          "Reading"
        ],
        "summary": "Get one submission with its answers",
        "x-required-scope": "read",
        "description": "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": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Submission id."
          }
        ],
        "responses": {
          "200": {
            "description": "The record.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SubmissionDetail"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "`invalid_or_missing_api_key`: no key, an unknown key or a revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`: the key does not have the `read` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such record in your organisation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/hazardous-substances/{id}/sds": {
      "get": {
        "operationId": "get_hazardous_substance_sds",
        "tags": [
          "Files"
        ],
        "summary": "Get a Safety Data Sheet",
        "x-required-scope": "read",
        "description": "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": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Hazardous substance id."
          },
          {
            "name": "json",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "description": "Send `json=1` to get a JSON response instead of the default."
          }
        ],
        "responses": {
          "200": {
            "description": "With `json=1`: the short-lived link.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/FileLink"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "302": {
            "description": "Redirect to the short-lived link."
          },
          "401": {
            "description": "`invalid_or_missing_api_key`: no key, an unknown key or a revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`: the key does not have the `read` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such substance in your organisation. `no_sds_on_file`: the substance has no Safety Data Sheet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sites/{id}/qr-poster": {
      "get": {
        "operationId": "get_site_qr_poster",
        "tags": [
          "Files"
        ],
        "summary": "Download a site QR poster",
        "x-required-scope": "read",
        "description": "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": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Site id."
          },
          {
            "name": "json",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "description": "Send `json=1` to get a JSON response instead of the default."
          }
        ],
        "responses": {
          "200": {
            "description": "The PDF. With `json=1`, a JSON object holding the PDF base64 encoded.",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/FileContent"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "`invalid_or_missing_api_key`: no key, an unknown key or a revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`: the key does not have the `read` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such site in your organisation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: more than 600 PDF requests in the hour for this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sites/{id}/sssp": {
      "get": {
        "operationId": "get_site_sssp",
        "tags": [
          "Files"
        ],
        "summary": "Download the Site-Specific Safety Plan linked to a site",
        "x-required-scope": "read",
        "description": "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": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Site id."
          },
          {
            "name": "json",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "description": "Send `json=1` to get a JSON response instead of the default."
          }
        ],
        "responses": {
          "200": {
            "description": "The PDF. With `json=1`, a JSON object holding the PDF base64 encoded.",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/FileContent"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "`invalid_or_missing_api_key`: no key, an unknown key or a revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`: the key does not have the `read` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such site in your organisation. `no_sssp_linked`: the site has no plan linked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: more than 600 PDF requests in the hour for this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sites/{id}": {
      "patch": {
        "operationId": "update_site",
        "tags": [
          "Writing"
        ],
        "summary": "Rename, update or archive a site",
        "x-required-scope": "sites:write",
        "description": "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": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Site id."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 200,
              "pattern": "^[A-Za-z0-9_\\-:.]{8,200}$"
            },
            "description": "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."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SiteUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The site after the change.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiteWriteResult"
                }
              }
            }
          },
          "400": {
            "description": "`invalid_parameters` (a field is wrong or unknown; `details` lists each problem), `invalid_body` (not JSON, or over the size limit) or `invalid_idempotency_key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`invalid_or_missing_api_key`: no key, an unknown key or a revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`: the key does not have the `sites:write` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such record in your organisation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`conflict`: another request changed the same record at the same moment. Send it again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "`idempotency_key_reused`: this Idempotency-Key was already used with a different body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/people/{id}": {
      "patch": {
        "operationId": "update_person",
        "tags": [
          "Writing"
        ],
        "summary": "Update a person by id",
        "x-required-scope": "people:write",
        "description": "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": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Person id."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 200,
              "pattern": "^[A-Za-z0-9_\\-:.]{8,200}$"
            },
            "description": "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."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PersonWrite"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The person after the change.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PersonWriteResult"
                }
              }
            }
          },
          "400": {
            "description": "`invalid_parameters` (a field is wrong or unknown; `details` lists each problem), `invalid_body` (not JSON, or over the size limit) or `invalid_idempotency_key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`invalid_or_missing_api_key`: no key, an unknown key or a revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`: the key does not have the `people:write` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such record in your organisation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`conflict`: another request changed the same record at the same moment. Send it again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "`idempotency_key_reused`: this Idempotency-Key was already used with a different body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "ThinkSafe Go API key, sent as: Authorization: Bearer tsk_live_..."
      }
    },
    "schemas": {
      "User": {
        "type": "object",
        "description": "People with a ThinkSafe Go login in your organisation.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "User id."
          },
          "email": {
            "type": "string",
            "description": "Login email address."
          },
          "name": {
            "type": "string",
            "description": "Full name."
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "description": "Phone number, where recorded."
          },
          "role": {
            "type": "string",
            "description": "worker, supervisor or client_admin. A ThinkSafe support account attached to your organisation appears as thinksafe_admin."
          },
          "assigned_site_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Ids of the sites recorded against the user."
          },
          "assigned_form_slugs": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Form slugs recorded against the user, where per-user form access has been set. Null when not set."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "invited",
              "disabled"
            ],
            "description": "Login status."
          },
          "last_login_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Last sign-in, or null if the user has never signed in."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed."
          }
        },
        "required": [
          "id",
          "email",
          "name",
          "phone",
          "role",
          "assigned_site_ids",
          "assigned_form_slugs",
          "status",
          "last_login_at",
          "created_at",
          "updated_at"
        ]
      },
      "Site": {
        "type": "object",
        "description": "Work locations (jobs, branches, projects). Sites can be created and updated with a sites:write key.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Site id."
          },
          "name": {
            "type": "string",
            "description": "Site name."
          },
          "address": {
            "type": [
              "string",
              "null"
            ],
            "description": "Street address, where recorded."
          },
          "latitude": {
            "type": [
              "string",
              "null"
            ],
            "description": "Latitude, where recorded. Returned as a string."
          },
          "longitude": {
            "type": [
              "string",
              "null"
            ],
            "description": "Longitude, where recorded. Returned as a string."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "archived"
            ],
            "description": "active or archived."
          },
          "site_slug": {
            "type": "string",
            "description": "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": {
            "type": [
              "string",
              "null"
            ],
            "description": "Your job number for the site, where recorded."
          },
          "sssp_document_set_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Id of the Site-Specific Safety Plan linked to the site, or null. Download the plan with GET /v1/sites/{id}/sssp."
          },
          "sssp_version": {
            "type": [
              "integer",
              "null"
            ],
            "description": "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": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "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": {
            "type": "string",
            "format": "date-time",
            "description": "When the record was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed."
          }
        },
        "required": [
          "id",
          "name",
          "address",
          "latitude",
          "longitude",
          "status",
          "site_slug",
          "job_number",
          "sssp_document_set_id",
          "sssp_version",
          "sssp_updated_at",
          "created_at",
          "updated_at"
        ]
      },
      "Submission": {
        "type": "object",
        "description": "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.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Record id."
          },
          "site_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Site the record belongs to, where one was chosen."
          },
          "site_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Site name: the linked site's name when there is one, otherwise the location typed on the form."
          },
          "form_definition_id": {
            "type": "string",
            "format": "uuid",
            "description": "Which form this is. Look it up in /v1/form-definitions."
          },
          "submitted_by": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "User id of the person who submitted the record, where known."
          },
          "worker_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Related worker id, where set."
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "in_review",
              "resolved",
              "closed"
            ],
            "description": "Where the record is in its close-out."
          },
          "priority": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "maximum": 5,
            "description": "Priority from 1 to 5, where set."
          },
          "risk_level": {
            "type": [
              "string",
              "null"
            ],
            "description": "Risk level. Only hazard reports set this; it is null on every other form."
          },
          "reference_number": {
            "type": [
              "string",
              "null"
            ],
            "description": "Reference shown in the app, for example INC-0020. Can be null on older imported records."
          },
          "parent_submission_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Id of the record this one was raised from, where there is one."
          },
          "gps_latitude": {
            "type": [
              "string",
              "null"
            ],
            "description": "Latitude captured at submission, where available. Returned as a string."
          },
          "gps_longitude": {
            "type": [
              "string",
              "null"
            ],
            "description": "Longitude captured at submission, where available. Returned as a string."
          },
          "submitted_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the form was submitted."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed."
          }
        },
        "required": [
          "id",
          "site_id",
          "site_name",
          "form_definition_id",
          "submitted_by",
          "worker_id",
          "status",
          "priority",
          "risk_level",
          "reference_number",
          "parent_submission_id",
          "gps_latitude",
          "gps_longitude",
          "submitted_at",
          "created_at",
          "updated_at"
        ]
      },
      "Licence": {
        "type": "object",
        "description": "Licences, training, certificates and other dated records, for people and for plant and equipment (WOF, COF, registration and so on).",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Record id."
          },
          "user_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "User the record is linked to, where there is one."
          },
          "person_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Person the record belongs to (id from /v1/people), where there is one."
          },
          "worker_name": {
            "type": "string",
            "description": "Name of the person or plant item the record belongs to."
          },
          "notify_email": {
            "type": [
              "string",
              "null"
            ],
            "description": "Contact email held on the record, where set."
          },
          "licence_type": {
            "type": "string",
            "description": "Type of record, for example Full Drivers License, COF or First Aid."
          },
          "licence_type_other": {
            "type": [
              "string",
              "null"
            ],
            "description": "Free-text type, where one was entered."
          },
          "licence_number": {
            "type": [
              "string",
              "null"
            ],
            "description": "Licence or certificate number, where recorded."
          },
          "issuing_authority": {
            "type": [
              "string",
              "null"
            ],
            "description": "Who issued it, where recorded."
          },
          "issue_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "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": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Expiry date, where there is one. Returned as a timestamp at 00:00 UTC on that date."
          },
          "no_expiry": {
            "type": "boolean",
            "description": "True when the record does not expire."
          },
          "notes": {
            "type": [
              "string",
              "null"
            ],
            "description": "Notes, where recorded."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "expiring_soon",
              "expired",
              "archived"
            ],
            "description": "active, expiring_soon, expired or archived."
          },
          "record_type": {
            "type": "string",
            "description": "Kind of record, for example licence."
          },
          "subject_type": {
            "type": "string",
            "description": "What the record is about, for example person or plant."
          },
          "competency_level": {
            "type": [
              "string",
              "null"
            ],
            "description": "Competency level, where recorded."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed."
          }
        },
        "required": [
          "id",
          "user_id",
          "person_id",
          "worker_name",
          "notify_email",
          "licence_type",
          "licence_type_other",
          "licence_number",
          "issuing_authority",
          "issue_date",
          "expiry_date",
          "no_expiry",
          "notes",
          "status",
          "record_type",
          "subject_type",
          "competency_level",
          "created_at",
          "updated_at"
        ]
      },
      "FormDefinition": {
        "type": "object",
        "description": "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.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Form id. Match submissions to forms on this, not on slug."
          },
          "slug": {
            "type": "string",
            "description": "Short name of the form. One of your own forms can share a slug with a standard form, so match on id."
          },
          "name": {
            "type": "string",
            "description": "Form name as shown in the app."
          },
          "category": {
            "type": [
              "string",
              "null"
            ],
            "description": "Category the form sits under in the app, where set."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "draft",
              "archived"
            ],
            "description": "active, draft or archived."
          },
          "version": {
            "type": "integer",
            "description": "Version number of the form."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed."
          }
        },
        "required": [
          "id",
          "slug",
          "name",
          "category",
          "status",
          "version",
          "created_at",
          "updated_at"
        ]
      },
      "Asset": {
        "type": "object",
        "description": "The plant and equipment register: vehicles, trailers and other items. Their dated records (WOF, COF, registration and so on) are on /v1/licences.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Item id."
          },
          "name": {
            "type": "string",
            "description": "Make and model, or a description of the item."
          },
          "identifier": {
            "type": [
              "string",
              "null"
            ],
            "description": "Registration or serial number, where recorded."
          },
          "asset_type": {
            "type": "string",
            "description": "Type of item, for example vehicle, trailer or other."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "archived"
            ],
            "description": "active or archived."
          },
          "assigned_to": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Id of who the item is assigned to, where set."
          },
          "year": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Year of manufacture, where recorded."
          },
          "colour": {
            "type": [
              "string",
              "null"
            ],
            "description": "Colour, where recorded."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed."
          }
        },
        "required": [
          "id",
          "name",
          "identifier",
          "asset_type",
          "status",
          "assigned_to",
          "year",
          "colour",
          "created_at",
          "updated_at"
        ]
      },
      "HazardousSubstance": {
        "type": "object",
        "description": "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.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Substance id."
          },
          "substance_name": {
            "type": "string",
            "description": "Substance name."
          },
          "hazard_class": {
            "type": [
              "string",
              "null"
            ],
            "description": "Hazard classification, where recorded."
          },
          "location": {
            "type": [
              "string",
              "null"
            ],
            "description": "Where it is kept, where recorded."
          },
          "quantity": {
            "type": [
              "string",
              "null"
            ],
            "description": "Quantity held, as entered."
          },
          "storage_segregation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Storage and segregation notes, where recorded."
          },
          "notes": {
            "type": [
              "string",
              "null"
            ],
            "description": "Notes, where recorded."
          },
          "sds_review_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date the Safety Data Sheet is due for review (YYYY-MM-DD), where set."
          },
          "sds_review_status": {
            "type": "string",
            "enum": [
              "no_date",
              "overdue",
              "due_soon",
              "current"
            ],
            "description": "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."
          },
          "days_to_review": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Days until the review date. Negative when overdue, null when no date is set."
          },
          "has_sds": {
            "type": "boolean",
            "description": "True when a Safety Data Sheet file is held for the substance."
          },
          "sds_filename": {
            "type": [
              "string",
              "null"
            ],
            "description": "File name of the Safety Data Sheet, where one is held."
          },
          "sds_uploaded_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the Safety Data Sheet was uploaded, where one is held."
          },
          "status": {
            "type": "string",
            "description": "active or archived."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed."
          }
        },
        "required": [
          "id",
          "substance_name",
          "hazard_class",
          "location",
          "quantity",
          "storage_segregation",
          "notes",
          "sds_review_date",
          "sds_review_status",
          "days_to_review",
          "has_sds",
          "sds_filename",
          "sds_uploaded_at",
          "status",
          "created_at",
          "updated_at"
        ]
      },
      "Person": {
        "type": "object",
        "description": "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.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Person id."
          },
          "user_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "The person's login (user id), if they have one."
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Your own system's id for the person, where set."
          },
          "name": {
            "type": "string",
            "description": "Full name."
          },
          "job_title": {
            "type": [
              "string",
              "null"
            ],
            "description": "Job title, where recorded."
          },
          "worker_type": {
            "type": "string",
            "enum": [
              "employee",
              "casual",
              "contractor",
              "apprentice",
              "volunteer",
              "labour_hire",
              "other"
            ],
            "description": "Type of worker."
          },
          "employer": {
            "type": [
              "string",
              "null"
            ],
            "description": "Employer, where recorded (for example a contractor or labour-hire company)."
          },
          "site_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Site the person is based at, where set."
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "description": "Phone number, where recorded."
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "description": "Email address, where recorded."
          },
          "start_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Start date (YYYY-MM-DD), where recorded."
          },
          "end_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Last day worked (YYYY-MM-DD), where recorded."
          },
          "emergency_contact_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Emergency contact name, where recorded."
          },
          "emergency_contact_phone": {
            "type": [
              "string",
              "null"
            ],
            "description": "Emergency contact phone, where recorded."
          },
          "emergency_contact_relationship": {
            "type": [
              "string",
              "null"
            ],
            "description": "Emergency contact relationship, where recorded."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "archived"
            ],
            "description": "active or archived."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed."
          }
        },
        "required": [
          "id",
          "user_id",
          "external_id",
          "name",
          "job_title",
          "worker_type",
          "employer",
          "site_id",
          "phone",
          "email",
          "start_date",
          "end_date",
          "emergency_contact_name",
          "emergency_contact_phone",
          "emergency_contact_relationship",
          "status",
          "created_at",
          "updated_at"
        ]
      },
      "Actions": {
        "type": "object",
        "description": "The actions register: corrective and follow-up actions, who each one is assigned to, when it is due and whether it has been closed.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Action id."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "What needs to be done."
          },
          "status": {
            "type": "string",
            "description": "Status of the action: open, in_progress or closed. closed means it has been completed; the others are still outstanding."
          },
          "priority": {
            "type": [
              "string",
              "null"
            ],
            "description": "Priority, where set: low, medium, high or critical."
          },
          "due_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date the action is due (YYYY-MM-DD), where set."
          },
          "overdue": {
            "type": "boolean",
            "description": "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": {
            "type": [
              "string",
              "null"
            ],
            "description": "Name of the person the action is assigned to, where assigned."
          },
          "assigned_to_user_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "User id of the person the action is assigned to, where they have a login."
          },
          "closed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the action was closed, where it has been."
          },
          "closure_notes": {
            "type": [
              "string",
              "null"
            ],
            "description": "Notes recorded when the action was closed, where given."
          },
          "submission_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "The submission the action was raised from, where there is one; fetch one record with GET /v1/submissions/{id}."
          },
          "reference_number": {
            "type": [
              "string",
              "null"
            ],
            "description": "Reference number of that submission, for example INC-0003."
          },
          "form_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Name of the form that submission was made on."
          },
          "site_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Site that submission relates to, where recorded."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed."
          }
        },
        "required": [
          "id",
          "description",
          "status",
          "priority",
          "due_date",
          "overdue",
          "assigned_to_name",
          "assigned_to_user_id",
          "closed_at",
          "closure_notes",
          "submission_id",
          "reference_number",
          "form_name",
          "site_name",
          "created_at",
          "updated_at"
        ]
      },
      "Contractors": {
        "type": "object",
        "description": "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.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Contractor id."
          },
          "name": {
            "type": "string",
            "description": "Contractor name."
          },
          "trade": {
            "type": [
              "string",
              "null"
            ],
            "description": "Trade, where recorded."
          },
          "scope": {
            "type": [
              "string",
              "null"
            ],
            "description": "Scope of work, where recorded."
          },
          "status": {
            "type": "string",
            "enum": [
              "invited",
              "submitted",
              "approved",
              "approved_conditions",
              "declined"
            ],
            "description": "invited (pre-qualification not yet returned), submitted (returned and awaiting a decision), approved, approved_conditions (approved with conditions) or declined."
          },
          "approved_until": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date the approval runs to (YYYY-MM-DD), where set."
          },
          "approval_expired": {
            "type": "boolean",
            "description": "True when the contractor was approved and the approved-until date has passed. Worked out against the current date in New Zealand."
          },
          "conditions": {
            "type": [
              "string",
              "null"
            ],
            "description": "Conditions attached to the approval, where given."
          },
          "contact_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Name of the contact person at the contractor, where recorded."
          },
          "reviewed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the approval decision was made, where one has been."
          },
          "next_document_expiry": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Earliest expiry date among the current documents (YYYY-MM-DD), where any has one."
          },
          "expired_documents": {
            "type": "integer",
            "description": "How many current documents have passed their expiry date."
          },
          "expiring_documents": {
            "type": "integer",
            "description": "How many current documents expire within the next 30 days."
          },
          "documents": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Current documents held for the contractor, one line each: type | label | expiry date. The files themselves are not available here."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed."
          }
        },
        "required": [
          "id",
          "name",
          "trade",
          "scope",
          "status",
          "approved_until",
          "approval_expired",
          "conditions",
          "contact_name",
          "reviewed_at",
          "next_document_expiry",
          "expired_documents",
          "expiring_documents",
          "documents",
          "created_at",
          "updated_at"
        ]
      },
      "Pagination": {
        "type": "object",
        "required": [
          "limit",
          "offset",
          "returned",
          "has_more"
        ],
        "properties": {
          "limit": {
            "type": "integer",
            "description": "The limit that was applied."
          },
          "offset": {
            "type": "integer",
            "description": "The offset that was applied."
          },
          "returned": {
            "type": "integer",
            "description": "How many records are in this page."
          },
          "has_more": {
            "type": "boolean",
            "description": "True when there are more records after this page. Ask again with offset increased by limit."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "A short code, for example invalid_parameters or not_found."
          },
          "details": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Plain-language detail, where there is any."
          },
          "required": {
            "type": "string",
            "description": "On insufficient_scope: the scope the key would need."
          }
        }
      },
      "Answer": {
        "type": "object",
        "required": [
          "field_id",
          "label",
          "type",
          "value"
        ],
        "properties": {
          "field_id": {
            "type": "string",
            "description": "The id of the question on the form."
          },
          "label": {
            "type": "string",
            "description": "The question as shown in the app."
          },
          "type": {
            "type": "string",
            "description": "The kind of question, for example text, date, select or repeatable_group."
          },
          "value": {
            "description": "The answer. Choices are returned as their labels. A repeating section is returned as a list of rows, each with its own answers."
          }
        }
      },
      "SubmissionDetail": {
        "type": "object",
        "description": "One record with its answers.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Record id."
          },
          "site_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Site the record belongs to, where one was chosen."
          },
          "site_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Site name: the linked site's name when there is one, otherwise the location typed on the form."
          },
          "form_definition_id": {
            "type": "string",
            "format": "uuid",
            "description": "Which form this is. Look it up in /v1/form-definitions."
          },
          "submitted_by": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "User id of the person who submitted the record, where known."
          },
          "worker_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Related worker id, where set."
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "in_review",
              "resolved",
              "closed"
            ],
            "description": "Where the record is in its close-out."
          },
          "priority": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "maximum": 5,
            "description": "Priority from 1 to 5, where set."
          },
          "risk_level": {
            "type": [
              "string",
              "null"
            ],
            "description": "Risk level. Only hazard reports set this; it is null on every other form."
          },
          "reference_number": {
            "type": [
              "string",
              "null"
            ],
            "description": "Reference shown in the app, for example INC-0020. Can be null on older imported records."
          },
          "parent_submission_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Id of the record this one was raised from, where there is one."
          },
          "gps_latitude": {
            "type": [
              "string",
              "null"
            ],
            "description": "Latitude captured at submission, where available. Returned as a string."
          },
          "gps_longitude": {
            "type": [
              "string",
              "null"
            ],
            "description": "Longitude captured at submission, where available. Returned as a string."
          },
          "submitted_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the form was submitted."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record last changed. Lists are ordered by this, oldest first; use updated_since to fetch only what changed."
          },
          "form_slug": {
            "type": [
              "string",
              "null"
            ],
            "description": "Short name of the form."
          },
          "form_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Form name as shown in the app."
          },
          "answers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Answer"
            },
            "description": "The answers, in form order, labelled as your team sees them. Photos and signatures are not included."
          }
        },
        "required": [
          "id",
          "site_id",
          "site_name",
          "form_definition_id",
          "submitted_by",
          "worker_id",
          "status",
          "priority",
          "risk_level",
          "reference_number",
          "parent_submission_id",
          "gps_latitude",
          "gps_longitude",
          "submitted_at",
          "created_at",
          "updated_at",
          "form_slug",
          "form_name",
          "answers"
        ]
      },
      "FileLink": {
        "type": "object",
        "required": [
          "url",
          "expires_in",
          "filename",
          "content_type"
        ],
        "properties": {
          "url": {
            "type": "string",
            "description": "A link to the file. It stops working after expires_in seconds, so fetch it straight away."
          },
          "expires_in": {
            "type": "integer",
            "description": "Seconds until the link expires."
          },
          "filename": {
            "type": "string",
            "description": "File name."
          },
          "content_type": {
            "type": "string",
            "description": "File type, for example application/pdf."
          }
        }
      },
      "FileContent": {
        "type": "object",
        "required": [
          "filename",
          "content_type",
          "size_bytes",
          "content_base64"
        ],
        "properties": {
          "filename": {
            "type": "string",
            "description": "File name."
          },
          "content_type": {
            "type": "string",
            "description": "Always application/pdf."
          },
          "size_bytes": {
            "type": "integer",
            "description": "Size of the PDF in bytes, before base64 encoding."
          },
          "content_base64": {
            "type": "string",
            "description": "The PDF, base64 encoded."
          },
          "sssp_version": {
            "type": "integer",
            "description": "SSSP download only. Version number of the plan, as printed on its cover."
          },
          "sssp_updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "SSSP download only. When the plan last changed, published or not."
          }
        }
      },
      "SiteCreate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 255,
            "description": "Site name."
          },
          "address": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 500,
            "description": "Street address, where recorded. Send null or an empty string to leave it blank."
          },
          "job_number": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "description": "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."
          }
        },
        "additionalProperties": false,
        "required": [
          "name"
        ]
      },
      "SiteUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 255,
            "description": "Site name."
          },
          "address": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 500,
            "description": "Street address, where recorded. Send null or an empty string to leave it blank."
          },
          "job_number": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "description": "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."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "archived"
            ],
            "description": "Set to archived when the job is finished, or back to active to reopen it."
          }
        },
        "additionalProperties": false,
        "minProperties": 1
      },
      "PersonWrite": {
        "type": "object",
        "properties": {
          "external_id": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "description": "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."
          },
          "name": {
            "type": "string",
            "maxLength": 150,
            "description": "Full name."
          },
          "job_title": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "description": "Job title, where recorded. Send null or an empty string to clear it."
          },
          "worker_type": {
            "type": "string",
            "enum": [
              "employee",
              "casual",
              "contractor",
              "apprentice",
              "volunteer",
              "labour_hire",
              "other"
            ],
            "description": "Type of worker."
          },
          "employer": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 150,
            "description": "Employer, where recorded (for example a contractor or labour-hire company). Send null or an empty string to clear it."
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 50,
            "description": "Phone number, where recorded. Send null or an empty string to clear it."
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email",
            "maxLength": 255,
            "description": "Email address, where recorded. Send null or an empty string to clear it."
          },
          "start_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Start date (YYYY-MM-DD), where recorded. Send null or an empty string to clear it."
          },
          "end_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Last day worked (YYYY-MM-DD), where recorded. Send null or an empty string to clear it."
          },
          "emergency_contact_name": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 150,
            "description": "Emergency contact name, where recorded. Send null or an empty string to clear it."
          },
          "emergency_contact_phone": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 50,
            "description": "Emergency contact phone, where recorded. Send null or an empty string to clear it."
          },
          "emergency_contact_relationship": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 60,
            "description": "Emergency contact relationship, where recorded. Send null or an empty string to clear it."
          },
          "invite": {
            "type": "boolean",
            "description": "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": {
            "type": "string",
            "enum": [
              "worker",
              "supervisor"
            ],
            "default": "worker",
            "description": "Role for the login when invite is true."
          },
          "login_enabled": {
            "type": "boolean",
            "description": "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": {
            "type": "object",
            "properties": {
              "licence_type": {
                "type": "string",
                "maxLength": 100,
                "description": "Name of the licence, for example Full Drivers License."
              },
              "licence_number": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 100,
                "description": "Licence number."
              },
              "issue_date": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date",
                "description": "YYYY-MM-DD. Send null to clear it."
              },
              "expiry_date": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date",
                "description": "YYYY-MM-DD. Send null to clear it."
              }
            },
            "required": [
              "licence_type"
            ],
            "additionalProperties": false,
            "description": "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."
          }
        },
        "additionalProperties": false
      },
      "SiteWriteResult": {
        "type": "object",
        "required": [
          "action",
          "data"
        ],
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "created",
              "updated"
            ],
            "description": "What happened."
          },
          "data": {
            "$ref": "#/components/schemas/Site"
          }
        }
      },
      "PersonWriteResult": {
        "type": "object",
        "required": [
          "action",
          "data"
        ],
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "created",
              "updated"
            ],
            "description": "What happened."
          },
          "data": {
            "$ref": "#/components/schemas/Person"
          },
          "invite": {
            "type": "object",
            "description": "Present when invite was sent in the request.",
            "properties": {
              "sent": {
                "type": "boolean",
                "description": "True when an invitation email was sent."
              },
              "reenabled": {
                "type": "boolean",
                "description": "True when an existing switched-off login was switched back on."
              },
              "user_id": {
                "type": "string",
                "format": "uuid",
                "description": "The login that was created or switched back on."
              },
              "role": {
                "type": "string",
                "description": "Role of the login."
              },
              "reason": {
                "type": "string",
                "description": "When sent is false, why. For example already_has_login, seat_limit_reached, no_email, email_in_use or person_is_leaver."
              }
            },
            "additionalProperties": true
          },
          "login": {
            "type": "object",
            "description": "Present when the request changed the state of the person's login.",
            "properties": {
              "enabled": {
                "type": "boolean",
                "description": "Whether the login is now on."
              },
              "disabled": {
                "type": "boolean",
                "description": "True when the login was switched off because the person has left."
              },
              "changed": {
                "type": "boolean",
                "description": "Whether anything changed."
              },
              "user_id": {
                "type": "string",
                "format": "uuid",
                "description": "The login affected."
              },
              "reason": {
                "type": "string",
                "description": "When nothing changed, why. For example no_login or role_not_managed."
              }
            },
            "additionalProperties": true
          },
          "driver_licence": {
            "type": "object",
            "description": "Present when driver_licence was sent in the request.",
            "properties": {
              "saved": {
                "type": "boolean",
                "description": "True when the licence record was created or updated."
              },
              "action": {
                "type": "string",
                "description": "created or updated."
              },
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "The licence record (see /v1/licences)."
              },
              "licence_type": {
                "type": "string",
                "description": "Type now on the record."
              },
              "previous_type": {
                "type": "string",
                "description": "The earlier type, when a driver licence moved to a new stage."
              },
              "licence_number": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Licence number."
              },
              "issue_date": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Issue date."
              },
              "expiry_date": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Expiry date (YYYY-MM-DD)."
              },
              "status": {
                "type": "string",
                "description": "active, expiring_soon or expired."
              },
              "reason": {
                "type": "string",
                "description": "When saved is false, why. For example multiple_matching_records or person_is_leaver."
              }
            },
            "additionalProperties": true
          }
        }
      }
    }
  }
}