Skip to content
Hyperproof API
/
/
Controls API

Controls API (1.0.0)

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.

Download OpenAPI description
controls.openapi.json
controls.openapi.yaml
Languages
Servers
Mock server
https://developer.hyperproof.app/_mock/hyperproof-api/controls/controls.openapi
Hyperproof US
https://api.hyperproof.app/v1/controls
Hyperproof Gov
https://api.hyperproofgov.app/v1/controls
Hyperproof EU
https://api.hyperproof.eu/v1/controls

Get Controls

Request

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.
GET https://api.hyperproof.app/v1/controls?expandscopes=true
Security
oauth2
Query
canLinkstring

If true, only returns controls to which the requesting user has link permission

expandScopesstring

If true, includes scope controls as well as parent controls

expandTeamsstring

If true, includes team controls as well as parent controls

statusstring

Filters results by the provided object status

curl -i -X GET \
  'https://developer.hyperproof.app/_mock/hyperproof-api/controls/controls.openapi/?canLink=string&expandScopes=string&expandTeams=string&status=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success.

Bodyapplication/jsonArray [
idstring

The unique identifier for the control

Example: "d88d505d-5199-11ee-a644-522476618ae8"
orgIdstring

The unique identifier for the organization

Example: "ce83e3cd-5199-11ee-a644-522476618ae8"
controlTypestring

Type of control

Enum"simple""parent""scopeAssignment"
Example: "scopeAssignment"
controlIdentifierstring

The human readable unique identifier for the control within the organization

Example: "SOC2-P4.1.1_Legal"
namestring

The name of the control

Example: "Include in the privacy notice the use of collected personal information"
scopeNamestring

Name of the scope associated with the control populated if the 'controlType' is 'scopeAssignment'

Example: "Legal"
descriptionstring

The description of the control

Example: "The privacy notice identifies the use of collected personal information."
notesstring

Additional notes about the control

domainIdstring

The unique identifier of the domain

Example: "d7cf0a26-5199-11ee-a644-522476618ae8"
domainNamestring

The name of the domain

Example: "Privacy"
freshnessPolicystring(FreshnessPolicy)

The freshness policy of an object. Set to 'manual' with a 'freshAsOfDate' value otherwise 'freshness' will be set to 'unknown'.

Enum"none""manual"
freshForDurationstring

The duration after which control becomes stale

Example: "PT720H"
freshnessstring(Freshness)

The freshness status of an object. Cannot be set if 'freshnessPolicy' is 'none' and 'freshAsOfDate' is null.

Enum"noFreshness""fresh""expired""unknown"
freshAsOfDatestring

The date when freshness was last marked 'fresh'

Example: "2025-01-12T18:26:10.00.5365Z"
freshAsOfNotestring

The note populated when the control was marked fresh

Example: "Initial freshness set"
implementationstring

Implementation status

Enum"unknown""notStarted""inProgress""completed"
Example: "inProgress"
testingStatusstring

Testing status

Enum"notTested""inProgress""effective""ineffective"
Example: "effective"
testingDeficiencyArray of strings

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 Enum"design""operation"
Example: []
computeTestingStatusboolean

Whether testing status is computed automatically

automationstring

Determines whether this control can be automated and its current status

Enum"notStarted""partial""fullyAutomated""cantAutomate"
Example: "partial"
healthstring

Whether the health status is available and its current status

Enum"critical""atRisk""healthy""notAvailable"
Example: "notAvailable"
overrideHealthboolean

Whether health status is overridden

ownerobject(User)
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"}
groupIdstring

The unique identifier of the group assigned to the control

customFieldsArray of objects(CustomFieldObjectValue)
Example: [{"fieldId":"ceb912ab-519b-11ee-a644-522476618ae8","fieldName":"Sponsor","fieldType":"text","textValue":"John Smith"}]
statusstring(ObjectStatus)

The status of the object

Enum"active""archived"
createdBystring

The unique identifier of the user who created the control

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
createdOnstring

The date the control was created (ISO-8601 format)

Example: "2023-09-12T18:26:10.005365Z"
updatedBystring

The unique identifier of the user who last updated the control

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
updatedOnstring

The date the control was updated (ISO-8601 format)

Example: "2023-09-12T18:26:10.005365Z"
permissionsArray of strings

List of permissions the API user has on the control

Example: []
_isPartialDataboolean

This is true when the user does not have read permissions on the control

teamNamestringDeprecated

This field is deprecated and will be removed in a future version. Use scopeName instead

]
Response
application/json
[
  {
    "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": { … },
    "customFields": [ … ],
    "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": []
  }
]

