Risks API

List risks

List all risks for an account:

GET /risks

Response

Status: 200 OK
[
  {
    "id": 12348,
    "sourceID": null,
    "subject": "Integration with cloud application could lead to breach of our Data Protection Policy",
    "severity": "high",
    "status": "closed",
    "closed_at": "2020-01-15T09:55:00-06:00",
    "closure_reason": "transferred",
    "created_at": "2020-01-10T07:36:00-06:00",
    "updated_at": "2020-02-11T05:30:55-06:00"
  },
  "..."
]

The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of risks.

Predefined Filters

The following predefined filters are available:

Collection Fields

By default the following fields will appear in collections of risks:

id sourceID subject severity status mitigation_target_at closed_at closure_reason created_at updated_at

Obtain a different set of fields using the ?fields= parameter.

Filtering

Filtering is available for the following fields:

id source sourceID subject status mitigation_target_at closed_at created_at updated_at

Sorting

By default a collection of risks is sorted ascending by name.

The following fields are accepted by the ?sort= parameter:

id sourceID subject mitigation_target_at closed_at created_at updated_at

Get a single risk

GET /risks/:id

Response

Status: 200 OK
{
  "closed_at": "2020-01-15T09:55:00-06:00",
  "closure_reason": "transferred",
  "created_at": "2020-01-10T07:36:00-06:00",
  "custom_data": "{\"likelihood\":\"high\",\"impact\":\"high\",\"residual_risk\":\"high\"}",
  "custom_fields": [
    {
      "id": "likelihood",
      "value": "high"
    },
    {
      "id": "impact",
      "value": "high"
    },
    {
      "id": "residual_risk",
      "value": "high"
    }
  ],
  "id": 12348,
  "manager": {
    "id": 6,
    "name": "Howard Tanner"
  },
  "severity": "high",
  "source": "4me",
  "sourceID": null,
  "status": "closed",
  "subject": "Integration with cloud application could lead to breach of our Data Protection Policy",
  "ui_extension": {
    "id": 4,
    "name": "Risk",
    "category": "risk",
    "title": "Risk Assessment",
    "account": {
      "id": "wdc",
      "name": "Widget Data Center"
    },
    "localized_title": "Risk Assessment"
  },
  "updated_at": "2020-02-11T05:30:55-06:00",
  "account": {
    "id": "wdc",
    "name": "Widget Data Center"
  }
}

The response contains these fields.

Create a risk

POST /risks

When creating a new risk these fields are available.

Response

Status: 201 Created
{
  "name": "...",
  "...": "..."
}

The response contains all fields of the created risk and is similar to the response in Get a single risk.

Update a risk

PATCH /risks/:id

When updating a risk these fields are available.

Response

Status: 200 OK
{
  "name": "...",
  "...": "..."
}

The response contains all fields of the updated risk and is similar to the response in Get a single risk.

Fields

attachments
Readonly aggregated Attachments
closed_at
Readonly datetime — The Closed at field is automatically set to the date and time at which the risk is saved with the status “Closed”.
closure_reason
Optional enum — The Closure reason field is used to select the appropriate closure reason for the risk when it has been closed. Valid values are:
  • eliminated: Eliminated - Risk Completely Eliminated
  • accepted: Accepted - Risk Level Accepted
  • mitigated: Mitigated - Risk Reduced to Acceptable Level
  • transferred: Transferred - Risk Transferred to Another Organization
  • no_risk: No Risk - Assessment Found No Risk
created_at
Readonly datetime — The date and time at which the risk was created.
custom_fields
Optional custom fields — Custom fields provided in JSON format by the UI Extension that is linked to the risk.
custom_fields_attachments
Writeonly attachments The attachments used in Custom fields.
id
Readonly integer — The unique ID of the risk.
manager
Optional reference to Person — The Manager field is used to select the manager of the risk. This person is able to maintain the information about the risk.
mitigation_target_at
Optional date — The date by which the risk should have been mitigated.
note
Optional text (max 64KB) — The Note field is used to provide a detailed description of the risk and the actions that are planned or have already been taken to eliminate it, or to minimize its severity. This field is also used when the status is set to ‘Closed’ to explain why it was decided to close the risk.

The Note field cannot be specified in the ?fields= parameter.

note_attachments
Writeonly attachments The attachments used in the Note field.
resolution_duration
Readonly integer — The number of minutes it took to complete this risk, which is calculated as the difference between the created_at and closed_at values.
severity
Optional enum with reference field of Risk Severity — The Severity field is used to select the severity of the risk.
status
Optional enum, default: anticipated — The Status field is used to select the current status of the risk. Valid values are:
  • anticipated: Anticipated
  • materialized: Materialized
  • closed: Closed
subject
Required string (max 128) — The Subject field is used to enter the subject of the risk.
source
Optional string (max 30) - See source
sourceID
Optional string (max 128) - See source
ui_extension
Readonly reference to UI Extension — The UI extension field indicates the UI extension that is applied to the risk.
updated_at
Readonly datetime — The date and time of the last update of the risk. If the risk has no updates it contains the created_at value.