# 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`  
]

```json
{
  "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

```json
{
  "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**

```bash
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**

```json
{
  "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.