Add Control

Request

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.

POST https://api.hyperproof.app/v1/controls
Content-Type: application/json
{
"name": "New Control Name",
"scopeId": "desiredScopeId",
...other control properties...
}
Security
oauth2
Bodyapplication/json
controlIdentifierstringrequired

Unique identifier for the control within the organization

Example: "SOC2-P4.1.1"
namestring

Name of the control

Example: "Include in the privacy notice the use of collected personal information"
scopeIdstring

Unique identifier of the scope associated with the control

descriptionstringrequired

Description of the control

Example: "The privacy notice identifies the use of collected personal information."
notesstring

Additional notes about the control

domainNamestring

Name of the domain

Example: "Privacy"
implementationstring

Implementation status

Enum"unknown""notStarted""inProgress""completed"
Example: "inProgress"
testingStatusstring

Testing status

Enum"notTested""inProgress""effective""ineffective"
automationstring

Automation status

Enum"notStarted""partial""fullyAutomated""cantAutomate"
ownerstringrequired

The unique identifier of the user who owns the control

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
groupIdstring

The unique identifier of the group assigned to the control

customFieldsArray of objects(CustomFieldObjectValuePatch)
externalObjectIdsArray of strings or null
teamIdstringDeprecated

This field is deprecated and will be removed in a future version. Use scopeId instead

curl -i -X POST \
  https://developer.hyperproof.app/_mock/hyperproof-api/controls/controls.openapi/ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "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

Success.

Bodyapplication/json
idstring

The unique identifier for the control

Example: "d88d505d-5199-11ee-a644-522476618ae8"
orgIdstring

The unique identifier for the organization

Example: "ce83e3cd-5199-11ee-a644-522476618ae8"
controlTypestring

Type of control

Enum"simple""parent""scopeAssignment"
Example: "scopeAssignment"
controlIdentifierstring

The human readable unique identifier for the control within the organization

Example: "SOC2-P4.1.1_Legal"
namestring

The name of the control

Example: "Include in the privacy notice the use of collected personal information"
scopeNamestring

Name of the scope associated with the control populated if the 'controlType' is 'scopeAssignment'

Example: "Legal"
descriptionstring

The description of the control

Example: "The privacy notice identifies the use of collected personal information."
notesstring

Additional notes about the control

domainIdstring

The unique identifier of the domain

Example: "d7cf0a26-5199-11ee-a644-522476618ae8"
domainNamestring

The name of the domain

Example: "Privacy"
freshnessPolicystring(FreshnessPolicy)

The freshness policy of an object. Set to 'manual' with a 'freshAsOfDate' value otherwise 'freshness' will be set to 'unknown'.

Enum"none""manual"
freshForDurationstring

The duration after which control becomes stale

Example: "PT720H"
freshnessstring(Freshness)

The freshness status of an object. Cannot be set if 'freshnessPolicy' is 'none' and 'freshAsOfDate' is null.

Enum"noFreshness""fresh""expired""unknown"
freshAsOfDatestring

The date when freshness was last marked 'fresh'

Example: "2025-01-12T18:26:10.00.5365Z"
freshAsOfNotestring

The note populated when the control was marked fresh

Example: "Initial freshness set"
implementationstring

Implementation status

Enum"unknown""notStarted""inProgress""completed"
Example: "inProgress"
testingStatusstring

Testing status

Enum"notTested""inProgress""effective""ineffective"
Example: "effective"
testingDeficiencyArray of strings

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 Enum"design""operation"
Example: []
computeTestingStatusboolean

Whether testing status is computed automatically

automationstring

Determines whether this control can be automated and its current status

Enum"notStarted""partial""fullyAutomated""cantAutomate"
Example: "partial"
healthstring

Whether the health status is available and its current status

Enum"critical""atRisk""healthy""notAvailable"
Example: "notAvailable"
overrideHealthboolean

Whether health status is overridden

ownerobject(User)
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"}
groupIdstring

The unique identifier of the group assigned to the control

customFieldsArray of objects(CustomFieldObjectValue)
Example: [{"fieldId":"ceb912ab-519b-11ee-a644-522476618ae8","fieldName":"Sponsor","fieldType":"text","textValue":"John Smith"}]
statusstring(ObjectStatus)

The status of the object

Enum"active""archived"
createdBystring

The unique identifier of the user who created the control

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
createdOnstring

