> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ctrl-hub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List a work order's history

> Lists the changes made to a work order and its operations, newest first. Filter on `resource.type` for one of the
two, with one `eq` or `in` term.

The operations are those the caller can view. A caller with an organisation-wide view grant on operations also
sees the events of ones since deleted.

Anyone who can view the record can read its history, including a contractor working a shared scheme. It needs no
audit role. A record the caller cannot view is refused, just as reading the record would be.

Each event says who made the change and when, and an update lists each changed field with its value before and
after. `include=user` includes the user who made each change. Records created before 9 Oct 2026, or synced from
v2, have no create event. The client IP, user agent and any impersonating staff member are left empty, because a
history needs no audit role.




## OpenAPI

````yaml /api-reference/openapi.yaml get /v3/work-orders/{work_order_id}/history
openapi: 3.1.0
info:
  contact:
    email: support@ctrl-hub.com
    name: Ctrl Hub
    url: https://www.ctrl-hub.com
  description: >
    Ctrl Hub is the all-in-one platform for high-risk industries like utilities,
    construction, infrastructure, and renewables. We help teams manage
    everything from risk assessments and HAVS exposure to vehicle and equipment
    checks, with a guaranteed minimum of 200% ROI.
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT
  summary: An API for managing your compliance and risk posture
  termsOfService: https://www.ctrl-hub.com/terms-conditions
  title: Ctrl Hub
  version: 1.0.0
servers:
  - description: Production
    url: https://api.ctrl-hub.com
  - description: Staging
    url: https://api.ctrl-hub.dev
  - description: Development
    url: https://api.ctrl-hub.run
