Create and update risk scenarios

This guide creates and updates risk scenarios via POST /v1/risk-scenarios and PATCH /v1/risk-scenarios/{riskScenarioId} on the Manage Vanta API. It covers the three things most integrations trip on: targeting a specific risk register, setting custom fields with the right label and value shape, and modeling attributes (like “source of risk”) that aren’t in the built-in schema.

Before you begin

This guide is for Vanta admins managing risk data inside their own Vanta account. You’ll need:

A Manage Vanta API token.
Scopes vanta-api.all:read and vanta-api.all:write on the token. There is no risk-specific scope — risk scenarios are covered by the broad vanta-api.all:* scopes. See API authentication.
Any custom fields you plan to set must already be defined in Risk Management → Settings → Custom Fields in the Vanta UI. The API fills custom field values; it can’t create the field definitions.

The CreateRiskScenarioInput schema has a fixed set of fields. There is no built-in source field, no built-in jiraTicket field, and no per-scenario “risk owner group”. Anything not in the table below has to be modeled as a custom field (see Step 2 below):

Field	Type	Notes
`description`	string	Required. Short title of the risk.
`detailedDescription`	string	Long-form context (max 10,000 chars).
`riskId`	string	Stable identifier. Auto-generated if omitted. Reuse it to update.
`likelihood` / `impact`	integer	Inherent risk scores, default range 1–5 (customizable in settings).
`residualLikelihood` / `residualImpact`	integer	Post-mitigation scores.
`categories`	string[]	New values become new categories automatically.
`ciaCategories`	`Confidentiality` / `Integrity` / `Availability`
`treatment`	`Mitigate` / `Transfer` / `Avoid` / `Accept`
`owner`	string	Email address of a Vanta user.
`note`	string	Justification for the scores.
`riskRegister`	string	Name of the register (not an id). Required if you have multiple registers.
`customFields`	array	Label/value pairs for org-specific attributes — see Step 2 below.
`type`	`Risk Scenario` / `Enterprise Risk`	Enterprise risks can’t be attached to a register. Defaults to `Risk Scenario`.
`identificationDate`	ISO 8601	Defaults to creation time.

There’s also a deprecated isSensitive boolean still accepted by the API; new integrations shouldn’t rely on it.

Create a risk scenario in a specific register

Your terminal — POST /v1/risk-scenarios. Only description is strictly required, but if your tenant has more than one risk register you must pass riskRegister by name (case-sensitive) or the API returns 400.

const res = await fetch("https://api.vanta.com/v1/risk-scenarios", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer YOUR_TOKEN",
  },
  body: JSON.stringify({
    description: "Unauthorized access to production database",
    riskRegister: "Default",
    likelihood: 3,
    impact: 4,
    treatment: "Mitigate",
    owner: "risk-owner@example.com",
    ciaCategories: ["Confidentiality"],
  }),
});
const scenario = await res.json();
console.log(scenario.riskId);

import requests

r = requests.post(
    "https://api.vanta.com/v1/risk-scenarios",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "description": "Unauthorized access to production database",
        "riskRegister": "Default",
        "likelihood": 3,
        "impact": 4,
        "treatment": "Mitigate",
        "owner": "risk-owner@example.com",
        "ciaCategories": ["Confidentiality"],
    },
)
r.raise_for_status()
print(r.json()["riskId"])

curl -X POST 'https://api.vanta.com/v1/risk-scenarios' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "description": "Unauthorized access to production database",
    "riskRegister": "Default",
    "likelihood": 3,
    "impact": 4,
    "treatment": "Mitigate",
    "owner": "risk-owner@example.com",
    "ciaCategories": ["Confidentiality"]
  }'

A 200 response returns the full risk scenario, including the riskId you’ll use for later updates.

Which register name should I send?

riskRegister takes the register’s name, not its id. Open Risk Management → Registers in Vanta and copy the exact name (spaces, capitalization, and punctuation all matter). Tenants with a single register can omit the field.

Got `400` saying `owner` is not a valid user?

owner must be the email address of an existing Vanta user, not a display name or a person id. Look up the address with GET /v1/people filtered to employmentStatus=CURRENT.

Creating an Enterprise Risk instead?