The date the control was created (ISO-8601 format)

Example: "2023-09-12T18:26:10.005365Z"
updatedBystring

The unique identifier of the user who last updated the control

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
updatedOnstring

The date the control was updated (ISO-8601 format)

Example: "2023-09-12T18:26:10.005365Z"
permissionsArray of strings

List of permissions the API user has on the control

Example: []
_isPartialDataboolean

This is true when the user does not have read permissions on the control

teamNamestringDeprecated

This field is deprecated and will be removed in a future version. Use scopeName instead

Response
application/json
{
  "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": []
}

Add Control Proof

Request

POST /{controlId}/proof

Description

Uploads a proof item (e.g. a file) to associate with a specific control.

Security
oauth2
Path
controlIdstringrequired

Unique ID of the control.

Bodymultipart/form-data
curl -i -X POST \
  'https://developer.hyperproof.app/_mock/hyperproof-api/controls/controls.openapi/{controlId}/proof' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: multipart/form-data'

Responses

Success.

Bodyapplication/json
idstring

Unique identifier for the proof item

Example: "4eb909de-51af-11ee-a644-522476618ae8"
orgIdstring

Unique identifier for the organization

Example: "ce83e3cd-5199-11ee-a644-522476618ae8"
filenamestring

Name of the uploaded file

Example: "example.txt"
nameOverridestring

Name of proof Hyperproof given by Hyperproof user

contentTypestring

MIME type of the file (e.g.,text/plain)

Example: "text/plain"
fileExtensionstring

File extension (e.g.,txt)

Example: "txt"
sizenumber

File size in bytes

Example: 627
versioninteger

Version of the proof item

sourcestring

Source of the file (e.g.,localComputer)

Example: "localComputer"
sourceVersioninteger

The version of the proof maintained by the source system

ownedBystring

Unique identifier of the user who owns the proof item

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
isPrivateboolean

Whether the proof item is private

uploadedOnstring

The date the proof was uploaded (ISO-8601 format)

Example: "2023-09-12T20:59:47.694353Z"
statusstring

Status of the proof item

Enum"active""archived""deleted""pending""canceled"
Example: "active"
createdBystring

Unique identifier of the user who created the proof item

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
createdOnstring

The date the proof was created (ISO-8601 format)

Example: "2023-09-12T20:59:47.694353Z"
updatedBystring

Unique identifier of the user who last updated the proof item

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
updatedOnstring

The date the proof was updated (ISO-8601 format)

Example: "2023-09-12T20:59:47.694353Z"
Response
application/json
{
  "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"
}

Get Controls Filtered

Request

PUT /filter

Description

Fetches controls matching a provided filter, such as a list of control IDs.

Security
oauth2
Bodyapplication/json
controlIdsArray of strings
Example: ["23b806db-bad2-4f7a-b8d1-ac1177909992","23b402db-bad2-4f7a-b8d1-ac1177909992"]
curl -i -X PUT \
  https://developer.hyperproof.app/_mock/hyperproof-api/controls/controls.openapi/filter \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "controlIds": [
      "23b806db-bad2-4f7a-b8d1-ac1177909992",
      "23b402db-bad2-4f7a-b8d1-ac1177909992"
    ]
  }'

Responses

Success.

