openapi: 3.0.1
info:
  title: Controls API
  description: >-
    The Controls API provides access to manage and retrieve control information
    within a Hyperproof organization. This API allows you to list, create,
    update, and manage controls and any linked proof, ensuring compliance and
    oversight of organizational processes.
  version: 1.0.0
servers:
  - url: https://api.hyperproof.app/v1/controls
    description: Hyperproof US
  - url: https://api.hyperproofgov.app/v1/controls
    description: Hyperproof Gov
  - url: https://api.hyperproof.eu/v1/controls
    description: Hyperproof EU
security:
  - oauth2: []
paths:
  /:
    get:
      summary: Get Controls
      description: >+
        `GET /`


        #### Description


        Fetches a collection of controls based on specified query parameters.
        Use this endpoint to retrieve controls with optional filters for
        permissions, scopes, teams, or status.


        #### Notes and caveats


        ##### Finding scoped controls


        Use the `GET /` controls endpoint with the `expandscopes=true` query
        parameter. This addition pulls in extra information about scoped
        controls, such as:


        - Controls with a `parentControlId` value, showing the original parent
        control they stem from.

        - The linked `scopeId` and `scopeName` for each scoped control.


        ```bash

        GET https://api.hyperproof.app/v1/controls?expandscopes=true

        ```


        ---

      operationId: get-controls
      parameters:
        - name: canLink
          in: query
          description: >-
            If true, only returns controls to which the requesting user has link
            permission
          schema:
            type: string
        - name: expandScopes
          in: query
          description: If true, includes scope controls as well as parent controls
          schema:
            type: string
        - name: expandTeams
          in: query
          description: If true, includes team controls as well as parent controls
          schema:
            type: string
        - name: status
          in: query
          description: Filters results by the provided object status
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ControlCollection'
              example:
                - id: d88d505d-5199-11ee-a644-522476618ae8
                  orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                  controlType: scopeAssignment
                  controlIdentifier: SOC2-P4.1.1_Legal
                  name: >-
                    Include in the privacy notice the use of collected personal
                    information
                  scopeName: Legal
                  description: >-
                    The privacy notice identifies the use of collected personal
                    information.
                  notes: ''
                  domainId: d7cf0a26-5199-11ee-a644-522476618ae8
                  domainName: Privacy
                  freshnessPolicy: manual
                  freshForDuration: PT720H
                  freshness: fresh
                  freshAsOfDate: 2025-01-12T18:26:10.00.5365Z
                  freshAsOfNote: Initial freshness set
                  implementation: inProgress
                  testingStatus: effective
                  testingDeficiency: []
                  computeTestingStatus: false
                  automation: partial
                  health: notAvailable
                  overrideHealth: false
                  owner:
                    id: d2363cab-5199-11ee-a644-522476618ae8
                    type: activeUser
                    userId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                    email: jane.doe@example.com
                    givenName: Jane
                    surname: Doe
                    language: en
                    locale: US
                    timeZone: America/Los_Angeles
                    status: active
                  customFields:
                    - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                      fieldName: Sponsor
                      fieldType: text
                      textValue: John Smith
                  status: active
                  createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                  createdOn: '2023-09-12T18:26:10.0053650+00:00'
                  updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                  updatedOn: '2023-09-12T18:26:10.0053650+00:00'
                  permissions: []
    post:
      summary: Add Control
      description: >
        `POST /`


        #### Description


        Adds a new control to the organization with specified attributes, such
        as identifier, name, description, and owner.


        #### Notes and caveats


        ##### Setting up a new control with a scope using `POST`


        If you’re creating a control from scratch, you can assign a scope right
        away with the `POST /controls` endpoint. Just use the desired `scopeId`
        in the request payload alongside other control details.  


        **Note**:  This action creates a NEW control that can be used as a
        parent.  Child controls are not created using the API.  


        Currently, the creation of scoped child controls on existing controls is
        not supported.


        ```bash

        POST https://api.hyperproof.app/v1/controls

        Content-Type: application/json

        {

        "name": "New Control Name",

        "scopeId": "desiredScopeId",

        ...other control properties...

        }


        ```
      operationId: add-control
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ControlPost'
            example:
              controlIdentifier: SOC2-P4.1.1
              name: >-
                Include in the privacy notice the use of collected personal
                information
              description: >-
                The privacy notice identifies the use of collected personal
                information.
              domainName: Privacy
              implementation: inProgress
              owner: 82d7c228-8bcd-11e9-a94b-ab3de8494987
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Control'
              example:
                id: d88d505d-5199-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                controlType: scopeAssignment
                controlIdentifier: SOC2-P4.1.1_Legal
                name: >-
                  Include in the privacy notice the use of collected personal
                  information
                createdOn: '2023-09-12T18:26:10.0053650+00:00'
                updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                updatedOn: '2023-09-12T18:26:10.0053650+00:00'
                permissions: []
  /{controlId}/proof:
    post:
      summary: Add Control Proof
      description: |-
        `POST /{controlId}/proof`

        #### Description

        Uploads a proof item (e.g. a file) to associate with a specific control.
      operationId: add-control-proof
      parameters:
        - name: controlId
          in: path
          description: Unique ID of the control.
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data: {}
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Proof'
              example:
                id: 4eb909de-51af-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                filename: example.txt
                contentType: text/plain
                fileExtension: txt
                size: 627
                version: 0
                source: localComputer
                ownedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                uploadedOn: '2023-09-12T20:59:47.6943530+00:00'
                isPrivate: false
                status: active
                createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                createdOn: '2023-09-12T20:59:47.6943530+00:00'
                updatedOn: '2023-09-12T20:59:47.6943530+00:00'
  /filter:
    put:
      summary: Get Controls Filtered
      description: >-
        `PUT /filter`


        #### Description


        Fetches controls matching a provided filter, such as a list of control
        IDs.
      operationId: get-controls-filtered
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ControlFilter'
            example:
              controlIds:
                - 23b806db-bad2-4f7a-b8d1-ac1177909992
                - 23b402db-bad2-4f7a-b8d1-ac1177909992
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ControlCollection'
              example:
                - id: d88d505d-5199-11ee-a644-522476618ae8
                  orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                  controlType: scopeAssignment
                  controlIdentifier: SOC2-P4.1.1_Legal
                  name: >-
                    Include in the privacy notice the use of collected personal
                    information
                  scopeName: Legal
                  description: >-
                    The privacy notice identifies the use of collected personal
                    information.
                  notes: ''
                  domainId: d7cf0a26-5199-11ee-a644-522476618ae8
                  domainName: Privacy
                  freshnessPolicy: manual
                  freshForDuration: PT720H
                  freshness: fresh
                  freshAsOfDate: 2025-01-12T18:26:10.00.5365Z
                  freshAsOfNote: Initial freshness set
                  implementation: inProgress
                  testingStatus: effective
                  testingDeficiency: []
                  computeTestingStatus: false
                  automation: partial
                  health: notAvailable
                  overrideHealth: false
                  owner:
                    id: d2363cab-5199-11ee-a644-522476618ae8
                    type: activeUser
                    userId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                    email: jane.doe@example.com
                    givenName: Jane
                    surname: Doe
                    language: en
                    locale: US
                    timeZone: America/Los_Angeles
                    status: active
                  customFields:
                    - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                      fieldName: Sponsor
                      fieldType: text
                      textValue: John Smith
                  status: active
                  createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                  createdOn: '2023-09-12T18:26:10.0053650+00:00'
                  updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                  updatedOn: '2023-09-12T18:26:10.0053650+00:00'
                  permissions: []
  /summaries:
    get:
      summary: Get Control Summaries
      description: >-
        `GET /summaries`


        #### Description


        Fetches a summarized list of controls, including their IDs, identifiers,
        names, and timestamps.
      operationId: get-control-summaries
      parameters:
        - name: canLink
          in: query
          description: >-
            If true, only returns control summaries the requesting user has link
            permission for
          schema:
            type: string
        - name: status
          in: query
          description: Filters results by the provided object status
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ControlSummaryCollection'
              example:
                - id: 09bb0a00-519a-11ee-a644-522476618ae8
                  controlIdentifier: SOC2-CC9.2.4
                  name: >-
                    Establish roles and responsibilities to oversee
                    implementation of information security policies, incident
                    response
                  createdOn: '2023-09-08T18:26:10.0053650+00:00'
                  updatedOn: '2023-09-08T18:26:10.0053650+00:00'
                - id: d88d505d-5199-11ee-a644-522476618ae8
                  controlIdentifier: SOC2-P4.1.1
                  name: >-
                    Include in the privacy notice the use of collected personal
                    information
                  createdOn: '2023-09-12T18:26:10.0053650+00:00'
                  updatedOn: '2023-09-12T18:26:10.0053650+00:00'
  /{controlId}:
    get:
      summary: Get Control
      description: >-
        `GET /{controlId}`


        #### Description


        Fetches detailed information about a specific control using its unique
        ID.


        #### Notes and caveats


        ##### Finding scoped controls


        Use the `GET /controls` endpoint with the `expandscopes=true` query
        parameter. This addition pulls in extra information about scoped
        controls, such as:


        - Controls with a `parentControlId` value, showing the original parent
        control they stem from.

        - The linked `scopeId` and `scopeName` for each scoped control.


        ```bash

        GET https://api.hyperproof.app/v1/controls/{controlId}?expandscopes=true

        ```


        ---
      operationId: get-control
      parameters:
        - name: controlId
          in: path
          description: Unique ID of the control to retrieve.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Control'
              example:
                id: d88d505d-5199-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                controlType: scopeAssignment
                controlIdentifier: SOC2-P4.1.1_Legal
                name: >-
                  Include in the privacy notice the use of collected personal
                  information
                scopeName: Legal
                description: >-
                  The privacy notice identifies the use of collected personal
                  information.
                notes: ''
                domainId: d7cf0a26-5199-11ee-a644-522476618ae8
                domainName: Privacy
                freshnessPolicy: manual
                freshForDuration: PT720H
                freshness: fresh
                freshAsOfDate: 2025-01-12T18:26:10.00.5365Z
                freshAsOfNote: Initial freshness set
                implementation: inProgress
    patch:
      summary: Update Control
      description: >-
        `PATCH /{controlId}`


        #### Description


        Modifies an existing control’s attributes, such as name, description, or
        owner.


        #### Notes and caveats


        ##### Changing the scope on an existing control with `PATCH`


        You can do a `PATCH` request to
        `https://api.hyperproof.app/v1/controls/{controlId}`.  Just include the
        `scopeId` you want to assign in the request body. This links the control
        to the specified scope.


        - You must know the `scopeId` beforehand. There’s no API endpoint to
        list all available `scopeIds`, so you can get the `scopeId` by running a
        `GET /controls?expandscopes=true` call as mentioned earlier.

        - Double-check that the `scopeId` is valid for your Hyperproof setup
        before sending the request.


        ```bash   

        PATCH https://api.hyperproof.app/v1/controls/{controlId}  

        Content-Type: application/json  

        {  

        "scopeId": "desiredScopeId"  

        }

        ```
      operationId: update-control
      parameters:
        - name: controlId
          in: path
          description: Unique ID of the control to update.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ControlPatch'
            example:
              name: >-
                Include in the privacy notice the use of collected personal
                information
              description: >-
                The privacy notice identifies the use of collected personal
                information.
              notes: Meet quarterly to review
              freshnessPolicy: manual
              freshForDuration: PT720H
              freshness: fresh
              freshAsOfDate: 2025-01-12T18:26:10.00.5365Z
              freshAsOfNote: Updating expired control freshness
              implementation: inProgress
              testingStatus: effective
              owner: 82d7c228-8bcd-11e9-a94b-ab3de8494987
              customFields:
                - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                  textValue: Antonio Moreno
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Control'
              example:
                id: d88d505d-5199-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                controlType: scopeAssignment
                controlIdentifier: SOC2-P4.1.1_Legal
                name: >-
                  Include in the privacy notice the use of collected personal
                  information
                scopeName: Legal
                description: >-
                  The privacy notice identifies the use of collected personal
                  information.
                notes: ''
                domainId: d7cf0a26-5199-11ee-a644-522476618ae8
                domainName: Privacy
                freshnessPolicy: manual
                freshForDuration: PT720H
                freshness: fresh
                freshAsOfDate: 2025-01-12T18:26:10.00.5365Z
                freshAsOfNote: Initial freshness set
                implementation: inProgress
                testingStatus: effective
                testingDeficiency: []
                computeTestingStatus: false
                automation: partial
                health: notAvailable
                overrideHealth: false
                owner:
                  id: d2363cab-5199-11ee-a644-522476618ae8
                  type: activeUser
                  userId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                  email: jane.doe@example.com
                  givenName: Jane
                  surname: Doe
                  language: en
                  locale: US
                  timeZone: America/Los_Angeles
                  status: active
                customFields:
                  - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                    fieldName: Sponsor
                    fieldType: text
                    textValue: John Smith
                status: active
                createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                createdOn: '2023-09-12T18:26:10.0053650+00:00'
                updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                updatedOn: '2023-09-12T18:26:10.0053650+00:00'
                permissions: []
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://accounts.hyperproof.app/oauth/token
          scopes:
            control.read: Grants read access to controls
            control.update: Grants update access to controls
  schemas:
    Control:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the control
        orgId:
          type: string
          description: The unique identifier for the organization
        controlType:
          type: string
          description: Type of control
          enum:
            - simple
            - parent
            - scopeAssignment
        controlIdentifier:
          type: string
          description: >-
            The human readable unique identifier for the control within the
            organization
        name:
          type: string
          description: The name of the control
        teamName:
          type: string
          description: >-
            This field is deprecated and will be removed in a future version.
            Use `scopeName` instead
          deprecated: true
        scopeName:
          type: string
          description: >-
            Name of the scope associated with the control populated if the
            'controlType' is 'scopeAssignment'
        description:
          type: string
          description: The description of the control
        notes:
          type: string
          description: Additional notes about the control
        domainId:
          type: string
          description: The unique identifier of the domain
        domainName:
          type: string
          description: The name of the domain
        freshnessPolicy:
          $ref: '#/components/schemas/FreshnessPolicy'
        freshForDuration:
          type: string
          description: The duration after which control becomes stale
        freshness:
          $ref: '#/components/schemas/Freshness'
        freshAsOfDate:
          type: string
          description: The date when freshness was last marked 'fresh'
        freshAsOfNote:
          type: string
          description: The note populated when the control was marked fresh
        implementation:
          type: string
          description: Implementation status
          enum:
            - unknown
            - notStarted
            - inProgress
            - completed
        testingStatus:
          type: string
          description: Testing status
          enum:
            - notTested
            - inProgress
            - effective
            - ineffective
        testingDeficiency:
          type: array
          description: >-
            Design deficiency: The control, as designed, is inadequate to meet
            its intended objective. Operation deficiency: The control’s design
            is sound, but it is not being executed or followed as intended in
            practice.
          items:
            type: string
            enum:
              - design
              - operation
        computeTestingStatus:
          type: boolean
          description: Whether testing status is computed automatically
        automation:
          type: string
          description: >-
            Determines whether this control can be automated and its current
            status
          enum:
            - notStarted
            - partial
            - fullyAutomated
            - cantAutomate
        health:
          type: string
          description: Whether the health status is available and its current status
          enum:
            - critical
            - atRisk
            - healthy
            - notAvailable
        overrideHealth:
          type: boolean
          description: Whether health status is overridden
        owner:
          $ref: '#/components/schemas/User'
        groupId:
          type: string
          description: The unique identifier of the group assigned to the control
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldObjectValue'
        status:
          $ref: '#/components/schemas/ObjectStatus'
        createdBy:
          type: string
          description: The unique identifier of the user who created the control
        createdOn:
          type: string
          description: The date the control was created (ISO-8601 format)
        updatedBy:
          type: string
          description: The unique identifier of the user who last updated the control
        updatedOn:
          type: string
          description: The date the control was updated (ISO-8601 format)
        permissions:
          type: array
          description: List of permissions the API user has on the control
          items:
            type: string
        _isPartialData:
          type: boolean
          description: >-
            This is true when the user does not have read permissions on the
            control
      example:
        id: d88d505d-5199-11ee-a644-522476618ae8
        orgId: ce83e3cd-5199-11ee-a644-522476618ae8
        controlType: scopeAssignment
        controlIdentifier: SOC2-P4.1.1_Legal
        name: >-
          Include in the privacy notice the use of collected personal
          information
        scopeName: Legal
        description: >-
          The privacy notice identifies the use of collected personal
          information.
        notes: ''
        domainId: d7cf0a26-5199-11ee-a644-522476618ae8
        domainName: Privacy
        freshnessPolicy: manual
        freshForDuration: PT720H
        freshness: fresh
        freshAsOfDate: 2025-01-12T18:26:10.00.5365Z
        freshAsOfNote: Initial freshness set
        implementation: inProgress
        testingStatus: effective
        testingDeficiency: []
        computeTestingStatus: false
        automation: partial
        health: notAvailable
        overrideHealth: false
        owner:
          id: d2363cab-5199-11ee-a644-522476618ae8
          type: activeUser
          userId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
          email: jane.doe@example.com
          givenName: Jane
          surname: Doe
          language: en
          locale: US
          timeZone: America/Los_Angeles
          status: active
        customFields:
          - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
            fieldName: Sponsor
            fieldType: text
            textValue: John Smith
        status: active
        createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        createdOn: '2023-09-12T18:26:10.005365Z'
        updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        updatedOn: '2023-09-12T18:26:10.005365Z'
        permissions: []
    ControlCollection:
      type: array
      items:
        $ref: '#/components/schemas/Control'
    ControlFilter:
      type: object
      properties:
        controlIds:
          type: array
          items:
            type: string
      example:
        controlIds:
          - 23b806db-bad2-4f7a-b8d1-ac1177909992
          - 23b402db-bad2-4f7a-b8d1-ac1177909992
    ControlPatch:
      type: object
      properties:
        controlIdentifier:
          type: string
          description: The unique identifier for the control within the organization
        name:
          type: string
          description: Name of the control
        scopeId:
          type: string
          description: Unique identifier of the scope associated with the control
        teamId:
          type: string
          description: >-
            This field is deprecated and will be removed in a future version.
            Use `scopeId` instead
          deprecated: true
        description:
          type: string
          description: Description of the control
        notes:
          type: string
          description: Additional notes about the control
        domainId:
          type: string
          description: Identifier of the domain
        domainName:
          type: string
          description: Name of the domain
        clearDomain:
          type: boolean
          description: Clears the domain association if `true`
        freshnessPolicy:
          $ref: '#/components/schemas/FreshnessPolicy'
        freshForDuration:
          type: string
          description: >-
            Sets the duration after which the control becomes stale. Supply as a
            string in standard ISO-8601 duration format ex: P1Y3M2D or PT720H
        freshness:
          $ref: '#/components/schemas/Freshness'
        freshAsOfDate:
          type: string
          description: The date when freshness was last marked 'fresh'
        freshAsOfNote:
          type: string
          description: The note to populate when the control is marked 'fresh'
        resetFreshnessNote:
          type: string
          description: The note to populate when freshness is reset
        implementation:
          type: string
          description: Implementation status
          enum:
            - unknown
            - notStarted
            - inProgress
            - completed
        testingStatus:
          type: string
          description: Testing status
          enum:
            - notTested
            - inProgress
            - effective
            - ineffective
        testingDeficiency:
          type: array
          description: List of deficiencies
          items:
            type: string
            enum:
              - design
              - operation
        automation:
          type: string
          description: Automation status
          enum:
            - notStarted
            - partial
            - fullyAutomated
            - cantAutomate
        health:
          type: string
          description: Health status
          enum:
            - critical
            - atRisk
            - healthy
            - notAvailable
        overrideHealth:
          type: boolean
          description: Whether health status is overridden
        overrideHealthOn:
          type: string
          description: The date when health was overridden
        overrideHealthReason:
          type: string
          description: Reason for overriding health status
        computeTestingStatus:
          type: boolean
          description: Whether testing status is computed automatically
        owner:
          type: string
          description: The unique identifier of the user who owns the control
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldObjectValuePatch'
        status:
          $ref: '#/components/schemas/ObjectStatus'
        groupId:
          type: string
          description: >-
            The unique identifier of the group assigned to the control. If set,
            clearGroupId must not be set.
        clearGroupId:
          type: boolean
          description: >-
            Clears the group Unique identifier if `true`. If set, groupId must
            not be set. 
      example:
        name: >-
          Include in the privacy notice the use of collected personal
          information
        description: >-
          The privacy notice identifies the use of collected personal
          information.
        notes: Meet quarterly to review
        freshnessPolicy: manual
        freshForDuration: PT720H
        freshness: fresh
        freshAsOfDate: 2025-01-12T18:26:10.00.5365Z
        freshAsOfNote: Updating expired control freshness
        implementation: inProgress
        testingStatus: effective
        owner: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        customFields:
          - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
            textValue: Antonio Moreno
    ControlPost:
      type: object
      properties:
        controlIdentifier:
          type: string
          description: Unique identifier for the control within the organization
        name:
          type: string
          description: Name of the control
        scopeId:
          type: string
          description: Unique identifier of the scope associated with the control
        teamId:
          type: string
          description: >-
            This field is deprecated and will be removed in a future version.
            Use `scopeId` instead
          deprecated: true
        description:
          type: string
          description: Description of the control
        notes:
          type: string
          description: Additional notes about the control
        domainName:
          type: string
          description: Name of the domain
        implementation:
          type: string
          description: Implementation status
          enum:
            - unknown
            - notStarted
            - inProgress
            - completed
        testingStatus:
          type: string
          description: Testing status
          enum:
            - notTested
            - inProgress
            - effective
            - ineffective
        automation:
          type: string
          description: Automation status
          enum:
            - notStarted
            - partial
            - fullyAutomated
            - cantAutomate
        owner:
          type: string
          description: The unique identifier of the user who owns the control
        groupId:
          type: string
          description: The unique identifier of the group assigned to the control
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldObjectValuePatch'
        externalObjectIds:
          type: array
          items:
            type: string
          nullable: true
      required:
        - controlIdentifier
        - description
        - owner
      example:
        controlIdentifier: SOC2-P4.1.1
        name: >-
          Include in the privacy notice the use of collected personal
          information
        description: >-
          The privacy notice identifies the use of collected personal
          information.
        domainName: Privacy
        implementation: inProgress
        owner: 82d7c228-8bcd-11e9-a94b-ab3de8494987
    ControlSummaryCollection:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            description: Unique identifier for the control
          controlIdentifier:
            type: string
            description: >-
              Human readable unique identifier for the control within the
              organization
          name:
            type: string
            description: Name of the control
          createdOn:
            type: string
            description: The date the control was created (ISO-8601 format)
          updatedOn:
            type: string
            description: The date the control was last updated (ISO-8601 format)
      example:
        - id: 09bb0a00-519a-11ee-a644-522476618ae8
          controlIdentifier: SOC2-CC9.2.4
          name: >-
            Establish roles and responsibilities to oversee implementation of
            information security policies, incident response
          createdOn: '2023-09-08T18:26:10.005365Z'
          updatedOn: '2023-09-08T18:26:10.005365Z'
        - id: d88d505d-5199-11ee-a644-522476618ae8
          controlIdentifier: SOC2-P4.1.1
          name: >-
            Include in the privacy notice the use of collected personal
            information
          createdOn: '2023-09-12T18:26:10.005365Z'
          updatedOn: '2023-09-12T18:26:10.005365Z'
    CustomFieldObjectValue:
      type: array
      items:
        type: object
        properties:
          fieldId:
            type: string
            description: Unique identifier for the custom field
          fieldName:
            type: string
            description: Name of the custom field
          fieldType:
            type: string
            description: Type of field
            enum:
              - text
              - number
              - date
              - user
              - textSingleSelect
              - textMultiSelect
          numberFormat:
            type: string
            description: Format if the field type is `number`
            enum:
              - decimal
              - percentage
          textValue:
            type: string
            description: Value if the field type is `text`
          numberValue:
            type: number
            description: Value if the field type is `number`
          dateValue:
            type: string
            description: Value if the field type is `date`
          userValue:
            type: string
            description: Value if the field type is `user`
          selection:
            type: string
            description: Value for `textSingleSelect`
          selections:
            type: array
            description: List of values for `textMultiSelect`
            items:
              type: string
    CustomFieldObjectValuePatch:
      type: object
      properties:
        fieldId:
          type: string
          description: Unique identifier for the custom field
        textValue:
          type: string
          description: Value if the field type is `text`
        numberValue:
          type: number
          description: Value if the field type is `number`
        dateValue:
          type: string
          description: Value if the field type is `date`
        userValue:
          type: string
          description: Value if the field type is `user`
        selections:
          type: array
          description: List of values for `textMultiSelect`
          items:
            type: string
    Freshness:
      type: string
      description: >-
        The freshness status of an object. Cannot be set if 'freshnessPolicy' is
        'none' and 'freshAsOfDate' is null.
      enum:
        - noFreshness
        - fresh
        - expired
        - unknown
    FreshnessPolicy:
      type: string
      description: >-
        The freshness policy of an object. Set to 'manual' with a
        'freshAsOfDate' value otherwise 'freshness' will be set to 'unknown'.
      enum:
        - none
        - manual
    ObjectStatus:
      type: string
      description: The status of the object
      enum:
        - active
        - archived
    Proof:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the proof item
        orgId:
          type: string
          description: Unique identifier for the organization
        filename:
          type: string
          description: Name of the uploaded file
        nameOverride:
          type: string
          description: Name of proof Hyperproof given by Hyperproof user
        contentType:
          type: string
          description: MIME type of the file (e.g.,`text/plain`)
        fileExtension:
          type: string
          description: File extension (e.g.,`txt`)
        size:
          type: number
          description: File size in bytes
        version:
          type: integer
          description: Version of the proof item
        source:
          type: string
          description: Source of the file (e.g.,localComputer)
        sourceVersion:
          type: integer
          description: The version of the proof maintained by the source system
        ownedBy:
          type: string
          description: Unique identifier of the user who owns the proof item
        isPrivate:
          type: boolean
          description: Whether the proof item is private
        uploadedOn:
          type: string
          description: The date the proof was uploaded (ISO-8601 format)
        status:
          type: string
          description: Status of the proof item
          enum:
            - active
            - archived
            - deleted
            - pending
            - canceled
        createdBy:
          type: string
          description: Unique identifier of the user who created the proof item
        createdOn:
          type: string
          description: The date the proof was created (ISO-8601 format)
        updatedBy:
          type: string
          description: Unique identifier of the user who last updated the proof item
        updatedOn:
          type: string
          description: The date the proof was updated (ISO-8601 format)
      example:
        id: 4eb909de-51af-11ee-a644-522476618ae8
        orgId: ce83e3cd-5199-11ee-a644-522476618ae8
        filename: example.txt
        contentType: text/plain
        fileExtension: txt
        size: 627
        version: 0
        source: localComputer
        ownedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        uploadedOn: '2023-09-12T20:59:47.694353Z'
        isPrivate: false
        status: active
        createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        createdOn: '2023-09-12T20:59:47.694353Z'
        updatedOn: '2023-09-12T20:59:47.694353Z'
    User:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the user within the organization
          example: string
        type:
          type: string
          description: Type of Hyperproof user
          enum:
            - activeUser
            - deactivatedUser
            - contact
            - serviceAccount
            - deactivatedServiceAccount syncServiceAccount
            - deactivatedSyncServiceAccount
        userId:
          type: string
          description: Unique identifier for the user across all Hyperproof organizations
        email:
          type: string
          description: The email address of the user
        givenName:
          type: string
          description: The given name of the user
        surname:
          type: string
          description: The surname of the user
        language:
          type: string
          description: The language of the user
        locale:
          type: string
          description: The locale of the user
        timeZone:
          type: string
          description: The time zone of the user
        title:
          type: string
          description: The title of the user
        status:
          type: string
          description: The status of the user
          enum:
            - active
            - archived
            - deleted
            - pending
            - canceled
      example:
        id: d2363cab-5199-11ee-a644-522476618ae8
        type: activeUser
        userId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        email: jane.doe@example.com
        givenName: Jane
        surname: Doe
        language: en
        locale: US
        timeZone: America/Los_Angeles
        status: active
