# Get Controls

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


---

Endpoint: GET /
Version: 1.0.0
Security: oauth2

## Query parameters:

  - `canLink` (string)
    If true, only returns controls to which the requesting user has link permission

  - `expandScopes` (string)
    If true, includes scope controls as well as parent controls

  - `expandTeams` (string)
    If true, includes team controls as well as parent controls

  - `status` (string)
    Filters results by the provided object status

## 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