security: []
tags:
  - description: |
      Actions are follow-ups assigned to users and teams, produced manually or
      by domain producers such as the data-capture workflow runner.
    name: Actions
  - description: |
      Audit events are the events that are logged by the system.
    name: Audit Events
  - description: |
      View the platform's health and availability.
    name: Status
  - description: >
      User-owned dashboards composed of cards on a fixed-slot bento layout.
      Cards come from a per-domain registry; the API stores their config as
      opaque JSON.
    name: Dashboards
  - description: >
      Copies of a mobile device's local database, sent by the operative on
      request so that people

      in their organisation can recover work that never reached the server. Kept
      for 30 days, and

      visible to people granted `device-backups:view` in the organisation each
      is filed against.
    name: Device Backups
  - description: >
      A record of documents the platform generated and handed over, retained as
      evidence of what

      was issued. `subject_type` says what kind of records an export covers, and
      it is what decides

      how the request is authorised: there is no export permission of its own,
      so if you can see the

      records you can export them.
    name: Exports
  - description: >
      Scheduled delivery of a saved query's results, as a CSV attachment or a
      summary email. Every run is retained with the file it sent, so what a
      recipient received stays retrievable. A report runs as the person who
      created it, under their own access.
    name: Reports
  - description: >
      Performance standards the platform defines, such as the gas Guaranteed
      Standards of Performance 3 and 13, and how an organisation's forms answer
      them. An organisation maps its form fields to a standard's inputs, and the
      mapping generates a saved query that reads the answers.
    name: Standards
  - description: |
      Manage appointments for work to be carried out with your customers
    name: Customer Appointments
  - description: |
      Manage interactions you have with your customers
    name: Customer Interactions
  - description: |
      Manage accounts for your customers
    name: Customer Accounts and Contacts
  - description: >
      Competency: the assessments, training items, inductions and registrations
      an

      organisation requires, and the specifications that combine them.
    name: Qualifications
  - description: |
      Workflows allow you to automate your processes.
    name: Workflows
  - description: |
      Manage documents
    name: Documents
  - description: |
      Manage documents
    name: Folders
  - description: |
      Manage documents
    name: Document Reviews
  - description: |
      Manage feature configurations for an organisation.
    name: Feature Configurations
  - description: |
      Equipment are the physical assets that an organisation manages.
    name: Equipment
  - description: >
      Exposure limits: an organisation's thresholds for each exposure type,
      stricter than the HSE

      values, and the limit in force for a person on a date.
    name: Exposure Limits
  - description: |
      The central cost register: time-versioned rate codes for material, labour,
      contractor and miscellaneous spend, used to cost work against the job
      hierarchy.
    name: Costs
  - description: >
      Locations are places an organisation manages, optionally classified by a
      location type.
    name: Locations
  - description: >
      Bulk loads of locations from an uploaded CSV. An import matches rows on
      the organisation's own

      `reference`, so re-importing a corrected file updates what is already
      there rather than

      doubling the population, and the import record is the audit trail for the
      whole load: the bulk

      write path deliberately emits no per-row events.
    name: Location Imports
  - description: |
      Manage your forms and their schemas
    name: Forms, Schemas and Categories
  - description: |
      Create and view form submissions
    name: Submissions
  - description: |
      View the roles available in the system.
    name: IAM Roles
  - description: >
      IAM role groups can be assigned to principals to manage authorisation
      centrally.
    name: IAM Role Groups
  - description: |
      Manage service accounts which can access the API programmatically.
    name: Service Accounts
  - description: |
      Manage bridges between organisations.
    name: Bridges
  - description: |
      Manage settings for an organisation.
    name: Settings
  - description: |
      Manage teams within an organisation.
    name: Teams
  - description: >
      Manage who manages whom within an organisation, and the manager roles that
      say what a manager may do for their people.
    name: Management
  - description: |
      Manage job roles within an organisation.
    name: Job Roles
  - description: |
      Manage users and accounts.
    name: Users
  - description: |
      Invite and manage invitations to organisations.
    name: Invitations
  - description: >
      IAM grants are the asignment of roles or permissions to principals to
      manage resource access.
    name: IAM Grants
  - description: |
      View the permissions available in the system.
    name: IAM Permissions
  - description: |
      SSO providers are the identity providers for an organisation.
    name: SSO Providers
  - description: |
      Whoami returns information about the currently authenticated principal.
    name: Whoami
  - description: |
      Your personal inbox. A notification is the thing you receive: an envelope
      that carries what happened to one or more channels. Email is one of those
      channels, the inbox is another, and this is where the ones delivered to
      your inbox are listed, read, saved and archived.
    name: Notifications
  - description: |
      Manage your images
    name: Images
  - description: >
      AI agent personas that synthesise data into role-specific intelligent
      briefings.
    name: Agents
  - description: |
      Briefings generated by AI agents, including reasoning traces.
    name: Agent Briefings
  - description: >
      Feedback a console user sends to Ctrl Hub from any page. Only Ctrl Hub
      staff read it, on the

      Management API.
    name: User Feedback
  - description: >
      Notices an organisation sends to its own people and its contractors'
      people, who

      acknowledge that they have read and understood them. Replaces v2's
      bulletins.
    name: Briefings
  - description: >
      Things an organisation has that expire or renew, such as insurance,
      accreditations, domains,

      certificates and contracts, in the organisation's own categories. Their
      recipients are told

      ahead of time, and evidence is attached to each period.
    name: Reminders
  - description: >
      What falls due in an organisation between two dates, drawn from reminders,
      documents,

      competency records and work permits.
    name: Calendar
  - description: >
      Organisations are the center point for most resources in the platform.
      Most other endpoints are subresources of an organisation.
    name: Organisations
  - description: |
      Permits managements, integrated with street manager.
    name: Permits
  - description: |
      Projects manage your work and governance.
    name: Projects
  - description: >
      Import templates allow users to save and reuse their CSV importer
      configuration as named templates.
    name: Import Templates
  - description: |
      Properties are the physical locations.
    name: Properties
  - description: |
      Search across schemes, work orders, and operations.
    name: Search
  - description: |
      Provides the API specification in JSON and YAML formats
    name: Specifications
  - description: |
      Streets are the physical roads.
    name: Streets
  - description: |
      Integration with street manager
    name: Street Manager
  - description: |
      Vehicles are the physical vehicles that an organisation manages.
    name: Vehicles
  - description: >
      Scheme contracts (also known as regions) group schemes allocated from the
      network to a contractor.
    name: Scheme Contracts
  - description: >
      Scheme shares allow you to share your schemes with other organisations
      across bridges.
    name: Scheme Shares
  - description: |
      Schemes are large programmes of work
    name: Schemes
  - description: >
      A Construction Phase Plan is the Principal Contractor's plan for managing
      health and safety

      on a scheme, under CDM 2015. Its risks are control measures written
      against the hazards on

      the scheme's Pre-Construction Information. Each section is owned by one
      duty-holder role.
    name: Construction Phase Plans
  - description: >
      A Pre-Construction Information pack is the Client's information about a
      scheme under CDM

      2015, with its site hazards. A scheme has at most one. Each section is
      owned by one

      duty-holder role, and only that role can write it.
    name: Pre-Construction Information
  - description: >
      Site attendances record who was on site and when, whether or not they hold
      an account.

      There is no daily register resource: a day's register and who is currently
      on site are

      both queries over the attendances themselves.
    name: Site Attendances
  - description: |
      Work orders the component parts of a scheme.
    name: Work Orders
  - description: |
      Operations are the work to be carried out within work orders.
    name: Operations