Pass type: "Enterprise Risk" and omit riskRegister — enterprise risks aren’t attached to a register. Requires the Enterprise Risk Management SKU.

Set custom fields

Anything outside the built-in schema — “Source of risk”, a Jira ticket URL, an internal risk tier, a business unit — is a custom field. Custom fields must be defined ahead of time in Risk Management → Settings → Custom Fields; the API fills values but never creates field definitions.Pass them via the customFields array. Each entry has a label (matches the field name in settings exactly, case-sensitive) and a value matching the field’s type:

Text / date / number / currency — JSON string: { "label": "Source of risk", "value": "Internal audit finding" }
Picklist — JSON array of strings: { "label": "Business unit", "value": ["Engineering", "Security"] }

curl -X POST 'https://api.vanta.com/v1/risk-scenarios' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "description": "Unauthorized access to production database",
    "riskRegister": "Default",
    "customFields": [
      { "label": "Source of risk", "value": "Internal audit finding" },
      { "label": "Jira ticket", "value": "https://your-org.atlassian.net/browse/SEC-1234" },
      { "label": "Business unit", "value": ["Engineering", "Security"] }
    ]
  }'

Got `400 RiskCustomAttribute with id: <label> not found`?

The label you sent doesn’t match any custom field defined in Risk Management → Settings → Custom Fields. This includes system-style identifiers like managed_by_email — the API does not resolve those. Open the settings page, copy the field name exactly, and retry. Custom field definitions cannot be created through the API.

Got a 400 saying the value type is wrong?

Your JSON value doesn’t match the field’s declared type. Picklist fields need an array of strings even when you’re only setting one option. Text/date/number/currency fields need a plain string.

Where does the built-in Source, Jira, or Ticket field live?

There isn’t one. riskId, description, detailedDescription, note, categories, ciaCategories, treatment, owner, riskRegister, likelihood, impact, residualLikelihood, residualImpact, type, and identificationDate (plus the deprecated isSensitive flag) are the only non-custom fields on a risk scenario — everything else has to be a custom field.

Update an existing scenario

Your terminal — PATCH /v1/risk-scenarios/{riskScenarioId}. Send only the fields you want to change; omitted fields keep their current values. customFields follows the same shape as create.

const RISK_ID = "YOUR_RISK_ID";

const res = await fetch(`https://api.vanta.com/v1/risk-scenarios/${RISK_ID}`, {
  method: "PATCH",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer YOUR_TOKEN",
  },
  body: JSON.stringify({
    residualLikelihood: 2,
    residualImpact: 2,
    customFields: [
      { label: "Jira ticket", value: "https://your-org.atlassian.net/browse/SEC-1234" },
    ],
  }),
});
console.log(await res.json());

RISK_ID="YOUR_RISK_ID"

curl -X PATCH "https://api.vanta.com/v1/risk-scenarios/$RISK_ID" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "residualLikelihood": 2,
    "residualImpact": 2,
    "customFields": [
      { "label": "Jira ticket", "value": "https://your-org.atlassian.net/browse/SEC-1234" }
    ]
  }'

Need to clear a custom field?

Send the field with value: "" (text/date/number/currency) or value: [] (picklist). The label still has to match a defined field.

Can I change `type` on update?

No — changing a scenario’s type (Risk Scenario ↔ Enterprise Risk) is not supported via PATCH. Requests that include type are rejected. Create a new scenario with the desired type and archive the old one.

Congratulations

You can now create risk scenarios in the right register, populate every organization-specific attribute via custom fields, and update scores or metadata idempotently.

Next steps

Assign a control owner

Make a specific user accountable for the controls that mitigate a risk.

Set custom fields on vendors

Same customFields pattern applied to the Vendors API.

Try it in Postman

Import the collection and hit POST /v1/risk-scenarios against a sandbox.

Manage Vanta API reference

Browse every Manage Vanta endpoint — risk scenarios, controls, tests, documents, people.

Get Started

Guides

Concepts

Build for Vanta customers

Tools and Platform

Before you begin

Congratulations

Next steps

Assign a control owner

Set custom fields on vendors

Try it in Postman

Manage Vanta API reference

​Before you begin

​Congratulations

​Next steps

Assign a control owner

Set custom fields on vendors

Try it in Postman

Manage Vanta API reference

Before you begin

Congratulations

Next steps