# Update Control

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"  
}

Endpoint: PATCH /{controlId}
Version: 1.0.0
Security: oauth2

## Path parameters:

  - `controlId` (string, required)
    Unique ID of the control to update.

## Request fields (application/json):

  - `controlIdentifier` (string)
    The unique identifier for the control within the organization

  - `name` (string)
    Name of the control
    Example: "Include in the privacy notice the use of collected personal information"

  - `scopeId` (string)
    Unique identifier of the scope associated with the control

  - `description` (string)
    Description of the control
    Example: "The privacy notice identifies the use of collected personal information."

  - `notes` (string)
    Additional notes about the control
    Example: "Meet quarterly to review"

  - `domainId` (string)
    Identifier of the domain

  - `domainName` (string)
    Name of the domain

  - `clearDomain` (boolean)
    Clears the domain association if true

  - `freshnessPolicy` (string)
    The freshness policy of an object. Set to 'manual' with a 'freshAsOfDate' value otherwise 'freshness' will be set to 'unknown'.
    Enum: "none", "manual"

  - `freshForDuration` (string)
    Sets the duration after which the control becomes stale. Supply as a string in standard ISO-8601 duration format ex: P1Y3M2D or PT720H
    Example: "PT720H"

  - `freshness` (string)
    The freshness status of an object. Cannot be set if 'freshnessPolicy' is 'none' and 'freshAsOfDate' is null.
    Enum: "noFreshness", "fresh", "expired", "unknown"

  - `freshAsOfDate` (string)
    The date when freshness was last marked 'fresh'
    Example: "2025-01-12T18:26:10.00.5365Z"

  - `freshAsOfNote` (string)
    The note to populate when the control is marked 'fresh'
    Example: "Updating expired control freshness"

  - `resetFreshnessNote` (string)
    The note to populate when freshness is reset

  - `implementation` (string)
    Implementation status
    Enum: "unknown", "notStarted", "inProgress", "completed"

  - `testingStatus` (string)
    Testing status
    Enum: "notTested", "inProgress", "effective", "ineffective"

  - `testingDeficiency` (array)
    List of deficiencies
    Enum: "design", "operation"

  - `automation` (string)
    Automation status
    Enum: "notStarted", "partial", "fullyAutomated", "cantAutomate"

  - `health` (string)
    Health status
    Enum: "critical", "atRisk", "healthy", "notAvailable"

  - `overrideHealth` (boolean)
    Whether health status is overridden

  - `overrideHealthOn` (string)
    The date when health was overridden

  - `overrideHealthReason` (string)
    Reason for overriding health status

  - `computeTestingStatus` (boolean)
    Whether testing status is computed automatically

  - `owner` (string)
    The unique identifier of the user who owns the control
    Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"

  - `customFields` (array)
    Example: [{"fieldId":"ceb912ab-519b-11ee-a644-522476618ae8","textValue":"Antonio Moreno"}]

  - `customFields.fieldId` (string)
    Unique identifier for the custom field

  - `customFields.textValue` (string)
    Value if the field type is text

  - `customFields.numberValue` (number)
    Value if the field type is number

  - `customFields.dateValue` (string)
    Value if the field type is date

  - `customFields.userValue` (string)
    Value if the field type is user

  - `customFields.selections` (array)
    List of values for textMultiSelect

  - `status` (string)
    The status of the object
    Enum: "active", "archived"

  - `groupId` (string)
    The unique identifier of the group assigned to the control. If set, clearGroupId must not be set.

  - `clearGroupId` (boolean)
    Clears the group Unique identifier if true. If set, groupId must not be set.

  - `teamId` (string)
    This field is deprecated and will be removed in a future version. Use scopeId instead

