Create assessment

POST https://www.example.com/api/v2/assessments

Create a new assessment from a template, optionally linked to systems. The assessment starts in not_started status. The template must be a Risk Monitor template accessible to the customer.

Request

Header Parameters

authorization string required
Example: Bearer privacy_api_key.abc123

• application/json

Body required

template_id uuid required
UUID of the assessment template to create from. Must be a Risk Monitor template.

name string required
Assessment name
Example: Vendor Risk Assessment - Acme Analytics

due_date date nullable
Example: 2026-06-01

renewal_frequency string nullable
Renewal frequency for recurring assessments
Possible values: [Week, Month, Year]

renewal_interval integer nullable
Number of frequency units between renewals
Possible values: >= 1
Example: 1

processing_activity_ids integer[] nullable
Optional processing activity IDs to link. Each must belong to the customer.
Example: [123,456]

systems object[] nullable
Optional systems to link. Each entry must have at least system_id or display_name.
Array [
system_id uuid nullable
UUID from the shared system catalog
display_name string nullable
Display name for custom systems not in the catalog
Example: Acme Analytics
]

{
  "template_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",

"name": "Vendor Risk Assessment - Acme Analytics",

"due_date": "2026-06-01",

"renewal_frequency": "Week",

"renewal_interval": 1,

"processing_activity_ids": [
    123,
    456
  ],

"systems": [
    {
      "system_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "display_name": "Acme Analytics"
    }
  ]
}

Responses

• 201
  Assessment created

• 422
  Validation failure

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Vendor Risk Assessment - Acme Analytics",
    "status": "not_started",
    "template_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "template_name": "Vendor Risk Assessment",
    "due_date": "2024-07-29",
    "systems": [
      {
        "system_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "display_name": "Acme Analytics"
      }
    ],
    "last_updated": "1714500000000",
    "created_at": "2024-07-29T15:51:28.071Z",
    "updated_at": "2024-07-29T15:51:28.071Z",
    "progress": {
      "total_questions": 24,
      "answered_questions": 12,
      "required_remaining": 5
    }
  }
}

Validation Failure Examples

• CURL

curl -L 'https://www.example.com/api/v2/assessments' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "template_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Vendor Risk Assessment - Acme Analytics",
  "due_date": "2026-06-01",
  "renewal_frequency": "Week",
  "renewal_interval": 1,
  "processing_activity_ids": [
    123,
    456
  ],
  "systems": [
    {
      "system_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "display_name": "Acme Analytics"
    }
  ]
}'

Base URL

https://www.example.com

Parameters

authorization — header required

Body required

{
  "template_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Vendor Risk Assessment - Acme Analytics",
  "due_date": "2026-06-01",
  "renewal_frequency": "Week",
  "renewal_interval": 1,
  "processing_activity_ids": [
    123,
    456
  ],
  "systems": [
    {
      "system_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "display_name": "Acme Analytics"
    }
  ]
}

Disclaimer: The information contained in this message does not constitute as legal advice. We would advise seeking professional counsel before acting on or interpreting any material.