Bodyapplication/jsonArray [
idstring

The unique identifier for the control

Example: "d88d505d-5199-11ee-a644-522476618ae8"
orgIdstring

The unique identifier for the organization

Example: "ce83e3cd-5199-11ee-a644-522476618ae8"
controlTypestring

Type of control

Enum"simple""parent""scopeAssignment"
Example: "scopeAssignment"
controlIdentifierstring

The human readable unique identifier for the control within the organization

Example: "SOC2-P4.1.1_Legal"
namestring

The name of the control

Example: "Include in the privacy notice the use of collected personal information"
scopeNamestring

Name of the scope associated with the control populated if the 'controlType' is 'scopeAssignment'

Example: "Legal"
descriptionstring

The description of the control

Example: "The privacy notice identifies the use of collected personal information."
notesstring

Additional notes about the control

domainIdstring

The unique identifier of the domain

Example: "d7cf0a26-5199-11ee-a644-522476618ae8"
domainNamestring

The name of the domain

Example: "Privacy"
freshnessPolicystring(FreshnessPolicy)

The freshness policy of an object. Set to 'manual' with a 'freshAsOfDate' value otherwise 'freshness' will be set to 'unknown'.

Enum"none""manual"
freshForDurationstring

The duration after which control becomes stale

Example: "PT720H"
freshnessstring(Freshness)

The freshness status of an object. Cannot be set if 'freshnessPolicy' is 'none' and 'freshAsOfDate' is null.

Enum"noFreshness""fresh""expired""unknown"
freshAsOfDatestring

The date when freshness was last marked 'fresh'

Example: "2025-01-12T18:26:10.00.5365Z"
freshAsOfNotestring

The note populated when the control was marked fresh

Example: "Initial freshness set"
implementationstring

Implementation status

Enum"unknown""notStarted""inProgress""completed"
Example: "inProgress"
testingStatusstring

Testing status

Enum"notTested""inProgress""effective""ineffective"
Example: "effective"
testingDeficiencyArray of strings

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 Enum"design""operation"
Example: []
computeTestingStatusboolean

Whether testing status is computed automatically

automationstring

Determines whether this control can be automated and its current status

Enum"notStarted""partial""fullyAutomated""cantAutomate"
Example: "partial"
healthstring

Whether the health status is available and its current status

Enum"critical""atRisk""healthy""notAvailable"
Example: "notAvailable"
overrideHealthboolean

Whether health status is overridden

ownerobject(User)
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"}
groupIdstring

The unique identifier of the group assigned to the control

customFieldsArray of objects(CustomFieldObjectValue)
Example: [{"fieldId":"ceb912ab-519b-11ee-a644-522476618ae8","fieldName":"Sponsor","fieldType":"text","textValue":"John Smith"}]
statusstring(ObjectStatus)

The status of the object

Enum"active""archived"
createdBystring

The unique identifier of the user who created the control

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
createdOnstring

The date the control was created (ISO-8601 format)

Example: "2023-09-12T18:26:10.005365Z"
updatedBystring

The unique identifier of the user who last updated the control

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
updatedOnstring

The date the control was updated (ISO-8601 format)

Example: "2023-09-12T18:26:10.005365Z"
permissionsArray of strings

List of permissions the API user has on the control

Example: []
_isPartialDataboolean

This is true when the user does not have read permissions on the control

teamNamestringDeprecated

This field is deprecated and will be removed in a future version. Use scopeName instead

]
Response
application/json
[
  {
    "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": { … },
    "customFields": [ … ],
    "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": []
  }
]

Get Control Summaries

Request

GET /summaries

Description

Fetches a summarized list of controls, including their IDs, identifiers, names, and timestamps.

Security
oauth2
Query
canLinkstring

If true, only returns control summaries the requesting user has link permission for

statusstring

Filters results by the provided object status

curl -i -X GET \
  'https://developer.hyperproof.app/_mock/hyperproof-api/controls/controls.openapi/summaries?canLink=string&status=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success.

Bodyapplication/jsonArray [
idstring

Unique identifier for the control

controlIdentifierstring

Human readable unique identifier for the control within the organization

namestring

Name of the control

createdOnstring

The date the control was created (ISO-8601 format)

updatedOnstring

The date the control was last updated (ISO-8601 format)

]
Response
application/json
[
  {
    "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"
  }
]

Get Control

Request

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.
GET https://api.hyperproof.app/v1/controls/{controlId}?expandscopes=true
Security
oauth2
Path
controlIdstringrequired

Unique ID of the control to retrieve.

curl -i -X GET \
  'https://developer.hyperproof.app/_mock/hyperproof-api/controls/controls.openapi/{controlId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success.

Bodyapplication/json
idstring

The unique identifier for the control

Example: "d88d505d-5199-11ee-a644-522476618ae8"
orgIdstring

The unique identifier for the organization

Example: "ce83e3cd-5199-11ee-a644-522476618ae8"
controlTypestring

Type of control

Enum"simple""parent""scopeAssignment"
Example: "scopeAssignment"
controlIdentifierstring

The human readable unique identifier for the control within the organization

Example: "SOC2-P4.1.1_Legal"
namestring

The name of the control

Example: "Include in the privacy notice the use of collected personal information"
scopeNamestring

Name of the scope associated with the control populated if the 'controlType' is 'scopeAssignment'

Example: "Legal"
descriptionstring

The description of the control

Example: "The privacy notice identifies the use of collected personal information."
notesstring

Additional notes about the control

domainIdstring

The unique identifier of the domain

Example: "d7cf0a26-5199-11ee-a644-522476618ae8"
domainNamestring

The name of the domain

Example: "Privacy"
freshnessPolicystring(FreshnessPolicy)