## Response 200 fields (application/json):

  - `id` (string)
    The unique identifier for the control
    Example: "d88d505d-5199-11ee-a644-522476618ae8"

  - `orgId` (string)
    The unique identifier for the organization
    Example: "ce83e3cd-5199-11ee-a644-522476618ae8"

  - `controlType` (string)
    Type of control
    Enum: "simple", "parent", "scopeAssignment"

  - `controlIdentifier` (string)
    The human readable unique identifier for the control within the organization
    Example: "SOC2-P4.1.1_Legal"

  - `name` (string)
    The name of the control
    Example: "Include in the privacy notice the use of collected personal information"

  - `scopeName` (string)
    Name of the scope associated with the control populated if the 'controlType' is 'scopeAssignment'
    Example: "Legal"

  - `description` (string)
    The description of the control
    Example: "The privacy notice identifies the use of collected personal information."

  - `notes` (string)
    Additional notes about the control

  - `domainId` (string)
    The unique identifier of the domain
    Example: "d7cf0a26-5199-11ee-a644-522476618ae8"

  - `domainName` (string)
    The name of the domain
    Example: "Privacy"

  - `freshnessPolicy` (string)
    The freshness policy of an object. Set to 'manual' with a 'freshAsOfDate' value otherwise 'freshness' will be set to 'unknown'.
    Enum: "none", "manual"

  - `freshForDuration` (string)
    The duration after which control becomes stale
    Example: "PT720H"

  - `freshness` (string)
    The freshness status of an object. Cannot be set if 'freshnessPolicy' is 'none' and 'freshAsOfDate' is null.
    Enum: "noFreshness", "fresh", "expired", "unknown"

  - `freshAsOfDate` (string)
    The date when freshness was last marked 'fresh'
    Example: "2025-01-12T18:26:10.00.5365Z"

  - `freshAsOfNote` (string)
    The note populated when the control was marked fresh
    Example: "Initial freshness set"

  - `implementation` (string)
    Implementation status
    Enum: "unknown", "notStarted", "inProgress", "completed"

  - `testingStatus` (string)
    Testing status
    Enum: "notTested", "inProgress", "effective", "ineffective"

  - `testingDeficiency` (array)
    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.
    Enum: "design", "operation"

  - `computeTestingStatus` (boolean)
    Whether testing status is computed automatically

  - `automation` (string)
    Determines whether this control can be automated and its current status
    Enum: "notStarted", "partial", "fullyAutomated", "cantAutomate"

  - `health` (string)
    Whether the health status is available and its current status
    Enum: "critical", "atRisk", "healthy", "notAvailable"

  - `overrideHealth` (boolean)
    Whether health status is overridden

  - `owner` (object)
    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"}

  - `owner.id` (string)
    Unique identifier for the user within the organization
    Example: "d2363cab-5199-11ee-a644-522476618ae8"

  - `owner.type` (string)
    Type of Hyperproof user
    Enum: "activeUser", "deactivatedUser", "contact", "serviceAccount", "deactivatedServiceAccount syncServiceAccount", "deactivatedSyncServiceAccount"

  - `owner.userId` (string)
    Unique identifier for the user across all Hyperproof organizations
    Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"

  - `owner.email` (string)
    The email address of the user
    Example: "jane.doe@example.com"

  - `owner.givenName` (string)
    The given name of the user
    Example: "Jane"

  - `owner.surname` (string)
    The surname of the user
    Example: "Doe"

  - `owner.language` (string)
    The language of the user
    Example: "en"

  - `owner.locale` (string)
    The locale of the user
    Example: "US"

  - `owner.timeZone` (string)
    The time zone of the user
    Example: "America/Los_Angeles"

  - `owner.title` (string)
    The title of the user

  - `owner.status` (string)
    The status of the user
    Enum: "active", "archived", "deleted", "pending", "canceled"

  - `groupId` (string)
    The unique identifier of the group assigned to the control

  - `customFields` (array)
    Example: [{"fieldId":"ceb912ab-519b-11ee-a644-522476618ae8","fieldName":"Sponsor","fieldType":"text","textValue":"John Smith"}]

  - `customFields.fieldId` (string)
    Unique identifier for the custom field

  - `customFields.fieldName` (string)
    Name of the custom field

  - `customFields.fieldType` (string)
    Type of field
    Enum: "text", "number", "date", "user", "textSingleSelect", "textMultiSelect"

  - `customFields.numberFormat` (string)
    Format if the field type is number
    Enum: "decimal", "percentage"

  - `customFields.textValue` (string)
    Value if the field type is text

  - `customFields.numberValue` (number)
    Value if the field type is number

  - `customFields.dateValue` (string)
    Value if the field type is date

  - `customFields.userValue` (string)
    Value if the field type is user

  - `customFields.selection` (string)
    Value for textSingleSelect

  - `customFields.selections` (array)
    List of values for textMultiSelect

  - `status` (string)
    The status of the object
    Enum: "active", "archived"

  - `createdBy` (string)
    The unique identifier of the user who created the control
    Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"

  - `createdOn` (string)
    The date the control was created (ISO-8601 format)
    Example: "2023-09-12T18:26:10.005365Z"

  - `updatedBy` (string)
    The unique identifier of the user who last updated the control
    Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"

  - `updatedOn` (string)
    The date the control was updated (ISO-8601 format)
    Example: "2023-09-12T18:26:10.005365Z"

  - `permissions` (array)
    List of permissions the API user has on the control
    Example: []

  - `_isPartialData` (boolean)
    This is true when the user does not have read permissions on the control

  - `teamName` (string)
    This field is deprecated and will be removed in a future version. Use scopeName instead