Skip to main content
POST
/
risk-scenarios
Create risk scenario
curl --request POST \
  --url https://api.vanta.com/v1/risk-scenarios \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "<string>",
  "riskId": "<string>",
  "isSensitive": true,
  "likelihood": 123,
  "impact": 123,
  "residualLikelihood": 123,
  "residualImpact": 123,
  "categories": [
    "<string>"
  ],
  "ciaCategories": [],
  "owner": "<string>",
  "note": "<string>",
  "riskRegister": "<string>",
  "customFields": [
    {
      "label": "<string>",
      "value": "<string>"
    }
  ],
  "identificationDate": "2023-11-07T05:31:56Z"
}
'
{
  "riskId": "assets-not-identified-and-protected",
  "description": "Assets are not identified and protected according to company requirements.",
  "isSensitive": false,
  "likelihood": 4,
  "impact": 4,
  "residualLikelihood": 2,
  "residualImpact": 1,
  "categories": [
    "Access control"
  ],
  "ciaCategories": [
    "Confidentiality"
  ],
  "treatment": "Avoid",
  "owner": null,
  "note": null,
  "riskRegister": "Default",
  "customFields": [],
  "isArchived": false,
  "reviewStatus": "DRAFT",
  "requiredApprovers": [],
  "type": "Risk Scenario",
  "identificationDate": "2024-03-07T18:46:05.944Z"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
description
string
required

This describes an actual or potential risk to your organization's people, processes, technology, data, and facilities. Document actual issues or likely scenarios based on your specific environment or a potential vulnerability.

​
riskId
string

The unique ID of the risk. Used to reference and update existing risks. We will auto-generate one if one isn't specified.

​
isSensitive
boolean
deprecated

If set to true this risk can only be seen by its owner or users with Admin, RiskSensitiveManage or RiskSensitiveView permissions.

​
likelihood
integer<int32>

Represents the probability of an incident occurring due to this risk or vulnerability, expressed as a numerical score. Defaults to a range of 1-5, where higher values indicate greater likelihood. The range can be customized in the Risk Management settings.

​
impact
integer<int32>

Represents the potential severity of harm to your organization’s operations if this risk is exploited, expressed as a numerical score. Defaults to a range of 1-5, where higher values indicate greater impact. The range can be customized in the Risk Management settings.

​
residualLikelihood
integer<int32>

Represents the adjusted probability of this risk being exploited or affecting operations after implementing risk treatments, such as controls or mitigations. Expressed as a numerical score, defaulting to a range of 1-5. The range can be customized in the Risk Management settings.

​
residualImpact
integer<int32>

Represents the adjusted severity of harm to your organization’s operations if this risk is exploited after implementing risk treatments, such as controls or mitigations. Expressed as a numerical score, defaulting to a range of 1-5. The range can be customized in the Risk Management settings.

​
categories
string[]

The list of categories this risk scenario belongs to. Each element in the list will become a new custom category if it doesn't match an existing one. You can reference the current category options in the Risk Management settings and/or enter new values.

​
ciaCategories
enum<string>[]

Enter a list of the following for the type of risk documented:

  • Confidentiality: Risk to data stores, customer/sensitive information, etc.
  • Integrity: Risk to accuracy or integrity of system settings and/or data
  • Availability: Risk to normal service operations and critical system functionality
Available options:
Confidentiality,
Integrity,
Availability
​
treatment
enum<string>

Indicate how your leadership team wants to address an identified risk. Please note: not all risks need to be addressed immediately (or at all). Your Risk Treatment decision will depend on multiple factors, such as your organization's risk tolerance and the value of the asset that the risk is associated with. The options are:

  • Mitigate: Identify controls to put in place or tasks to be done that will reduce the risk score.
  • Transfer: Move risk outside of your organization's set of responsibilities e.g. get cyber liability insurance.
  • Avoid: Stop doing the activity which is causing the risk to your organization and its assets.
  • Accept: Decide to live with the risk and take no further actions. - Accept: decide to live with the risk; this may be because it is highly unlikely, has a low financial or operational impact, or the cost and effort to treat the risk far exceeds the value of the asset
Available options:
Mitigate,
Transfer,
Avoid,
Accept
​
owner
string

The person responsible for tracking and mitigating this risk scenario. This should be the email address of a valid Vanta user.

​
note
string

Additional context about the risk scenario and why it has specific impact and likelihood scores.

​
riskRegister
string

Name of the risk register to associate with this scenario.

This field must be set if the organization has multiple registers.

​
customFields
object[]

The list of custom attributes. You can reference existing custom attributes in the Risk Management settings and/or create new ones. The format is:

  • {label: "field-name", value: "string-representation"} for text, date, number and currency fields
  • {label: "field-name", value: ["option1", "option2"]} for picklist fields
​
type
enum<string>

The type of risk scenario to create.

  • "Risk Scenario": Standard risk scenario (default)
  • "Enterprise Risk": Enterprise-level risk (requires Enterprise Risk Management SKU)

Enterprise risks cannot be associated with a risk register. Defaults to "Risk Scenario" if not specified.

Available options:
Risk Scenario,
Enterprise Risk
​
identificationDate
string<date-time>

The date this risk was identified. Matches the "Identified Date" field in the Vanta UI. Defaults to the scenario's creation time if omitted.

Response

200 - application/json

Ok

​
riskId
string
required

The unique ID of the risk specified by the user. Used to reference and update existing risks.

​
description
string
required

This describes an actual or potential risk to your organization's people, processes, technology, data, and facilities. Document actual issues or likely scenarios based on your specific environment or a potential vulnerability.

​
isSensitive
boolean | null
required
deprecated

If set to true this risk can only be seen by its owner or users with Admin, RiskSensitiveManage or RiskSensitiveView permissions.

​
likelihood
integer<int32> | null
required

Represents the probability of an incident occurring due to this risk or vulnerability, expressed as a numerical score. Defaults to a range of 1-5, where higher values indicate greater likelihood. The range can be customized in the Risk Management settings. A value of null indicates that no score has been assigned.

​
impact
integer<int32> | null
required

Represents the potential severity of harm to your organization’s operations if this risk is exploited, expressed as a numerical score. Defaults to a range of 1-5, where higher values indicate greater impact. The range can be customized in the Risk Management settings. A value of null indicates that no score has been assigned.

​
residualLikelihood
integer<int32> | null
required

Represents the adjusted probability of this risk being exploited or affecting operations after implementing risk treatments, such as controls or mitigations. Expressed as a numerical score, defaulting to a range of 1-5. The range can be customized in the Risk Management settings. A value of null indicates that no score has been assigned.

​
residualImpact
integer<int32> | null
required

Represents the adjusted severity of harm to your organization’s operations if this risk is exploited after implementing risk treatments, such as controls or mitigations. Expressed as a numerical score, defaulting to a range of 1-5. The range can be customized in the Risk Management settings. A value of null indicates that no score has been assigned.

​
categories
string[]
required

The list of categories this risk scenario belongs to.

​
ciaCategories
enum<string>[]
required

A list of the following for the type of risk documented:

  • Confidentiality: Risk to data stores, customer/sensitive information, etc.
  • Integrity: Risk to accuracy or integrity of system settings and/or data
  • Availability: Risk to normal service operations and critical system functionality
Available options:
Confidentiality,
Integrity,
Availability
​
treatment
enum<string>
required

Indicate how your leadership team wants to address an identified risk. Please note: not all risks need to be addressed immediately (or at all). Your Risk Treatment decision will depend on multiple factors, such as your organization's risk tolerance and the value of the asset that the risk is associated with. The options are:

  • Mitigate: Identify controls to put in place or tasks to be done that will reduce the risk score.
  • Transfer: Move risk outside of your organization's set of responsibilities e.g. get cyber liability insurance.
  • Avoid: Stop doing the activity which is causing the risk to your organization and its assets.
  • Accept: Decide to live with the risk and take no further actions. - Accept: decide to live with the risk; this may be because it is highly unlikely, has a low financial or operational impact, or the cost and effort to treat the risk far exceeds the value of the asset
Available options:
Mitigate,
Transfer,
Avoid,
Accept
​
owner
string | null
required

The email of the person responsible for tracking and mitigating this risk scenario.

​
note
string | null
required

Additional context about the risk scenario and why it has specific impact and likelihood scores.

​
riskRegister
string | null
required

Name of the risk register associated with this scenario.

​
customFields
object[]
required

The list of custom fields. You can reference existing custom fields in the Risk Management settings and/or create new ones. The format is:

  • {label: "field-name", value: "string-representation"} for text, date, number and currency fields
  • {label: "field-name", value: ["option1", "option2"]} for picklist fields
​
isArchived
boolean
required

Whether this scenario is archived.

​
reviewStatus
enum<string>
required

The current review status of this risk scenario

Available options:
APPROVED,
DRAFT,
NOT_REVIEWED,
AWAITING_SUBMISSION,
PENDING_APPROVAL,
REQUESTED_CHANGES
​
requiredApprovers
string[]
required

The list of required approvers for this risk scenario.

​
type
enum<string>
required

The type of risk scenario.

  • "Risk Scenario": Standard risk scenario
  • "Enterprise Risk": Enterprise-level risk
Available options:
Risk Scenario,
Enterprise Risk
​
identificationDate
string<date-time>
required

The date this risk was identified. Matches the "Identified Date" field in the Vanta UI. Set by the customer when a risk is created; defaults to the scenario's creation time when not explicitly provided.