> ## 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. # Hand over a pre-construction information > Hand the document over to the other party, which mints revision 1. Only the Client can, and only once. The handing-over principal comes from the request, and the recipient is the nominated Principal Contractor. After handover every change goes through a proposed change. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v3/pre-construction-informations/{pre_construction_information_id}/handover 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 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/pre-construction-informations/{pre_construction_information_id}/handover: post: tags: - Pre-Construction Information summary: Hand over a pre-construction information description: > Hand the document over to the other party, which mints revision 1. Only the Client can, and only once. The handing-over principal comes from the request, and the recipient is the nominated Principal Contractor. After handover every change goes through a proposed change. operationId: HandOverPreConstructionInformation parameters: - $ref: '#/components/parameters/pre_construction_information_id' responses: '200': $ref: '#/components/responses/GetPreConstructionInformationRevision' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorised' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalServerError' security: - Session: [] - OAuth2: [] - Cookie: [] components: parameters: pre_construction_information_id: name: pre_construction_information_id in: path required: true description: The unique identifier for the pre-construction information resource. schema: type: string format: uuid example: 5a1e7c3b-92d4-4f6a-8b0e-3c9d1f2a6e41 responses: GetPreConstructionInformationRevision: description: A pre-construction information revision. 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/PreConstructionInformationRevision' - $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 Forbidden: description: >- The authenticated principal does not hold the grant required for this action 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: errors: - id: 1b3f2c30-2d56-4d3a-9c44-9be9c2cbf2f0 status: '403' title: Forbidden detail: You do not hold the grant required for this action. code: AUTH.002 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. 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: PreConstructionInformationRevision: type: object description: > An immutable revision of a pre-construction information: the document as it stood when the revision was minted. Nothing can change or delete it. required: - id - type - attributes - relationships properties: id: type: string format: uuid type: type: string const: pre-construction-information-revisions attributes: $ref: '#/components/schemas/PreConstructionInformationRevisionAttributes' relationships: $ref: '#/components/schemas/PreConstructionInformationRevisionRelationships' 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 PreConstructionInformationRevisionAttributes: type: object description: > Attributes for a pre-construction information revision. `attestations` holds every sign-off made up to and including this revision, each naming the revision it attested. required: - number - cause - proposer - recipient - minted_at - document - hazards - attestations properties: number: type: integer minimum: 1 description: The revision's number. Revision 1 is the handover. cause: $ref: '#/components/schemas/CDMRevisionCause' proposer: $ref: '#/components/schemas/CDMActor' recipient: $ref: '#/components/schemas/CDMActor' minted_at: type: string format: date-time document: $ref: '#/components/schemas/PCIRevisionDocument' hazards: type: array items: $ref: '#/components/schemas/CDMRevisionHazard' attestations: $ref: '#/components/schemas/CDMAttestations' PreConstructionInformationRevisionRelationships: type: object description: Relationships for a pre-construction information revision required: - pre_construction_information properties: pre_construction_information: type: object description: The document this is a revision of. required: - data properties: data: $ref: '#/components/schemas/PreConstructionInformationRelationship' proposed_change: type: object description: >- The accepted proposed change that minted this revision. Absent for the handover. properties: data: $ref: >- #/components/schemas/PreConstructionInformationProposedChangeRelationship CDMRevisionCause: type: string description: > What minted a revision. Revision 1 comes from the handover, and every later one from an accepted proposed change. A construction phase plan's revision can also come from an accepted change to a hazard on the pre-construction information, which refreshed the plan's risks. enum: - handover - proposed_change - hazard_change CDMActor: type: object description: > A party acting on a CDM document: who acted, in which duty-holder role, for which organisation, and when. Every field is taken from the authenticated request. A handover's recipient names an organisation and role but no principal, because the recipient does not act. required: - acting_role - organisation_id - at properties: principal_type: type: - string - 'null' enum: - users - service-accounts - null description: >- Whether a user or a service account acted. Null for a handover's recipient. principal_id: type: - string - 'null' format: uuid acting_role: $ref: '#/components/schemas/CDMRole' organisation_id: type: string format: uuid at: type: string format: date-time PCIRevisionDocument: type: object description: >- A pre-construction information's sections and nomination as they stood when a revision was minted. required: - project_information - notifiability - notifiability_result - duty_holders - planning_information - file_log properties: project_information: $ref: '#/components/schemas/PCIProjectInformation' notifiability: $ref: '#/components/schemas/PCINotifiability' notifiability_result: $ref: '#/components/schemas/NotifiabilityResult' duty_holders: $ref: '#/components/schemas/PCIDutyHolders' planning_information: $ref: '#/components/schemas/PCIPlanningInformation' file_log: $ref: '#/components/schemas/PCIFileLog' principal_contractor_id: type: - string - 'null' format: uuid description: The nominated Principal Contractor organisation. CDMRevisionHazard: type: object description: A hazard as it stood when a revision was minted. required: - id - reference - description - version properties: id: type: string format: uuid reference: type: string description: type: string associated_activity: type: - string - 'null' identified_by: type: - string - 'null' identified_by_user_id: type: - string - 'null' format: uuid description: >- The user who identified the hazard, when they have an account. The name is kept as written either way. identified_on: type: - string - 'null' format: date version: type: integer CDMAttestations: type: array readOnly: true description: Every sign-off of the document's sections, oldest first. items: $ref: '#/components/schemas/CDMAttestation' PreConstructionInformationRelationship: type: object description: Represents a relationship to a pre-construction information required: - id - type properties: id: type: string format: uuid description: The unique identifier of the pre-construction information type: type: string const: pre-construction-informations PreConstructionInformationProposedChangeRelationship: type: object description: >- Represents a relationship to a proposed change to a pre-construction information required: - id - type properties: id: type: string format: uuid type: type: string const: pre-construction-information-proposed-changes CDMRole: type: string description: > A CDM 2015 duty-holder role on a scheme. The scheme owner is the Client and Principal Designer. The organisation nominated on the Pre-Construction Information is the Principal Contractor. Any other organisation the scheme is shared with is a reader. enum: - client_and_principal_designer - principal_contractor - reader PCIProjectInformation: type: object description: Project information. Owned by the Client and Principal Designer. x-cdm-owner: client_and_principal_designer additionalProperties: false properties: description: type: - string - 'null' description: What the project is. location: type: - string - 'null' description: Where the work is. planned_start_date: type: - string - 'null' format: date planned_end_date: type: - string - 'null' format: date existing_information: type: - string - 'null' description: Drawings, surveys and records available for the site. client_requirements: type: - string - 'null' description: >- The Client's requirements for managing health and safety, such as permits, security and welfare. PCINotifiability: type: object description: >- The Client's estimates for the CDM 2015 Reg 6 notifiability test. Owned by the Client and Principal Designer. Each is a whole number, and is absent until given. x-cdm-owner: client_and_principal_designer additionalProperties: false properties: person_days: type: - integer - 'null' minimum: 0 description: >- The estimated total of days worked by everyone on the project. More than 500 is notifiable on its own. working_days: type: - integer - 'null' minimum: 0 description: >- Every day on which construction work is likely to be carried out, including weekends and holidays, as HSE counts them. Not the planned end date minus the start date when work will not happen every day. peak_workers: type: - integer - 'null' minimum: 0 description: The most workers expected on site at the same time. NotifiabilityResult: type: object readOnly: true description: >- The CDM 2015 Reg 6 test applied to the pack's notifiability inputs, computed on every read. Limb one is more than 30 working days and more than 20 workers at the same time. Limb two is more than 500 person-days. Either limb met makes the project notifiable. Every threshold is exclusive. required: - outcome - limb_one - limb_two properties: outcome: $ref: '#/components/schemas/NotifiabilityOutcome' limb_one: $ref: '#/components/schemas/NotifiabilityLimb' limb_two: $ref: '#/components/schemas/NotifiabilityLimb' PCIDutyHolders: type: object description: > Duty-holder details. Owned by the Client and Principal Designer. The Principal Contractor nomination is the document's `principal_contractor` relationship, and belongs to this section. x-cdm-owner: client_and_principal_designer additionalProperties: false properties: client: $ref: '#/components/schemas/CDMContact' principal_designer: $ref: '#/components/schemas/CDMContact' designers: type: array items: $ref: '#/components/schemas/CDMContact' PCIPlanningInformation: type: object description: > Pre-construction planning information, one field per topic. Owned by the Client and Principal Designer. x-cdm-owner: client_and_principal_designer additionalProperties: false properties: existing_services: $ref: '#/components/schemas/PCIPlanningTopic' ground_conditions: $ref: '#/components/schemas/PCIPlanningTopic' contaminated_land: $ref: '#/components/schemas/PCIPlanningTopic' asbestos: $ref: '#/components/schemas/PCIPlanningTopic' existing_structures: $ref: '#/components/schemas/PCIPlanningTopic' hazardous_materials: $ref: '#/components/schemas/PCIPlanningTopic' adjacent_land_use: $ref: '#/components/schemas/PCIPlanningTopic' access_and_traffic: $ref: '#/components/schemas/PCIPlanningTopic' working_hours_restrictions: $ref: '#/components/schemas/PCIPlanningTopic' security: $ref: '#/components/schemas/PCIPlanningTopic' environmental_constraints: $ref: '#/components/schemas/PCIPlanningTopic' unexploded_ordnance: $ref: '#/components/schemas/PCIPlanningTopic' PCIFileLog: type: array description: >- The pre-construction file log. Owned by the Client and Principal Designer. x-cdm-owner: client_and_principal_designer items: type: object additionalProperties: false required: - title properties: title: type: string minLength: 1 reference: type: - string - 'null' issued_on: type: - string - 'null' format: date notes: type: - string - 'null' CDMAttestation: type: object description: > A sign-off of one section. Every field is derived on the server from the authenticated request, and none is accepted from a client. required: - section - acting_role - attested_at - attested_by_type - attested_by_id - revision properties: section: type: string description: The section that was signed off. acting_role: $ref: '#/components/schemas/CDMRole' organisation_id: type: string format: uuid description: The organisation the principal acted for. attested_at: type: string format: date-time attested_by_type: type: string enum: - users - service-accounts description: >- Whether a user or a service account signed it off. A client shows the two differently. attested_by_id: type: string format: uuid revision: type: integer description: >- The document's revision when the section was signed off. 0 means before handover. NotifiabilityOutcome: type: string description: >- Unknown means an input the result depends on has not been given. It never means not notifiable. enum: - notifiable - not_notifiable - unknown NotifiabilityLimb: type: object description: One limb of the notifiability test, and the inputs it used. required: - outcome properties: outcome: $ref: '#/components/schemas/NotifiabilityOutcome' working_days: type: - integer - 'null' peak_workers: type: - integer - 'null' person_days: type: - integer - 'null' CDMContact: type: object description: A named person at a duty-holder. additionalProperties: false properties: name: type: - string - 'null' organisation: type: - string - 'null' phone: type: - string - 'null' email: type: - string - 'null' user_id: type: - string - 'null' format: uuid description: >- The user this contact is, when they have an account. The name is kept as written either way. organisation_id: type: - string - 'null' format: uuid description: >- The organisation this contact works for, when it is a party to the scheme. The name is kept as written either way. PCIPlanningTopic: type: object description: One planning topic. additionalProperties: false properties: relevant: type: - boolean - 'null' description: Whether the topic is relevant to this project. Null until answered. comments: type: - string - 'null' 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.