# Get Risks Filtered

PUT /risks/filter

#### Description

Retrieves a list of risks that match the specified filter criteria, such as category, status, likelihood, or owner.

Endpoint: PUT /filter
Version: 1.0
Security: oauth2

## Query parameters:

  - `expand` (string)
    Comma separated list of fields to expand. Supported values: linkedControls.

## Request fields (application/json):

  - `riskIds` (array)
    List of unique identifiers for risks to return
    Example: ["23b806db-bad2-4f7a-b8d1-ac1177909992","23b402db-bad2-4f7a-b8d1-ac1177909992"]

  - `modifiedAfter` (string)
    Return only risks modified after this date (ISO-8601 format)
    Example: "2020-12-17T20:00:00Z"

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

  - `riskStage` (string)
    The current stage of the risk
    Enum: "proposed", "evaluating", "approved", "operating"

## Response 200 fields (application/json):

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

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

  - `riskIdentifier` (string)
    Human readable unique identifier for the risk within the organization
    Example: "FGSC-RA1"

  - `riskRegisterId` (string)
    The unique identifier for the risk register which the risk belongs to
    Example: "9f25da4f-1532-11ee-a87d-8e36b9d27de7"

  - `name` (string)
    Name of the risk
    Example: "Free Gas Safety Checks not provided in a complete and timely manner"

  - `description` (string)
    Description of the risk
    Example: "Requests from eligible customers for a Free Gas Safety Check are not actioned in an appropriate timescale leading to poor customer service, the potential for safety issues and non compliance with our SLCs."

  - `category` (string)
    Category of the risk
    Example: "Controls Program - Customer Operations"

  - `health` (string)
    Current health status of the risk
    Enum: "healthy", "atRisk", "critical"

  - `response` (string)
    The response to the risk
    Enum: "mitigate", "accept", "transfer", "avoid", "notSet"

  - `responseRationale` (string)
    Reasoning for the selected risk response
    Example: "accepted"

  - `riskStage` (string)
    The current stage of the risk
    Enum: "proposed", "evaluating", "approved", "operating"

  - `notes` (string)
    Additional notes about the risk
    Example: "Reviewed by our internal team"

  - `ownerId` (string)
    The unique identifier for the user who is the owner of the risk
    Example: "ce83e3cd-5199-11ee-a644-522476618aek"

  - `groupId` (string)
    The unique identifier of the group assigned to the risk
    Example: "d2363cab-5199-11ee-a644-522476618ae8"

  - `riskReporterId` (string)
    The unique identifier for the hyperproof user or external contact who reported the risk
    Example: "ce83e3cd-5484-11ee-12b6-522476618ae9"

  - `riskReporterType` (string)
    The type of person who reported the risk
    Enum: "user", "externalContact"

  - `likelihoodLevel` (integer)
    The inherent likelihood level of the risk. Index notation (0-based)
    Example: 1

  - `likelihoodValue` (integer)
    The user-assigned value for the inherent likelihood scale for the risk, determined from likelihoodLevel and customRiskScales
    Example: 2

  - `likelihoodRationale` (string)
    The reasoning for the inherent likelihood level of the risk
    Example: "security"

  - `impactLevel` (integer)
    The inherent impact level of the risk. Index notation (0-based)
    Example: 2

  - `impactRationale` (string)
    The reasoning for the inherent impact level of the risk
    Example: "cyber"

  - `impactValue` (integer)
    The user-assigned value of inherent impact scale for the risk, determined from impactLevel and customRiskScales
    Example: 5

  - `inherentRisk` (integer)
    The inherent risk value for the risk, calculated as likelihoodValue x impactValue
    Example: 10

  - `toleranceLevel` (integer)
    The tolerance level for the risk. Index notation (0-based)
    Example: 1

  - `actualRisk` (integer)
    The user-overridden residual risk value for the risk
    Example: 4

  - `overrideActualRisk` (boolean)
    Flag indicating whether the actual residual risk has been overridden from the calculated value
    Example: "false"

  - `overrideActualRiskReason` (string)
    The reasoning for overriding the residual risk
    Example: "low"

  - `overrideActualRiskBy` (string)
    The unique identifier of the user who overrode the residual risk
    Example: "ac57e976-69ab-11ed-b991-1284f382c88o"

  - `overrideActualRiskOn` (string)
    The date when the residual risk was overridden (ISO-8601 format)
    Example: "2023-08-10 20:27:32.890116+00"

  - `overrideResidualLikelihood` (boolean)
    Flag indicating whether the residual likelihood has been overridden from the calculated value
    Example: "false"

  - `residualLikelihoodLevel` (integer)
    The user-overridden residual likelihood level of the risk. Index notation (0-based)
    Example: 3

  - `overrideResidualLikelihoodBy` (string)
    The unique identifier of the user who overrode the residual likelihood
    Example: "ac57e976-69ab-12ab-b991-1284f382c88a"

  - `overrideResidualLikelihoodOn` (string)
    The date when the residual likelihood was overridden (ISO-8601 format)
    Example: "2023-08-10 20:27:32.890116+00"

  - `overrideResidualImpact` (boolean)
    Flag indicating whether the residual impact has been overridden from the calculated value
    Example: "true"

  - `residualImpactLevel` (integer)
    The user-overridden residual impact level of the risk. Index notation (0-based)
    Example: 2

  - `overrideResidualImpactBy` (string)
    The unique identifier of the user who overrode the residual impact
    Example: "ac57e976-69ab-11ed-b991-1284f382c88d"

  - `overrideResidualImpactOn` (string)
    The date when the residual impact was overridden (ISO-8601 format)
    Example: "2023-08-10 20:27:32.890116+00"

  - `actualLikelihood` (number)
    The residual likelihood value for the risk after applying the mitigation from linked controls and accounting for the controls' health to likelihoodValue. If overridden, calculated using residualLikelihoodLevel and customRiskScales
    Example: 8

  - `actualImpact` (number)
    The residual impact value for the risk after applying the mitigation from linked controls and accounting for the controls' health to impactValue. If overridden, calculated using residualImpactLevel and customRiskScales
    Example: 5

  - `desiredResidualRisk` (number)
    The calculated risk value after applying the mitigation from linked controls to the inherent risk value
    Example: 16

  - `calculatedActualResidualRisk` (number)
    The desiredResidualRisk accounting for the health of the mitigating controls
    Example: 15

  - `actualResidualRisk` (number)
    The calculatedActualResidualRisk value unless overridden by the actualRisk value
    Example: 12

  - `customRiskScales` (object)
    Custom risk scales defined for the risk register the risk belongs to
    Example: {"likelihood":[{"name":"Very Low","value":1,"color":"#EDF9F2"},{"name":"Low","value":2,"color":"#91D4BC"},{"name":"Moderate","value":5,"color":"#FFB75D"},{"name":"High","value":8,"color":"#FF8C00"},{"name":"Very High","value":10,"color":"#C2533B"}],"impact":[{"name":"Very Low","value":1,"color":"#EDF9F2"},{"name":"Low","value":2,"color":"#91D4BC"},{"name":"Moderate","value":5,"color":"#FFB75D"},{"name":"High","value":8,"color":"#FF8C00"},{"name":"Very High","value":10,"color":"#C2533B"}],"inherentRisk":[{"name":"Very Low","value":1,"color":"#EDF9F2","inherentRiskThreshold":1},{"name":"Low","value":2,"color":"#91D4BC","inherentRiskThreshold":10},{"name":"Moderate","value":5,"color":"#FFB75D","inherentRiskThreshold":40},{"name":"High","value":8,"color":"#FF8C00","inherentRiskThreshold":64},{"name":"Very High","value":10,"color":"#C2533B","inherentRiskThreshold":100}]}

  - `customRiskScales.likelihood` (array)
    Example: [{"name":"Very Low","value":1,"color":"#EDF9F2"},{"name":"Low","value":2,"color":"#91D4BC"},{"name":"Moderate","value":5,"color":"#FFB75D"},{"name":"High","value":8,"color":"#FF8C00"},{"name":"Very High","value":10,"color":"#C2533B"}]

  - `customRiskScales.likelihood.name` (string)
    Name of the likelihood level

  - `customRiskScales.likelihood.value` (integer)
    Value of the likelihood level

  - `customRiskScales.likelihood.color` (string)
    Color associated with the likelihood level

  - `customRiskScales.impact` (array)
    Example: [{"name":"Very Low","value":1,"color":"#EDF9F2"},{"name":"Low","value":2,"color":"#91D4BC"},{"name":"Moderate","value":5,"color":"#FFB75D"},{"name":"High","value":8,"color":"#FF8C00"},{"name":"Very High","value":10,"color":"#C2533B"}]

  - `customRiskScales.impact.name` (string)
    Name of the impact level

  - `customRiskScales.impact.value` (integer)
    Value of the impact level

  - `customRiskScales.impact.color` (string)
    Color associated with the impact level

  - `customRiskScales.inherentRisk` (array)
    Example: [{"name":"Very Low","value":1,"color":"#EDF9F2","inherentRiskThreshold":1},{"name":"Low","value":2,"color":"#91D4BC","inherentRiskThreshold":10},{"name":"Moderate","value":5,"color":"#FFB75D","inherentRiskThreshold":40},{"name":"High","value":8,"color":"#FF8C00","inherentRiskThreshold":64},{"name":"Very High","value":10,"color":"#C2533B","inherentRiskThreshold":100}]

  - `customRiskScales.inherentRisk.name` (string)
    Name of the inherent risk level

  - `customRiskScales.inherentRisk.value` (integer)
    Value of the inherent risk level

  - `customRiskScales.inherentRisk.color` (string)
    Color associated with the inherent risk level

  - `customRiskScales.inherentRisk.inherentRiskThreshold` (integer)
    Threshold value for the inherent risk level

  - `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 risk
    Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"

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

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

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

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