The freshness policy of an object. Set to 'manual' with a 'freshAsOfDate' value otherwise 'freshness' will be set to 'unknown'.

Enum"none""manual"
freshForDurationstring

The duration after which control becomes stale

Example: "PT720H"
freshnessstring(Freshness)

The freshness status of an object. Cannot be set if 'freshnessPolicy' is 'none' and 'freshAsOfDate' is null.

Enum"noFreshness""fresh""expired""unknown"
freshAsOfDatestring

The date when freshness was last marked 'fresh'

Example: "2025-01-12T18:26:10.00.5365Z"
freshAsOfNotestring

The note populated when the control was marked fresh

Example: "Initial freshness set"
implementationstring

Implementation status

Enum"unknown""notStarted""inProgress""completed"
Example: "inProgress"
testingStatusstring

Testing status

Enum"notTested""inProgress""effective""ineffective"
Example: "effective"
testingDeficiencyArray of strings

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 Enum"design""operation"
Example: []
computeTestingStatusboolean

Whether testing status is computed automatically

automationstring

Determines whether this control can be automated and its current status

Enum"notStarted""partial""fullyAutomated""cantAutomate"
Example: "partial"
healthstring

Whether the health status is available and its current status

Enum"critical""atRisk""healthy""notAvailable"
Example: "notAvailable"
overrideHealthboolean

Whether health status is overridden

ownerobject(User)
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"}
groupIdstring

The unique identifier of the group assigned to the control

customFieldsArray of objects(CustomFieldObjectValue)
Example: [{"fieldId":"ceb912ab-519b-11ee-a644-522476618ae8","fieldName":"Sponsor","fieldType":"text","textValue":"John Smith"}]
statusstring(ObjectStatus)

The status of the object

Enum"active""archived"
createdBystring

The unique identifier of the user who created the control

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
createdOnstring

The date the control was created (ISO-8601 format)

Example: "2023-09-12T18:26:10.005365Z"
updatedBystring

The unique identifier of the user who last updated the control

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
updatedOnstring

The date the control was updated (ISO-8601 format)

Example: "2023-09-12T18:26:10.005365Z"
permissionsArray of strings

List of permissions the API user has on the control

Example: []
_isPartialDataboolean

This is true when the user does not have read permissions on the control

teamNamestringDeprecated

This field is deprecated and will be removed in a future version. Use scopeName instead

Response
application/json
{
  "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"
}

Update Control

Request

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.
PATCH https://api.hyperproof.app/v1/controls/{controlId}  
Content-Type: application/json  
{  
"scopeId": "desiredScopeId"  
}
Security
oauth2
Path
controlIdstringrequired

Unique ID of the control to update.

Bodyapplication/json
controlIdentifierstring

The unique identifier for the control within the organization

namestring

Name of the control

Example: "Include in the privacy notice the use of collected personal information"
scopeIdstring

Unique identifier of the scope associated with the control

descriptionstring

Description of the control

Example: "The privacy notice identifies the use of collected personal information."
notesstring

Additional notes about the control

Example: "Meet quarterly to review"
domainIdstring

Identifier of the domain

domainNamestring

Name of the domain

clearDomainboolean

Clears the domain association if true

freshnessPolicystring(FreshnessPolicy)

The freshness policy of an object. Set to 'manual' with a 'freshAsOfDate' value otherwise 'freshness' will be set to 'unknown'.

Enum"none""manual"
freshForDurationstring

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"
freshnessstring(Freshness)

The freshness status of an object. Cannot be set if 'freshnessPolicy' is 'none' and 'freshAsOfDate' is null.

Enum"noFreshness""fresh""expired""unknown"
freshAsOfDatestring

The date when freshness was last marked 'fresh'

Example: "2025-01-12T18:26:10.00.5365Z"
freshAsOfNotestring

The note to populate when the control is marked 'fresh'

Example: "Updating expired control freshness"
resetFreshnessNotestring

The note to populate when freshness is reset

implementationstring

Implementation status

Enum"unknown""notStarted""inProgress""completed"
Example: "inProgress"
testingStatusstring

Testing status

Enum"notTested""inProgress""effective""ineffective"
Example: "effective"
testingDeficiencyArray of strings

List of deficiencies

Items Enum"design""operation"
automationstring

Automation status

Enum"notStarted""partial""fullyAutomated""cantAutomate"
healthstring

Health status

Enum"critical""atRisk""healthy""notAvailable"
overrideHealthboolean

Whether health status is overridden