externalDocs:
  description: More documentation and resources
  url: https://docs.ctrl-hub.com
paths:
  /v3/work-orders/{work_order_id}/history:
    get:
      tags:
        - Audit Events
      summary: List a work order's history
      description: >
        Lists the changes made to a work order and its operations, newest first.
        Filter on `resource.type` for one of the

        two, with one `eq` or `in` term.


        The operations are those the caller can view. A caller with an
        organisation-wide view grant on operations also

        sees the events of ones since deleted.


        Anyone who can view the record can read its history, including a
        contractor working a shared scheme. It needs no

        audit role. A record the caller cannot view is refused, just as reading
        the record would be.


        Each event says who made the change and when, and an update lists each
        changed field with its value before and

        after. `include=user` includes the user who made each change. Records
        created before 9 Oct 2026, or synced from

        v2, have no create event. The client IP, user agent and any
        impersonating staff member are left empty, because a

        history needs no audit role.
      operationId: ListWorkOrderHistory
      parameters:
        - $ref: '#/components/parameters/work_order_id'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/history_filter'
        - $ref: '#/components/parameters/history_include'
      responses:
        '200':
          $ref: '#/components/responses/ListAuditEvents'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - Session: []
        - OAuth2: []
        - Cookie: []
components:
  parameters:
    work_order_id:
      name: work_order_id
      in: path
      required: true
      description: The unique identifier for the work order.
      schema:
        type: string
        format: uuid
      example: fb082ee5-b678-4451-b02b-8269aaf262a3
    limit:
      name: limit
      in: query
      description: Limit the number of resources returned by the API
      required: false
      schema:
        type: integer
        format: int64
        minimum: 1
        default: 100
    offset:
      name: offset
      in: query
      description: Offset the resources returned by the API
      required: false
      schema:
        type: integer
        format: int64
        minimum: 0
        default: 0
    page:
      name: page
      in: query
      description: >
        JSON:API pagination, as `page[limit]` and `page[offset]`. The same as
        the top-level `limit` and `offset` parameters; when both forms are sent,
        `page[...]` wins.
      required: false
      style: deepObject
      explode: true
      schema:
        type: object
        additionalProperties: false
        properties:
          limit:
            type: integer
            format: int64
            minimum: 1
            description: >-
              Limit the number of resources returned by the API. Defaults to the
              operation's `limit` default.
          offset:
            type: integer
            format: int64
            minimum: 0
            description: Offset the resources returned by the API. Defaults to 0.
    history_filter:
      name: filter
      in: query
      description: >
        Narrows a history to the events about one kind of record.


        Available filters:


        - `in(resource.type,[xxx])`: Only the events about records of these
        types: `schemes`, `work-orders` or
          `operations`. Without it, a scheme's history holds the events about the scheme, its work orders and its
          operations, and a work order's holds the events about the work order and its operations.

        For more information on using named filters, see [the
        docs](https://docs.ctrl-hub.com/api-reference/features#filtering)
      required: false
      schema:
        type: string
        default: ''
    history_include:
      name: include
      in: query
      description: >-
        A comma separated list of related resources to include. `user` includes
        the user who made each change.
      required: false
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
            - user
  responses:
    ListAuditEvents:
      description: List of audit events.
      headers:
        Content-Type:
          $ref: '#/components/headers/content-type'
        Content-Length:
          $ref: '#/components/headers/content-length'
        X-Request-ID:
          $ref: '#/components/headers/x-request-id'
      content:
        application/vnd.api+json:
          schema:
            allOf:
              - type: object
                required:
                  - data
                properties:
                  data:
                    title: A list of audit events
                    type: array
                    items:
                      $ref: '#/components/schemas/AuditEvent'
                  included:
                    $ref: '#/components/schemas/AuditEventIncludes'
              - $ref: '#/components/schemas/DocumentMeta'
              - $ref: '#/components/schemas/JSONAPI'
    BadRequest:
      description: >
        There was an error with the request - this could be due to an invalid
        body, query parameters,

        or headers that were sent to the API.
      headers:
        Content-Type:
          $ref: '#/components/headers/content-type'
        Content-Length:
          $ref: '#/components/headers/content-length'
        X-Request-ID:
          $ref: '#/components/headers/x-request-id'
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/Error'
          example:
            id: 98ca4a78-b66f-4234-9719-aaf832ee6669
            status: '400'
            title: A validation error was encountered
            source:
              parameter: include
            meta:
              resource: wrong_value
    Unauthorised:
      description: Authentication failed
      headers:
        Content-Type:
          $ref: '#/components/headers/content-type'
        Content-Length:
          $ref: '#/components/headers/content-length'
        X-Request-ID:
          $ref: '#/components/headers/x-request-id'
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/Error'
          example:
            id: 05fc9c8d-73b9-4697-9337-57f7a567a48f
            status: '401'
            title: You are not authorised to access this resource
            detail: In order to access this resource, you need the 'admin' role.
            code: AUTH.001
    NotFound:
      description: The requested resource could not be found
      headers:
        Content-Type:
          $ref: '#/components/headers/content-type'
        Content-Length:
          $ref: '#/components/headers/content-length'
        X-Request-ID:
          $ref: '#/components/headers/x-request-id'
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/Error'
          example:
            id: 7b4c8f12-3e9a-4d5b-8c6f-1a2b3c4d5e6f
            status: '404'
            title: Resource not found
            detail: The requested resource could not be found or does not exist.
            code: NOT_FOUND.001
    InternalServerError:
      description: There was a problem handling the request on the server side
      headers:
        Content-Type:
          $ref: '#/components/headers/content-type'
        Content-Length:
          $ref: '#/components/headers/content-length'
        X-Request-ID:
          $ref: '#/components/headers/x-request-id'
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/Error'
          example:
            id: fe9d9a69-f0a7-4fdc-bb2c-176027f316c5
            status: '500'
            title: Internal Server Error
            detail: An unexpected error occurred on the server.
  headers:
    content-type:
      description: The content type of the response
      schema:
        type: string
      example: application/vnd.api+json
    content-length:
      description: The length of the response body in bytes
      schema:
        type: integer
        format: int32
      example: 1234
    x-request-id:
      description: >-
        An ID that can be provided when reporting bugs to help identify the
        issue
      schema:
        type: string
      example: 8470f56af4cf25e22be08e72c70dbbdc
  schemas:
    AuditEvent:
      type: object
      description: An audit event
      required:
        - id
        - type
        - attributes
        - meta
        - relationships
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the audit event.
        type:
          type: string
          const: audit-events
        attributes:
          $ref: '#/components/schemas/AuditEventAttributes'
        meta:
          $ref: '#/components/schemas/AuditEventMeta'
        relationships:
          $ref: '#/components/schemas/AuditEventRelationships'
    AuditEventIncludes:
      type: array
      description: Related resources that can be included when an audit event is returned
      items:
        discriminator:
          propertyName: type
          mapping:
            organisations: '#/components/schemas/Organisation'
            users: '#/components/schemas/User'
        oneOf:
          - $ref: '#/components/schemas/Organisation'
          - $ref: '#/components/schemas/User'
    DocumentMeta:
      type: object
      description: Document level meta about the resources on the server in list endpoints.
      required:
        - meta
      properties:
        meta:
          type: object
          required:
            - pagination
          properties:
            features:
              $ref: '#/components/schemas/Features'
            pagination:
              $ref: '#/components/schemas/Pagination'
    JSONAPI:
      type: object
      description: JSON API response object
      required:
        - jsonapi
      properties:
        jsonapi:
          type: object
          required:
            - version
          properties:
            version:
              type: string
              description: The version of the JSON API specification
              examples:
                - '1.0'
    Error:
      type: object
      description: An error response
      properties:
        id:
          description: >-
            A unique identifier for this particular occurrence of the problem.
            If you encounter this, please provide us with the error ID and we
            can investigate it on our side.
          type: string
          format: uuid
          examples:
            - 05fc9c8d-73b9-4697-9337-57f7a567a48f
        status:
          description: >-
            The status code for the error. This might not match the HTTP status
            code if there are more that one errors to return with different
            status codes.
          type: string
          examples:
            - '401'
            - '500'
        title:
          description: A human readable title for the error.
          type: string
          examples:
            - You are not authorised to access this resource
        detail:
          description: >-
            Where there is more detail that we can provide outside of the title,
            we will provide it here.
          type: string
          examples:
            - In order to access this resource, you need the 'admin' role.
        code:
          description: >-
            A unique code for the error that may help us to diagnose the issue.
            Not all errors have codes, so this is usually empty.

            `CH.003.080` (403) means the organisation in `meta.organisation_id`
            requires two-factor authentication and the caller's session does not
            satisfy it. The caller must set up or use a second factor, or sign
            in through their organisation's SAML single sign-on. Other OIDC
            sign-ins do not count.
          type: string
          examples:
            - AUTH.001
            - CH.003.080
        source:
          description: A JSON object containing additional information about the error.
          type: object
          properties:
            pointer:
              description: >-
                A JSON Pointer to the value in the request that caused the
                error.
              type: string
              examples:
                - /data/attributes/email
            parameter:
              description: >-
                A string indicating which query parameter in the request caused
                the error.
              type: string
              examples:
                - include
        meta:
          description: >-
            A JSON object containing additional information about the error.

            When a parameter caused the error, there will be a `resource`
            property with the name of the resource that caused the error.

            When `code` is `CH.003.080`, `organisation_id` names the
            organisation that requires two-factor authentication, which the
            caller's session does not satisfy.

            When `code` is `CH.029.016`, `retry_after` is the number of seconds
            to wait before sending feedback again. It matches the `Retry-After`
            header, which a browser on another origin cannot read.
          type: object
          properties:
            resource:
              type: string
              description: >-
                The resource a parameter error relates to, such as an
                unsupported include.
            organisation_id:
              type: string
              format: uuid
              examples:
                - c000c344-8847-47da-a091-32e75902d3b1
            retry_after:
              type: integer
              minimum: 1
              description: Seconds to wait before trying the request again.
              examples:
                - 1200
          additionalProperties: true
      required:
        - id
        - status
        - title
    AuditEventAttributes:
      type: object
      description: Attributes of an audit event.
      required:
        - time
        - operation
        - resource
        - values
        - principal
        - request_id
        - context
      properties:
        time:
          type: string
          format: date-time
          description: The date and time when the audit event occurred
        operation:
          type: string
          enum:
            - create
            - update
            - delete
          description: The type of operation that was performed
        resource:
          type: object
          required:
            - type
            - id
            - name
          properties:
            type:
              type: string
              description: The jsonapi resource type
            id:
              type: string
              description: The resource id
            name:
              type: string
              description: Human readable resource name
          description: Information about the resource that was modified
        values:
          type: array
          items:
            type: object
            required:
              - field
              - before
              - after
              - data_type
            properties:
              field:
                type: string
                description: The resource field that was changed
              before:
                description: The resource before state (preserves type)
              after:
                description: The resource after state (preserves type)
              data_type:
                type: string
                enum:
                  - string
                  - number
                  - boolean
                  - object
                  - array
                  - 'null'
                description: The original data type
          description: Array of field changes that occurred during the operation
        principal:
          type: object
          required:
            - type
            - id
          properties:
            type:
              type: string
              enum:
                - users
                - service-accounts
                - jobs
                - subscribers
              description: The type of principal
            id:
              type: string
              format: uuid
              description: The principal id
          description: Information about who performed the operation
        request_id:
          type: string
          format: uuid
          description: The unique identifier of the request that triggered this audit event
        context:
          type: object
          required:
            - client_ip
            - user_agent
          properties:
            client_ip:
              type: string
              description: The client IP address
            user_agent:
              type: string
              description: The client user agent
            related:
              type: array
              description: >-
                The other resources the change belongs to, such as a payment
                record's standard mapping and submission. Absent when there are
                none.
              items:
                type: object
                required:
                  - type
                  - id
                properties:
                  type:
                    type: string
                    description: The jsonapi resource type
                  id:
                    type: string
                    description: The resource id
                  name:
                    type: string
                    description: Human readable resource name
            impersonated_by:
              type: object
              description: >-
                The Ctrl Hub staff member who made the change while
                impersonating the principal, with the impersonation session.
                Absent for a change the principal made themselves.
              required:
                - user_id
                - name
                - impersonation_id
              properties:
                user_id:
                  type: string
                  format: uuid
                  description: The staff member's user id.
                name:
                  type: string
                  description: >-
                    The staff member's name, or their email when they have none,
                    as it was when the session started.
                impersonation_id:
                  type: string
                  format: uuid
                  description: The impersonation session the change was made in.
          description: Additional context about the request
        reason:
          type: string
          description: >-
            Why the change was made. Present only on a change that requires a
            reason.
    AuditEventMeta:
      type: object
      description: Metadata for an audit event
      required:
        - created_at
      properties:
        created_at:
          type: string
          format: date-time
          description: The date and time when the audit event was created
    AuditEventRelationships:
      type: object
      description: Relationships for an audit event
      required:
        - organisation
      properties:
        organisation:
          type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/OrganisationRelationship'
        user:
          type: object
          description: >-
            The user who made the change. Absent when the change was made by a
            service account, a job or a subscriber.
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/UserRelationship'
    Organisation:
      type: object
      description: An organisation
      required:
        - id
        - type
        - attributes
        - meta
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the organisation.
        type:
          type: string
          const: organisations
        attributes:
          $ref: '#/components/schemas/OrganisationAttributes'
        meta:
          $ref: '#/components/schemas/OrganisationMeta'
        relationships:
          $ref: '#/components/schemas/OrganisationRelationships'
    User:
      type: object
      description: A user
      required:
        - id
        - type
        - attributes
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the user.
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
        type:
          type: string
          const: users
        attributes:
          $ref: '#/components/schemas/UserAttributes'
        meta:
          $ref: '#/components/schemas/UserMeta'
        relationships:
          $ref: '#/components/schemas/UserRelationships'
    Features:
      type: object
      description: Represents feature configurations of the API
      properties:
        include:
          type: object
          properties:
            options:
              type: array
              items:
                type: string
                examples:
                  - related.resource
    Pagination:
      type: object
      description: Represents pagination details for API responses
      required:
        - counts
        - current_page
        - offsets
        - requested
      properties:
        counts:
          type: object
          required:
            - pages
            - resources
          properties:
            pages:
              type: integer
              examples:
                - 1
            resources:
              type: integer
              examples:
                - 1
        current_page:
          type: integer
          examples:
            - 1
        offsets:
          type: object
          required:
            - next
            - previous
          properties:
            next:
              type:
                - integer
                - 'null'
              examples:
                - null
            previous:
              type:
                - integer
                - 'null'
              examples:
                - null
        requested:
          type: object
          required:
            - limit
            - offset
          properties:
            limit:
              type: integer
              examples:
                - 10
            offset:
              type: integer
              examples:
                - 0
    OrganisationRelationship:
      type: object
      description: Represents a relationship to an organisation
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the organisation
        type:
          type: string
          const: organisations
    UserRelationship:
      type: object
      description: Represents a relationship to a user
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the user
        type:
          type: string
          const: users
    OrganisationAttributes:
      type: object
      description: Attributes for an organisation
      required:
        - name
        - slug
        - sandbox
      properties:
        name:
          type: string
          description: The name of the organisation.
          examples:
            - Acme Construction Ltd
        slug:
          type: string
          description: The URL-friendly identifier for the organisation.
          examples:
            - acme-construction
        description:
          type: string
          description: A short description of the organisation.
          examples:
            - >-
              Leading construction company specializing in infrastructure
              projects
        sandbox:
          type: boolean
          description: Whether the organisation is a sandbox (i.e. a test organisation)
          examples:
            - false
        settings:
          type: object
          required:
            - documents
          properties:
            teams:
              type: object
              description: Team-related settings for the organisation.
              properties:
                customer_representatives:
                  type: array
                  description: >
                    IDs of teams within this organisation whose members act as

                    customer service representatives. Each entry must reference
                    a

                    team that belongs to this organisation.
                  items:
                    type: string
                    format: uuid
                  uniqueItems: true
                  examples:
                    - - b234c567-8901-2345-6789-abcdef012345
            security:
              type: object
              description: Security settings for the organisation.
              properties:
                require_mfa:
                  type: boolean
                  description: >
                    Whether people must use a second factor to see this
                    organisation's data:

                    its members, and anyone working in it through a grant
                    without being a

                    member, such as a contractor. A SAML single sign-on sign-in
                    counts as

                    one; other OIDC sign-ins do not. Service accounts are
                    exempt.
                  examples:
                    - false
            documents:
              type: object
              description: Document settings for the organisation.
              required:
                - expiry_threshold_days
                - expiry_recipient_teams
              properties:
                expiry_threshold_days:
                  type: array
                  description: >
                    Lead times, in whole days before a document expires, at
                    which

                    its expiry is notified, in ascending order. Empty when none

                    are set.
                  items:
                    type: integer
                    minimum: 1
                    maximum: 365
                  uniqueItems: true
                  examples:
                    - - 7
                      - 30
                expiry_recipient_teams:
                  type: array
                  description: |
                    IDs of teams within this organisation whose members are
                    notified before a document expires. Empty when none are set,
                    and then nobody is notified.
                  items:
                    type: string
                    format: uuid
                  uniqueItems: true
                  examples:
                    - - b234c567-8901-2345-6789-abcdef012345
    OrganisationMeta:
      type: object
      description: Meta information for an organisation
      required:
        - v3
        - status
      properties:
        created_at:
          type: string
          format: date-time
          description: The creation time of the organisation.
          examples:
            - '2023-01-15T10:30:00.000Z'
        updated_at:
          type: string
          format: date-time
          description: The last update time of the organisation.
          examples:
            - '2023-02-20T14:45:00.000Z'
        v3:
          type: boolean
          description: Whether the organisation is using version 3 exclusively.
          examples:
            - true
        status:
          type: string
          enum:
            - active
            - inactive
          default: active
          description: The current status of the organisation.
          examples:
            - active
        features:
          type: array
          description: Available features and their limits for the organisation.
          items:
            type: object
            properties:
              name:
                type: string
                description: The name of the feature.
                examples:
                  - advanced_reporting
              enabled:
                type: boolean
                description: Whether the feature is enabled.
                examples:
                  - true
              limit:
                type: integer
                description: The usage limit for this feature (if applicable).
                examples:
                  - 1000
    OrganisationRelationships:
      type: object
      description: Relationships for an organisation
      properties:
        users:
          type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/UserRelationship'
        service_accounts:
          type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/ServiceAccountRelationship'
        groups:
          type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/UserGroupRelationship'
        teams:
          type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/TeamRelationship'
        nomenclature:
          type: object
          required:
            - data
          properties:
            data:
              oneOf:
                - $ref: '#/components/schemas/NomenclatureRelationship'
                - type: 'null'
    UserAttributes:
      type: object
      description: Attributes for a user
      required:
        - email
        - profile
      properties:
        email:
          type: string
          format: email
          description: The email address of the user.
          examples:
            - john.doe@example.com
        status:
          type: string
          enum:
            - active
            - inactive
            - pending
            - unknown
          description: >
            The membership status of this user in the organisation in the
            request URL.

            Only populated on org-scoped member endpoints; absent on global user

            endpoints.
          examples:
            - active
        seat_class:
          type: string
          enum:
            - full
            - field
            - record
          description: >
            The user's seat class in the organisation in the request URL. Only

            populated on org-scoped member endpoints, like `status`;
            `memberships`

            carries it everywhere.


            - `full`: a member who signs in and manages the organisation.

            - `field`: a member who signs in to capture data, usually on mobile.
              Nothing stops a field member using the console.
            - `record`: a member with no login who is never emailed. A record
            member
              can be the subject of competency records and organisation-level job
              roles, and cannot be assigned work.

            A membership stored before seat classes existed is `full`.
          examples:
            - full
        memberships:
          type: array
          description: |
            The user's membership of each organisation they belong to. A removed
            membership is left out.
          items:
            type: object
            required:
              - organisation
              - status
              - seat_class
            properties:
              organisation:
                type: string
                format: uuid
                description: The organisation's id.
                examples:
                  - 2f1e5a4c-8b7d-4c3e-9a1f-6d5b4c3a2e10
              status:
                type: string
                enum:
                  - active
                  - inactive
                  - pending
                  - unknown
                description: The membership status in that organisation.
                examples:
                  - active
              seat_class:
                type: string
                enum:
                  - full
                  - field
                  - record
                description: >-
                  The seat class in that organisation, as `seat_class`
                  describes.
                examples:
                  - record
              external_reference:
                type: string
                description: >
                  The organisation's own reference for the member, such as a
                  staff

                  number. Absent when it has none.
                examples:
                  - GR-0042
        password_set_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >
            When the user last set a password. Null if they never have, or if it
            is

            unknown because the user was created before this was tracked. Set by
            the

            server; it cannot be written through the API.
          examples:
            - '2026-09-25T10:15:00.000Z'
        last_login_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >
            When the user last signed in. Null if they have not signed in since
            this

            was recorded. Set by the server; it cannot be written through the
            API.
          examples:
            - '2026-11-14T08:30:00.000Z'
        mfa_enabled_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >
            When the user set up two-factor authentication with an authenticator
            app

            (TOTP). Null when they have none, including after they turn it off.

            Recovery codes on their own do not count. Set by the server from the

            identity provider; it cannot be written through the API.
          examples:
            - '2026-10-06T09:30:00.000Z'
        identities:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                description: The unique identifier for the identity.
                examples:
                  - 39ce13b8-1116-416a-ad5f-3c5edfd44f53
              platform:
                type: string
                description: The platform of the identity.
                examples:
                  - multi_tenant
              meta:
                type:
                  - object
                  - 'null'
                additionalProperties: true
                description: Additional metadata for the identity.
        profile:
          type: object
          required:
            - work
            - personal
            - contact
            - address
            - settings
          properties:
            work:
              type: object
              required:
                - occupation
                - cscs
                - eusr
                - start_date
              properties:
                occupation:
                  type: string
                  description: The occupation of the user.
                  examples:
                    - Site Manager
                cscs:
                  type: string
                  description: The CSCS card number of the user.
                  examples:
                    - CSC123456
                eusr:
                  type: string
                  description: The EUSR card number of the user.
                  examples:
                    - EUR789123
                start_date:
                  type: string
                  format: date
                  description: The start date of the user's employment.
                  examples:
                    - '2020-03-01T00:00:00.000Z'
            personal:
              type: object
              required:
                - first_name
                - last_name
                - dob
                - username
              properties:
                first_name:
                  type: string
                  description: The first name of the user.
                  examples:
                    - John
                last_name:
                  type: string
                  description: The last name of the user.
                  examples:
                    - Doe
                dob:
                  type: string
                  format: date
                  description: The date of birth of the user.
                  examples:
                    - '1985-06-15T00:00:00.000Z'
                username:
                  type: string
                  description: The username of the user.
                  examples:
                    - johndoe
            contact:
              type: object
              required:
                - mobile
                - landline
              properties:
                mobile:
                  type: string
                  description: The mobile number of the user.
                  examples:
                    - +44 7700 900123
                landline:
                  type: string
                  description: The landline of the user.
                  examples:
                    - +44 20 7946 0958
            address:
              type: object
              required:
                - name
                - number
                - street
                - area
                - town
                - county
                - postcode
                - country_code
                - what3words
              properties:
                name:
                  type: string
                  description: Building or location name
                  examples:
                    - Tech Tower
                number:
                  type: string
                  description: The house number of the user's address.
                  default: ''
                  examples:
                    - '42'
                street:
                  type: string
                  description: The street of the user's address.
                  examples:
                    - High Street
                area:
                  type: string
                  description: The area of the user's address.
                  examples:
                    - Westminster
                town:
                  type: string
                  description: The town of the user's address.
                  examples:
                    - London
                county:
                  type: string
                  description: The county of the user's address.
                  examples:
                    - Greater London
                postcode:
                  type: string
                  description: The postcode of the user's address.
                  examples:
                    - SW1A 1AA
                country_code:
                  type: string
                  description: The country code of the user's address.
                  examples:
                    - GB
                what3words:
                  type: string
                  description: The what3words location of the user's address.
                  examples:
                    - filled.count.soap
            settings:
              type: object
              required:
                - preferred_language
                - timezone
              properties:
                preferred_language:
                  type: string
                  description: The preferred language of the user.
                  default: en-GB
                  examples:
                    - en-GB
                timezone:
                  type: string
                  description: The timezone of the user.
                  examples:
                    - Europe/London
    UserMeta:
      type: object
      description: Metadata for a user
      properties:
        managed_type:
          type: string
          enum:
            - none
            - scim
            - organisation
            - unknown
          description: How this user is managed.
        withheld_organisations:
          type: array
          description: >
            Returned on `/v3/whoami` only. The organisations whose access is
            withheld

            from this session, because each requires two-factor authentication
            and the

            session does not satisfy it. This includes organisations the caller
            works in

            through a grant without being a member, such as a contractor in the
            owner's

            organisation. Absent when there are none. Requests to those
            organisations'

            routes answer 403 with code `CH.003.080`.
          items:
            type: string
            format: uuid
          examples:
            - - c000c344-8847-47da-a091-32e75902d3b1
        reach:
          type: string
          enum:
            - direct
            - chain
            - secondary
          description: >
            Returned on My people only. How the caller manages this person:
            `direct` when the caller

            is their primary manager, `chain` when the caller is a primary
            manager higher up their

            primary chain, and `secondary` when the caller is one of their
            secondary managers.
    UserRelationships:
      type: object
      description: Relationships for a user
      properties:
        organisations:
          type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/OrganisationRelationship'
        teams:
          type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/TeamRelationship'
        managing_organisation:
          type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/OrganisationRelationship'
    ServiceAccountRelationship:
      type: object
      description: Represents a relationship to a service account
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the service account
        type:
          type: string
          const: service-accounts
    UserGroupRelationship:
      type: object
      description: Represents a relationship to a group
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the group
        type:
          type: string
          const: groups
    TeamRelationship:
      type: object
      description: Represents a relationship to a team
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the team
        type:
          type: string
          const: teams
    NomenclatureRelationship:
      type: object
      description: Represents a relationship to a nomenclature resource
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the nomenclature resource
        type:
          type: string
          const: nomenclature
  securitySchemes:
    Session:
      description: |
        Session token for authentication.
      in: header
      name: X-Session-Token
      type: apiKey
    OAuth2:
      description: |
        OAuth2 token for authentication.
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://auth.ctrl-hub.com/oauth2/token
      type: oauth2
    Cookie:
      description: |
        Cookie token for authentication.
      in: cookie
      name: ctrl_hub_session
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.