> ## 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. # Allocate an operation > Allocate an unallocated operation to a work order. An operation can be allocated once: this is how an operation logged against a property, with no work order or scheme, is brought into the planned work. The operation takes the work order's scheme, and the work order and scheme totals are rebuilt to include it. The work order must be in the operation's organisation. The request is refused with 409 Conflict if the operation already has a work order, or if the work order already holds a permit for the same Street Manager works as the operation. An operation is never moved between work orders, and never has a permit dropped to make it fit. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v3/operations/{operation_id}/allocate 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: | 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: | 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: Briefings - 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/operations/{operation_id}/allocate: post: tags: - Operations summary: Allocate an operation to a work order description: > Allocate an unallocated operation to a work order. An operation can be allocated once: this is how an operation logged against a property, with no work order or scheme, is brought into the planned work. The operation takes the work order's scheme, and the work order and scheme totals are rebuilt to include it. The work order must be in the operation's organisation. The request is refused with 409 Conflict if the operation already has a work order, or if the work order already holds a permit for the same Street Manager works as the operation. An operation is never moved between work orders, and never has a permit dropped to make it fit. operationId: AllocateOperation parameters: - $ref: '#/components/parameters/operation_id' requestBody: $ref: '#/components/requestBodies/AllocateOperation' responses: '200': $ref: '#/components/responses/GetOperation' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorised' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalServerError' security: - Session: [] - OAuth2: [] - Cookie: [] components: parameters: operation_id: name: operation_id in: path required: true description: The unique identifier for the operation. schema: type: string format: uuid example: a8a41819-be0c-48b9-9883-1378fc63a637 requestBodies: AllocateOperation: required: true description: > The work order to allocate an unallocated operation to. The request type is `operation-allocations`, but there is no such resource: nothing of that name is stored and nothing can be fetched back by that id. It names the action, and the response is the operation it allocated. content: application/vnd.api+json: schema: type: object required: - data properties: data: type: object required: - type - relationships properties: type: type: string const: operation-allocations relationships: type: object required: - work_order properties: work_order: type: object required: - data properties: data: $ref: '#/components/schemas/WorkOrderRelationship' responses: GetOperation: description: An individual operation. 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: $ref: '#/components/schemas/Operation' included: $ref: '#/components/schemas/OperationIncludes' - $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 Conflict: description: The request conflicts with the current state of the resource 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: 8e2f9a34-b5c6-4d7e-9f8a-2b3c4d5e6f7g status: '409' title: Conflict detail: The request conflicts with the current state of the resource. code: CONFLICT.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. schemas: WorkOrderRelationship: type: object description: Represents a relationship to a work order required: - id - type properties: id: type: string format: uuid description: The unique identifier of the work order type: type: string const: work-orders Operation: type: object description: An operation required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the operation. type: type: string const: operations attributes: $ref: '#/components/schemas/OperationAttributes' meta: $ref: '#/components/schemas/OperationMeta' relationships: $ref: '#/components/schemas/OperationRelationships' OperationIncludes: type: array description: Related resources that can be included when an operation is returned items: discriminator: propertyName: type mapping: forms: '#/components/schemas/Form' operation-templates: '#/components/schemas/OperationTemplate' operation-types: '#/components/schemas/OperationType' organisations: '#/components/schemas/Organisation' locations: '#/components/schemas/Location' properties: '#/components/schemas/Property' schemes: '#/components/schemas/Scheme' streets: '#/components/schemas/Street' street-manager-permits: '#/components/schemas/StreetManagerPermit' teams: '#/components/schemas/Team' users: '#/components/schemas/User' work-orders: '#/components/schemas/WorkOrder' oneOf: - $ref: '#/components/schemas/Form' - $ref: '#/components/schemas/OperationTemplate' - $ref: '#/components/schemas/OperationType' - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/Location' - $ref: '#/components/schemas/Property' - $ref: '#/components/schemas/Scheme' - $ref: '#/components/schemas/Street' - $ref: '#/components/schemas/StreetManagerPermit' - $ref: '#/components/schemas/Team' - $ref: '#/components/schemas/User' - $ref: '#/components/schemas/WorkOrder' 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. 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 additionalProperties: true required: - id - status - title OperationAttributes: type: object description: Attributes for an operation required: - name - status properties: name: type: string code: type: string description: type: string requires_meter_details: type: boolean default: false description: >- When true, the operation's associated properties are expected to have meter details. Defaults from the operation template on create; the console uses it to warn about properties missing meters. dates: type: object properties: scheduled: type: object properties: start: type: string format: date-time end: type: string format: date-time labels: type: array items: $ref: '#/components/schemas/Label' requirements: oneOf: - type: object properties: forms: oneOf: - type: array items: type: object required: - id - required properties: id: type: string format: uuid required: type: boolean - type: 'null' - type: 'null' status: type: string enum: - done - in_progress - todo done_reason: type: - string - 'null' enum: - aborted - completed - cancelled - null allOf: - if: properties: status: const: done then: required: - done_reason OperationMeta: type: object description: Metadata for an operation required: - created_at - updated_at - counts properties: created_at: type: string format: date-time description: The date and time when the operation was created updated_at: type: string format: date-time description: The date and time when the operation was last updated counts: type: object required: - streets - properties - locations properties: streets: type: integer description: The number of streets in this operation format: int64 minimum: 0 default: 0 properties: type: integer description: The number of properties in this operation format: int64 minimum: 0 default: 0 locations: type: integer description: The number of organisation-managed locations in this operation format: int64 minimum: 0 default: 0 related_data: type: object description: Related resources for the operation properties: properties: type: array description: Array of property IDs with postcodes items: type: object description: Property ID and Postcode required: - id - postcode properties: id: type: string format: uuid description: The ID of the property postcode: type: string description: Postcode of the property OperationRelationships: type: object description: Relationships for an operation required: - work_order - scheme - organisation properties: organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' appointment: type: object required: - data properties: data: $ref: '#/components/schemas/AppointmentRelationship' scheme: type: object description: >- Null while the operation is unallocated (it has no scheme or work order yet). required: - data properties: data: oneOf: - $ref: '#/components/schemas/SchemeRelationship' - type: 'null' work_order: type: object description: >- Null while the operation is unallocated (it has no scheme or work order yet). required: - data properties: data: oneOf: - $ref: '#/components/schemas/WorkOrderRelationship' - type: 'null' permits: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/PermitRelationship' template: type: object required: - data properties: data: $ref: '#/components/schemas/OperationTemplateRelationship' type: type: object properties: data: $ref: '#/components/schemas/OperationTypeRelationship' teams: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/TeamRelationship' assignees: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/UserRelationship' properties: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/PropertyRelationship' locations: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/LocationRelationship' streets: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/StreetRelationship' created_by_user: type: object description: > The user who created this operation. Absent when it was created by a service account or by a v2 subscriber, and on every operation created before the creator was recorded. Set by the server. required: - data properties: data: $ref: '#/components/schemas/UserRelationship' created_by_service_account: type: object description: > The service account that created this operation. Absent when it was created by a user or by a v2 subscriber, and on every operation created before the creator was recorded. Set by the server. required: - data properties: data: $ref: '#/components/schemas/ServiceAccountRelationship' Form: type: object description: A form required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the form. type: type: string const: forms attributes: $ref: '#/components/schemas/FormAttributes' meta: $ref: '#/components/schemas/FormMeta' relationships: $ref: '#/components/schemas/FormRelationships' OperationTemplate: type: object description: An operation template required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the operation template. type: type: string const: operation-templates attributes: $ref: '#/components/schemas/OperationTemplateAttributes' meta: $ref: '#/components/schemas/OperationTemplateMeta' relationships: $ref: '#/components/schemas/OperationTemplateRelationships' OperationType: type: object description: An operation type required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the operation type. type: type: string const: operation-types attributes: $ref: '#/components/schemas/OperationTypeAttributes' meta: $ref: '#/components/schemas/OperationTypeMeta' relationships: $ref: '#/components/schemas/OperationTypeRelationships' 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' Location: type: object description: A location required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the location. type: type: string const: locations attributes: $ref: '#/components/schemas/LocationAttributes' meta: $ref: '#/components/schemas/LocationMeta' relationships: $ref: '#/components/schemas/LocationRelationships' Property: type: object description: A property required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the property. type: type: string const: properties attributes: $ref: '#/components/schemas/PropertyAttributes' meta: $ref: '#/components/schemas/PropertyMeta' relationships: $ref: '#/components/schemas/PropertyRelationships' Scheme: type: object description: A scheme required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the scheme. type: type: string const: schemes attributes: $ref: '#/components/schemas/SchemeAttributes' meta: $ref: '#/components/schemas/SchemeMeta' relationships: $ref: '#/components/schemas/SchemeRelationships' Street: type: object description: A street required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the street. type: type: string const: streets attributes: $ref: '#/components/schemas/StreetAttributes' meta: $ref: '#/components/schemas/StreetMeta' relationships: $ref: '#/components/schemas/StreetRelationships' StreetManagerPermit: type: object description: A street manager permit required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the street manager permit. type: type: string const: street-manager-permits attributes: $ref: '#/components/schemas/StreetManagerPermitAttributes' meta: $ref: '#/components/schemas/StreetManagerPermitMeta' relationships: $ref: '#/components/schemas/StreetManagerPermitRelationships' Team: type: object description: A team required: - id - type - attributes properties: id: type: string format: uuid description: The unique identifier of the team. type: type: string const: teams attributes: $ref: '#/components/schemas/TeamAttributes' meta: $ref: '#/components/schemas/TeamMeta' relationships: $ref: '#/components/schemas/TeamRelationships' 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' WorkOrder: type: object description: A work order required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the work order. examples: - fb082ee5-b678-4451-b02b-8269aaf262a3 type: type: string const: work-orders attributes: $ref: '#/components/schemas/WorkOrderAttributes' meta: $ref: '#/components/schemas/WorkOrderMeta' relationships: $ref: '#/components/schemas/WorkOrderRelationships' Label: type: object description: A label object required: - key - value properties: key: type: string minLength: 1 examples: - Your label key value: type: string examples: - Your label value 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 AppointmentRelationship: type: object description: Represents a relationship to an appointment required: - id - type properties: id: type: string format: uuid description: The unique identifier of the appointment type: type: string const: appointments SchemeRelationship: type: object description: Represents a relationship to a scheme required: - id - type properties: id: type: string format: uuid description: The unique identifier of the scheme type: type: string const: schemes PermitRelationship: type: object description: Represents a relationship to a permit required: - id - type properties: id: type: string format: uuid description: The unique identifier of the permit type: type: string const: permits OperationTemplateRelationship: type: object description: Represents a relationship to an operation template required: - id - type properties: id: type: string format: uuid description: The unique identifier of the operation template type: type: string const: operation-templates OperationTypeRelationship: type: object description: Represents a relationship to an operation type required: - id - type properties: id: type: string format: uuid description: The unique identifier of the operation type type: type: string const: operation-types 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 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 PropertyRelationship: type: object description: Represents a relationship to a property required: - id - type properties: id: type: string format: uuid description: The unique identifier of the property type: type: string const: properties LocationRelationship: type: object description: Represents a relationship to a location required: - id - type properties: id: type: string format: uuid description: The unique identifier of the location type: type: string const: locations StreetRelationship: type: object description: Represents a relationship to a street required: - id - type properties: id: type: string format: uuid description: The unique identifier of the street type: type: string const: streets 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 FormAttributes: type: object description: Attributes for a form required: - name - description - status properties: name: type: string description: The name of the form description: type: string description: The description of the form status: type: string enum: - draft - active - archived default: draft description: The current status of the form FormMeta: type: object description: Metadata for a form required: - created_at - updated_at - modified_at - counts properties: created_at: type: string format: date-time description: The date and time when the form was created updated_at: type: string format: date-time description: The date and time when the form was last updated modified_at: type: string format: date-time description: The date and time when the form was last modified counts: type: object properties: schemas: type: integer description: The number of schemas this form has. format: int64 minimum: 0 default: 0 categories: type: integer description: The number of categories this form has. format: int64 minimum: 0 default: 0 submissions: type: integer description: The number of submissions this form has. format: int64 minimum: 0 default: 0 submission_versions: type: integer description: The number of submission versions this form has. format: int64 minimum: 0 default: 0 FormRelationships: type: object description: Relationships for a form required: - organisation - categories - schemas properties: author: type: object required: - data properties: data: $ref: '#/components/schemas/UserRelationship' organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' categories: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/FormCategoryRelationship' workflow: type: object required: - data properties: data: oneOf: - $ref: '#/components/schemas/WorkflowDefinitionRelationship' - type: 'null' latest_schema: type: object required: - data properties: data: $ref: '#/components/schemas/FormSchemaRelationship' schemas: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/FormSchemaRelationship' submissions: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/FormSubmissionRelationship' OperationTemplateAttributes: type: object description: Attributes for an operation template required: - name properties: name: type: string description: The name of the operation template operation_name_template: type: string description: The template for the operation name operation_code_template: type: string description: The template for the operation code requires_meter_details: type: boolean default: false description: >- The default "requires meter details" flag applied to operations created from this template. Operations may override it on create. labels: type: array description: The labels associated with the operation template items: $ref: '#/components/schemas/Label' requirements: type: object description: The requirements for the operation template properties: forms: type: array description: The forms required for this operation template items: type: object required: - id - required properties: id: type: string format: uuid description: The ID of the required form required: type: boolean description: Whether this form is required OperationTemplateMeta: type: object description: Metadata for an operation template required: - created_at - updated_at properties: created_at: type: string format: date-time description: The date and time when the operation template was created updated_at: type: string format: date-time description: The date and time when the operation template was last updated OperationTemplateRelationships: type: object description: Relationships for an operation template properties: organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' scheme_template: type: object required: - data properties: data: $ref: '#/components/schemas/SchemeTemplateRelationship' OperationTypeAttributes: type: object description: Attributes for an operation type required: - name properties: name: type: string description: The name of the operation type description: type: string description: An optional description of the operation type colour_palette: $ref: '#/components/schemas/OperationTypeColourPalette' colour_shade: $ref: '#/components/schemas/OperationTypeColourShade' OperationTypeMeta: type: object description: Metadata for an operation type required: - created_at - updated_at properties: created_at: type: string format: date-time description: The date and time when the operation type was created updated_at: type: string format: date-time description: The date and time when the operation type was last updated OperationTypeRelationships: type: object description: Relationships for an operation type properties: organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' template: type: object properties: data: $ref: '#/components/schemas/OperationTemplateRelationship' 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 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 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' LocationAttributes: type: object description: Attributes for a location properties: reference: type: string description: > The organisation's own lookup key for the place, such as a pole number or an internal property reference. Unique within the organisation, and what identifies a location: it is the key a bulk import matches rows on. Required on create. Absent only on locations that predate the field, which is why it is not marked required here - the resource has to describe those as well as the ones written since. name: type: string description: > What the place is called, where it is called anything. Optional: a place identified by its reference does not need a name invented for it. description: type: string description: A description of the location location: $ref: '#/components/schemas/GeoPoint' address: $ref: '#/components/schemas/PostalAddress' LocationMeta: type: object description: Metadata for a location required: - created_at - updated_at properties: created_at: type: string format: date-time description: The date and time when the location was created updated_at: type: string format: date-time description: The date and time when the location was last updated LocationRelationships: type: object description: Relationships for a location required: - organisation properties: organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' location_type: type: object description: The location type assigned to this location, if any. properties: data: oneOf: - $ref: '#/components/schemas/LocationTypeRelationship' - type: 'null' PropertyAttributes: type: object description: Attributes for a property required: - address properties: address: type: object properties: description: type: string department: type: string organisation: type: string number: type: string name: type: string thoroughfare: type: string dependent_thoroughfare: type: string post_town: type: string postcode: type: string po_box: type: string country: type: string uprn: type: number psr: description: Deprecated. Use the psrs relationship instead. type: object properties: indicator: type: boolean priority: type: - integer - 'null' notes: type: - string - 'null' contact: type: - string - 'null' meters: description: Deprecated. Use the meters relationship instead. type: array items: type: object properties: type: type: string number: type: integer location: type: object properties: british_national_grid: type: - object - 'null' properties: easting: type: number format: double northing: type: number format: double lat_long: type: - object - 'null' properties: latitude: type: number format: double longitude: type: number format: double PropertyMeta: type: object description: Metadata for a property required: - created_at - updated_at properties: created_at: type: string format: date-time description: The date and time when the property was created updated_at: type: string format: date-time description: The date and time when the property was last updated PropertyRelationships: type: object description: Relationships for a property properties: street: type: object required: - data properties: data: $ref: '#/components/schemas/StreetRelationship' meters: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/MeterRelationship' psrs: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/PSRRelationship' SchemeAttributes: type: object description: Attributes for a scheme required: - name - status properties: name: type: string status: $ref: '#/components/schemas/LifecycleStatus' code: type: string description: type: string dates: type: object properties: anticipated: type: object properties: start: type: string format: date-time end: type: string format: date-time labels: type: array items: $ref: '#/components/schemas/Label' SchemeMeta: type: object description: Metadata for a scheme required: - created_at - updated_at - from_template - modified_at - dates - completeness - counts - is_default properties: created_at: type: string format: date-time updated_at: type: string format: date-time modified_at: type: string format: date-time imported_at: type: string format: date-time from_template: description: Whether this scheme was created from a template. type: boolean dates: type: object properties: scheduled: type: object properties: start: type: string format: date-time end: type: string format: date-time counts: type: object properties: operations: type: integer description: >- The number of operations in this scheme (from all of the work orders). format: int64 minimum: 0 default: 0 permits: type: integer description: >- The number of permits in this scheme (from all of the operations in all of the work orders). format: int64 minimum: 0 default: 0 properties: type: integer description: >- The number of properties in this scheme (from all of the operations in all of the work orders). format: int64 minimum: 0 default: 0 locations: type: integer description: >- The number of organisation-managed locations in this scheme (from all of the operations in all of the work orders) format: int64 minimum: 0 default: 0 streets: type: integer description: >- The number of streets in this scheme (from all of the operations in all of the work orders). format: int64 minimum: 0 default: 0 work_orders: type: integer description: The number of work orders in this scheme. format: int64 minimum: 0 default: 0 completeness: type: object required: - counts - percentage - statuses - done_reasons properties: percentage: type: object required: - completed - aborted - unknown - cancelled properties: completed: type: number minimum: 0 maximum: 100 default: 0 aborted: type: number minimum: 0 maximum: 100 default: 0 unknown: type: number minimum: 0 maximum: 100 default: 100 cancelled: type: number minimum: 0 maximum: 100 default: 0 counts: type: object required: - completed - aborted - unknown - cancelled properties: completed: type: integer minimum: 0 default: 0 aborted: type: integer minimum: 0 default: 0 unknown: type: integer minimum: 0 default: 1 cancelled: type: integer minimum: 0 default: 0 statuses: type: object required: - counts - percentages properties: counts: type: object required: - done - in_progress - todo properties: done: type: integer minimum: 0 default: 0 in_progress: type: integer minimum: 0 default: 0 todo: type: integer minimum: 0 default: 0 percentages: type: object required: - done - in_progress - todo properties: done: type: number minimum: 0 maximum: 100 default: 0 in_progress: type: number minimum: 0 maximum: 100 default: 0 todo: type: number minimum: 0 maximum: 100 default: 0 done_reasons: type: object required: - counts - percentages properties: counts: type: object required: - aborted - cancelled - completed properties: aborted: type: integer minimum: 0 default: 0 cancelled: type: integer minimum: 0 default: 0 completed: type: integer minimum: 0 default: 0 percentages: type: object required: - aborted - cancelled - completed properties: aborted: type: number minimum: 0 maximum: 100 default: 0 cancelled: type: number minimum: 0 maximum: 100 default: 0 completed: type: number minimum: 0 maximum: 100 default: 0 is_default: type: boolean default: false SchemeRelationships: type: object description: Relationships for a scheme required: - organisation properties: scheme_template: type: object required: - data properties: data: $ref: '#/components/schemas/SchemeTemplateRelationship' work_orders: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/WorkOrderRelationship' template: type: object required: - data properties: data: $ref: '#/components/schemas/SchemeTemplateRelationship' site_managers: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/UserRelationship' assignees: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/UserRelationship' teams: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/TeamRelationship' organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' folder: type: object required: - data properties: data: $ref: '#/components/schemas/FolderRelationship' contracts: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/SchemeContractRelationship' locations: type: object description: > The organisation-managed locations this scheme's work is against, aggregated from the operations beneath it. Read-only here: the relationship is owned by the operation. required: - data properties: data: type: array items: $ref: '#/components/schemas/LocationRelationship' created_by_user: type: object description: > The user who created this scheme. Absent when it was created by a service account or by a v2 subscriber, and on every scheme created before the creator was recorded. Set by the server. required: - data properties: data: $ref: '#/components/schemas/UserRelationship' created_by_service_account: type: object description: > The service account that created this scheme. Absent when it was created by a user or by a v2 subscriber, and on every scheme created before the creator was recorded. Set by the server. required: - data properties: data: $ref: '#/components/schemas/ServiceAccountRelationship' StreetAttributes: type: object description: Attributes for a street required: - usrn properties: name: type: string examples: - Main Street usrn: type: number examples: - 14930043 location: type: object required: - british_national_grid properties: british_national_grid: type: array items: type: array items: type: object required: - northing - easting properties: northing: type: number examples: - 557794 easting: type: number examples: - 426415 highway_authority: type: string examples: - National Highways highway_authority_code: type: number examples: - 1350 town: type: string examples: - Birmingham StreetMeta: type: object description: Metadata for a street required: - created_at - updated_at properties: created_at: type: string format: date-time description: The date and time when the street was created updated_at: type: string format: date-time description: The date and time when the street was last updated StreetRelationships: type: object description: Relationships for a street properties: properties: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/PropertyRelationship' StreetManagerPermitAttributes: type: object description: Attributes for a street manager permit required: - activated - end_date - permit_reference_number - permit_reference_number_iteration - start_date - status - usrn - work_reference_number - work_status_ref properties: activated: type: boolean description: Whether the permit is activated or not usrn: type: number description: Unique Street Reference Number permit_reference_number: type: string description: The unique reference number for this permit permit_reference_number_iteration: type: integer description: >- The iteration number of the permit based on the permit reference number work_reference_number: type: string description: The reference number for the work associated with this permit status: type: string description: The current status of the permit enum: - submitted - granted - permit_modification_request - refused - closed - cancelled - revoked - progressed work_status_ref: type: string description: The current status of the work as a reference enum: - completed - cancelled - planned - in_progress start_date: type: string format: date-time description: The start date of the permit end_date: type: string format: date-time description: The end date of the permit StreetManagerPermitMeta: type: object description: Metadata for a street manager permit required: - created_at - modified_at - updated_at properties: created_at: type: string format: date-time description: The date and time when the street manager permit was created modified_at: type: string format: date-time description: The date and time when the street manager permit was last modified updated_at: type: string format: date-time description: The date and time when the street manager permit was last updated StreetManagerPermitRelationships: type: object description: Relationships for a street manager permit properties: latest_version: type: object required: - data properties: data: $ref: '#/components/schemas/StreetManagerPermitVersionRelationship' versions: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/StreetManagerPermitVersionRelationship' TeamAttributes: type: object description: Attributes for a team properties: name: type: string description: The name of the team. examples: - Customer Service Representatives description: type: string description: A description of the team. examples: - >- Team responsible for handling customer inquiries and support requests TeamMeta: type: object description: Meta information for a team properties: created_at: type: string format: date-time description: The creation time of the team. examples: - '2025-07-16T12:42:40.000Z' updated_at: type: string format: date-time description: The last update time of the team. examples: - '2025-07-16T12:42:44.000Z' TeamRelationships: type: object description: Relationships for a team properties: members: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/UserRelationship' organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' schemas: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/FormSchemaRelationship' 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' 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' WorkOrderAttributes: type: object description: Attributes for a work order required: - name - status properties: name: type: string description: The name of the work order examples: - Infrastructure Maintenance Work Order status: $ref: '#/components/schemas/LifecycleStatus' code: type: string description: The code of the work order examples: - WO-2025-001 description: type: string description: The description of the work order examples: - Routine maintenance and inspection of electrical infrastructure dates: type: object description: The dates associated with the work order properties: anticipated: type: object description: The anticipated start and end dates properties: start: type: string format: date-time description: The anticipated start date examples: - '2025-08-01T09:00:00Z' end: type: string format: date-time description: The anticipated end date examples: - '2025-08-15T17:00:00Z' labels: type: array description: The labels associated with the work order items: $ref: '#/components/schemas/Label' WorkOrderMeta: type: object description: Metadata for a work order required: - created_at - updated_at - modified_at - counts - dates - completeness properties: created_at: type: string format: date-time description: The date and time when the work order was created examples: - '2025-05-06T18:37:12Z' updated_at: type: string format: date-time description: The date and time when the work order was last updated examples: - '2025-05-07T21:12:46Z' modified_at: type: string format: date-time description: The date and time when the work order was last modified examples: - '2025-05-07T21:12:46Z' dates: type: object description: The scheduled dates for the work order properties: scheduled: type: object description: The scheduled start and end dates properties: start: type: string format: date-time description: The scheduled start date examples: - '2025-08-01T09:00:00Z' end: type: string format: date-time description: The scheduled end date examples: - '2025-08-15T17:00:00Z' counts: type: object description: The counts of related entities required: - operations - properties - locations - streets properties: operations: type: integer description: The number of operations in this work order format: int64 minimum: 0 default: 0 examples: - 1 streets: type: integer description: >- The number of streets in this work order (from all of the operations in this work order) format: int64 minimum: 0 default: 0 examples: - 1 properties: type: integer description: >- The number of properties in this work order (from all of the operations in this work order) format: int64 minimum: 0 default: 0 examples: - 1 locations: type: integer description: >- The number of organisation-managed locations in this work order (from all of the operations in this work order) format: int64 minimum: 0 default: 0 examples: - 1 completeness: type: object description: The completeness statistics for the work order required: - percentage - counts - statuses - done_reasons properties: percentage: type: object description: The percentage breakdown of completion status required: - completed - aborted - unknown - cancelled properties: completed: type: number minimum: 0 maximum: 100 default: 0 description: The percentage of completed operations examples: - 25 aborted: type: number minimum: 0 maximum: 100 default: 0 description: The percentage of aborted operations examples: - 0 unknown: type: number minimum: 0 maximum: 100 default: 0 description: The percentage of operations with unknown status examples: - 75 cancelled: type: number minimum: 0 maximum: 100 default: 0 description: The percentage of cancelled operations examples: - 0 counts: type: object description: The count breakdown of completion status required: - completed - aborted - unknown - cancelled properties: completed: type: integer minimum: 0 default: 0 description: The number of completed operations examples: - 1 aborted: type: integer minimum: 0 default: 0 description: The number of aborted operations examples: - 0 unknown: type: integer minimum: 0 default: 0 description: The number of operations with unknown status examples: - 3 cancelled: type: integer minimum: 0 default: 0 description: The number of cancelled operations examples: - 0 statuses: type: object required: - counts - percentages properties: counts: type: object required: - done - in_progress - todo properties: done: type: integer minimum: 0 default: 0 examples: - 3 in_progress: type: integer minimum: 0 default: 0 examples: - 1 todo: type: integer minimum: 0 default: 0 examples: - 1 percentages: type: object required: - done - in_progress - todo properties: done: type: number minimum: 0 maximum: 100 default: 0 examples: - 60 in_progress: type: number minimum: 0 maximum: 100 default: 0 examples: - 20 todo: type: number minimum: 0 maximum: 100 default: 0 examples: - 20 done_reasons: type: object required: - counts - percentages properties: counts: type: object required: - aborted - cancelled - completed properties: aborted: type: integer minimum: 0 default: 0 examples: - 1 cancelled: type: integer minimum: 0 default: 0 examples: - 2 completed: type: integer minimum: 0 default: 0 examples: - 2 percentages: type: object required: - aborted - cancelled - completed properties: aborted: type: number minimum: 0 maximum: 100 default: 0 examples: - 20 cancelled: type: number minimum: 0 maximum: 100 default: 0 examples: - 40 completed: type: number minimum: 0 maximum: 100 default: 0 examples: - 40 WorkOrderRelationships: type: object description: Relationships for a work order required: - organisation - scheme - operations properties: organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' assignees: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/UserRelationship' teams: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/TeamRelationship' scheme: type: object required: - data properties: data: $ref: '#/components/schemas/SchemeRelationship' operations: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/OperationRelationship' template: type: object required: - data properties: data: $ref: '#/components/schemas/WorkOrderTemplateRelationship' site_managers: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/UserRelationship' folder: type: object required: - data properties: data: $ref: '#/components/schemas/FolderRelationship' locations: type: object description: > The organisation-managed locations this work order's work is against, aggregated from the operations beneath it. Read-only here: the relationship is owned by the operation. required: - data properties: data: type: array items: $ref: '#/components/schemas/LocationRelationship' created_by_user: type: object description: > The user who created this work order. Absent when it was created by a service account or by a v2 subscriber, and on every work order created before the creator was recorded. Set by the server. required: - data properties: data: $ref: '#/components/schemas/UserRelationship' created_by_service_account: type: object description: > The service account that created this work order. Absent when it was created by a user or by a v2 subscriber, and on every work order created before the creator was recorded. Set by the server. required: - data properties: data: $ref: '#/components/schemas/ServiceAccountRelationship' FormCategoryRelationship: type: object description: Represents a relationship to a form category required: - id - type properties: id: type: string format: uuid description: The unique identifier of the form category type: type: string const: form-categories WorkflowDefinitionRelationship: type: object description: Represents a relationship to a workflow definition required: - id - type properties: id: type: string format: uuid description: The unique identifier of the workflow definition type: type: string const: workflow-definitions FormSchemaRelationship: type: object description: Represents a relationship to a form schema required: - id - type properties: id: type: string format: uuid description: The unique identifier of the form schema type: type: string const: form-schemas FormSubmissionRelationship: type: object description: Represents a relationship to a form submission required: - id - type properties: id: type: string format: uuid description: The unique identifier of the form submission type: type: string const: form-submissions SchemeTemplateRelationship: type: object description: Represents a relationship to a scheme template required: - id - type properties: id: type: string format: uuid description: The unique identifier of the scheme template type: type: string const: scheme-templates OperationTypeColourPalette: type: string description: The palette component of the operation type's colour enum: - purple - blue - green - yellow - red - orange - grey OperationTypeColourShade: type: string description: The shade component of the operation type's colour enum: - '50' - '100' - '200' - '300' - '400' - '500' - '600' - '700' - '800' - '900' - '950' 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 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 GeoPoint: type: object description: > A point on the ground, given in either British National Grid eastings and northings or in latitude and longitude. Supply one standard, not both. The platform stores what it is given and does not convert between the two, so a point carries the standard it was entered in and only that one is populated on read. Supplying both is rejected: choosing one would silently discard the other. Each coordinate must be complete. Half a coordinate locates nothing, and a missing member would otherwise be read as a zero, putting a pole in the Gulf of Guinea or off the Isles of Scilly. The `oneOf` below is what makes that rule part of the contract rather than only prose, so a generated client cannot construct a point the API refuses. The third branch is the point that carries neither standard, which is how an empty `{}` clears a coordinate. properties: british_national_grid: type: - object - 'null' required: - easting - northing properties: easting: type: number format: double northing: type: number format: double lat_long: type: - object - 'null' required: - latitude - longitude properties: latitude: type: number format: double longitude: type: number format: double oneOf: - title: BritishNationalGridPoint description: A point given in British National Grid eastings and northings. required: - british_national_grid properties: british_national_grid: type: object lat_long: type: 'null' - title: LatLongPoint description: A point given in latitude and longitude. required: - lat_long properties: lat_long: type: object british_national_grid: type: 'null' - title: NoPoint description: > Neither standard carries a coordinate, which clears the point rather than storing one. properties: british_national_grid: type: 'null' lat_long: type: 'null' PostalAddress: type: object description: > A structured postal address. Every field is optional: an address is often partial, and a place that has one at all is better recorded incompletely than not at all. properties: description: type: string description: The address as a single line, as it would be written on an envelope. department: type: string organisation: type: string number: type: string name: type: string thoroughfare: type: string dependent_thoroughfare: type: string post_town: type: string postcode: type: string po_box: type: string country: type: string LocationTypeRelationship: type: object description: Represents a relationship to a location type required: - id - type properties: id: type: string format: uuid description: The unique identifier of the location type type: type: string const: location-types MeterRelationship: type: object description: Represents a relationship to a meter required: - id - type properties: id: type: string format: uuid description: The unique identifier of the meter type: type: string const: meters PSRRelationship: type: object description: Represents a relationship to a PSR record required: - id - type properties: id: type: string format: uuid description: The unique identifier of the PSR record type: type: string const: psrs LifecycleStatus: type: string description: > The lifecycle status of a contract, scheme or work order. - `in_planning`: work is being scoped and prepared; nothing is underway yet - `in_progress`: work is actively underway - `on_hold`: work has been paused and is expected to resume - `complete`: all work has been finished Any status may move to any other status; there are no restricted transitions. Resources created before this field existed, and resources created through the API, both start as `in_planning`. This is distinct from the operation status rollups under `meta`, which are derived from child operations and describe progress rather than intent. enum: - in_planning - in_progress - on_hold - complete FolderRelationship: type: object description: Represents a relationship to a folder required: - id - type properties: id: type: string format: uuid description: The unique identifier of the folder type: type: string const: folders SchemeContractRelationship: type: object description: Represents a relationship to a scheme contract required: - id - type properties: id: type: string format: uuid description: The unique identifier of the scheme contract type: type: string const: scheme-contracts StreetManagerPermitVersionRelationship: type: object description: Represents a relationship to a street manager permit version required: - id - type properties: id: type: string format: uuid description: The unique identifier of the street manager permit version type: type: string const: street-manager-permit-versions OperationRelationship: type: object description: Represents a relationship to an operation required: - id - type properties: id: type: string format: uuid description: The unique identifier of the operation type: type: string const: operations WorkOrderTemplateRelationship: type: object description: Represents a relationship to a work order template required: - id - type properties: id: type: string format: uuid description: The unique identifier of the work order template type: type: string const: work-order-templates 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 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.