overrideHealthOnstring

The date when health was overridden

overrideHealthReasonstring

Reason for overriding health status

computeTestingStatusboolean

Whether testing status is computed automatically

ownerstring

The unique identifier of the user who owns the control

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
customFieldsArray of objects(CustomFieldObjectValuePatch)
Example: [{"fieldId":"ceb912ab-519b-11ee-a644-522476618ae8","textValue":"Antonio Moreno"}]
statusstring(ObjectStatus)

The status of the object

Enum"active""archived"
groupIdstring

The unique identifier of the group assigned to the control. If set, clearGroupId must not be set.

clearGroupIdboolean

Clears the group Unique identifier if true. If set, groupId must not be set.

teamIdstringDeprecated

This field is deprecated and will be removed in a future version. Use scopeId instead

curl -i -X PATCH \
  'https://developer.hyperproof.app/_mock/hyperproof-api/controls/controls.openapi/{controlId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "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

Success.

Bodyapplication/json
idstring

The unique identifier for the control

Example: "d88d505d-5199-11ee-a644-522476618ae8"
orgIdstring

The unique identifier for the organization

Example: "ce83e3cd-5199-11ee-a644-522476618ae8"
controlTypestring

Type of control

Enum"simple""parent""scopeAssignment"
Example: "scopeAssignment"
controlIdentifierstring

The human readable unique identifier for the control within the organization

Example: "SOC2-P4.1.1_Legal"
namestring

The name of the control

Example: "Include in the privacy notice the use of collected personal information"
scopeNamestring

Name of the scope associated with the control populated if the 'controlType' is 'scopeAssignment'

Example: "Legal"
descriptionstring

The description of the control

Example: "The privacy notice identifies the use of collected personal information."
notesstring

Additional notes about the control

domainIdstring

The unique identifier of the domain

Example: "d7cf0a26-5199-11ee-a644-522476618ae8"
domainNamestring

The name of the domain

Example: "Privacy"
freshnessPolicystring(FreshnessPolicy)

The freshness policy of an object. Set to 'manual' with a 'freshAsOfDate' value otherwise 'freshness' will be set to 'unknown'.

Enum"none""manual"
freshForDurationstring

The duration after which control becomes stale

Example: "PT720H"
freshnessstring(Freshness)

The freshness status of an object. Cannot be set if 'freshnessPolicy' is 'none' and 'freshAsOfDate' is null.

Enum"noFreshness""fresh""expired""unknown"
freshAsOfDatestring

The date when freshness was last marked 'fresh'

Example: "2025-01-12T18:26:10.00.5365Z"
freshAsOfNotestring

The note populated when the control was marked fresh

Example: "Initial freshness set"
implementationstring

Implementation status

Enum"unknown""notStarted""inProgress""completed"
Example: "inProgress"
testingStatusstring

Testing status

Enum"notTested""inProgress""effective""ineffective"
Example: "effective"
testingDeficiencyArray of strings

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 Enum"design""operation"
Example: []
computeTestingStatusboolean

Whether testing status is computed automatically

automationstring

Determines whether this control can be automated and its current status

Enum"notStarted""partial""fullyAutomated""cantAutomate"
Example: "partial"
healthstring

Whether the health status is available and its current status

Enum"critical""atRisk""healthy""notAvailable"
Example: "notAvailable"
overrideHealthboolean

Whether health status is overridden

ownerobject(User)
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"}
groupIdstring

The unique identifier of the group assigned to the control

customFieldsArray of objects(CustomFieldObjectValue)
Example: [{"fieldId":"ceb912ab-519b-11ee-a644-522476618ae8","fieldName":"Sponsor","fieldType":"text","textValue":"John Smith"}]
statusstring(ObjectStatus)

The status of the object

Enum"active""archived"
createdBystring

The unique identifier of the user who created the control

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
createdOnstring

The date the control was created (ISO-8601 format)

Example: "2023-09-12T18:26:10.005365Z"
updatedBystring

The unique identifier of the user who last updated the control

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
updatedOnstring

The date the control was updated (ISO-8601 format)

Example: "2023-09-12T18:26:10.005365Z"
permissionsArray of strings

List of permissions the API user has on the control

Example: []
_isPartialDataboolean

This is true when the user does not have read permissions on the control

teamNamestringDeprecated

This field is deprecated and will be removed in a future version. Use scopeName instead

Response
application/json
{
  "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": [
    { … }
  ],
  "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": []
}
® 2026 Hyperproof All Rights Reserved.