v1

latestOpenAPI 3.1.0Apache 2.02026-07-245981,1853.0 MB

Assessment Actions

Launch Assessment

Use this API to launch a new assessment. The new assessment will be created with the details provided in the request body and assigned to the indicated respondents. If the selected template includes an Approver-only section, a user with the Project Owner role can be assigned to that section.

🗒 Things to Know

The inventoryDetails information can be added in order to set a primary record and pre-populate inventory information on the assessment.

Within the inventoryDetails object of the request, certain parameters are interchangeably required. This means that only one identifier parameter and one type parameter is required to make a successful API call:

Inventory identifier (choose one): inventoryId, inventoryNumber, or inventoryName

Inventory type (choose one): inventoryTypeId or inventoryTypeName

The templateRootVersionId parameter can be used instead of the templateId parameter to create the new assessment using the latest published version of a template.

post/api/assessment/v3/assessments

Request body

workflowIdstring uuid

Workflow identifier for which the assessment is associated with

namestring required

Name of the assessment

descriptionstring

Description of the assessment

orgGroupIdstring uuid

Organization group identifier to which the assessment should belong

orgGroupNamestring

Organization group name to which the assessment should belong

approverIdstring uuid

Approver identifier of the assessment (deprecated, use approvers list instead)

approverNamestring

Approver name of the assessment (deprecated, use approvers list instead)

templateIdstring uuid

Template identifier for which the assessment has to be created (mandatory if templateRootVersionId is not provided)

templateRootVersionIdstring uuid

Template root version identifier for which the assessment has to be created

Type of the template to use when creating the assessment. Used together with 'templateName' if templateId nor 'templateRootVersionId' is not provided

templateNamestring

Template name for which the assessment has to be created. Used together with 'templateType' if templateId nor 'templateRootVersionId' is not provided

suggestedTemplateIdstring uuid

Suggested template identifier provided by AI agent

suggestedTemplateNamestring

Suggested template name provided by AI agent

deadlinestring date-time

Deadline to complete the assessment (format: YYYY-MM-DDTHH:MM:SS.FFFZ)

reminderinteger

Number of days before the deadline when the reminder should be sent to the respondentNote: Either 'reminder' or 'reminderSchedules' should be provided. If both are present, 'reminder' takes precedence and will be converted to a reminderSchedule for RESPONDENT notification.

respondentCreationType'INVITED' | 'PROJECT_RESPONDENT'

Type of user creation for respondents

primaryRecordTypeReferencestring

Type of primary record when primaryEntityDetails are populated

ruleIdstring uuid

Identifier of the rule that triggered this assessment creation

triggeredByAssessmentIdstring uuid

Identifier of the assessment that triggered this assessment creation

triggeredByAssessmentNamestring

Name of the assessment that triggered this assessment creation

tagsstring[]

List of tag identifiers to attach to the assessment during creation

userAssignmentMode'ASSESSMENT' | 'SECTION'

Mode of user assignment for the assessment

Source of assessment creation

checkForInFlightAssessmentsboolean

Whether to check if any in-flight (status < COMPLETED) assessments exist with the same templateRootVersionId

defaultTemplateDeadlineReminderboolean

labelsstring[]

List of labels to attach to the assessment

duplicateNotAllowedboolean

Example request

{
  "workflowId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "GDPR Assessment",
  "description": "Annual GDPR compliance assessment",
  "orgGroupId": "550e8400-e29b-41d4-a716-446655440000",
  "orgGroupName": "Legal Department",
  "approverId": "550e8400-e29b-41d4-a716-446655440000",
  "approverName": "John Smith",
  "approvers": [
    {
      "approverId": "550e8400-e29b-41d4-a716-446655440001",
      "approverName": "Jane Smith",
      "comment": "Primary approver"
    }
  ],
  "templateId": "550e8400-e29b-41d4-a716-446655440000",
  "templateRootVersionId": "550e8400-e29b-41d4-a716-446655440000",
  "templateType": "PIA",
  "templateName": "One PIA 6.0",
  "suggestedTemplateId": "550e8400-e29b-41d4-a716-446655440000",
  "suggestedTemplateName": "GDPR Assessment Template",
  "deadline": "2023-12-31T23:59:59Z",
  "reminder": 7,
  "reminderSchedules": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "assessmentId": "8f14e45f-ea9e-4d1b-9b5f-42d5f6a8b9c1",
      "sectionId": "9a1b2c3d-4e5f-6789-abcd-ef0123456789",
      "reminderInterval": 7,
      "reminderReceiverEntityType": "RESPONDENT"
    }
  ],
  "respondents": [
    {
      "respondentId": "550e8400-e29b-41d4-a716-446655440002",
      "respondentName": "John Doe",
      "comment": "Primary respondent"
    }
  ],
  "approverOnlySectionRespondents": [
    {
      "respondentId": "550e8400-e29b-41d4-a716-446655440000",
      "respondentName": "John Doe"
    }
  ],
  "respondentCreationType": "INVITED",
  "inventoryDetails": {
    "inventoryId": "550e8400-e29b-41d4-a716-446655440000",
    "inventoryTypeId": 1,
    "inventoryTypeName": "Data Processing Activity",
    "inventoryNumber": 12345,
    "inventoryName": "Customer Data Processing for Marketing"
  },
  "incidentDetails": {
    "incidentId": "123e4567-e89b-12d3-a456-426614174000",
    "incidentName": "Data Breach - Customer Database Compromise"
  },
  "controlImplementationDetails": [
    {
      "controlImplementationId": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "primaryEntityDetails": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Vendor name",
      "number": 1,
      "relationshipResponseDetails": [
        {
          "relationshipNodeType": "ASSESSMENT",
          "entityId": "123e4567-e89b-12d3-a456-426614174000",
          "entityDisplayName": "Customer Data Assessment",
          "entityType": {
            "id": 1,
            "name": "Privacy Impact Assessment",
            "description": "Assessment type for privacy impact evaluation"
          }
        }
      ],
      "displayName": "Vendor display name",
      "entityBusinessKey": "Vendor business key"
    }
  ],
  "primaryRecordTypeReference": "INVENTORY",
  "engagementLink": {
    "engagementId": "987e6543-e21b-12d3-a456-426614174000",
    "engagementName": "Q4 2024 Vendor Risk Assessment Engagement",
    "number": 2024001
  },
  "ruleId": "550e8400-e29b-41d4-a716-446655440000",
  "triggeredByAssessmentId": "550e8400-e29b-41d4-a716-446655440000",
  "triggeredByAssessmentName": "Parent GDPR Assessment",
  "tags": [
    "tag1",
    "tag2"
  ],
  "userAssignmentMode": "ASSESSMENT",
  "creationSource": "DEFAULT",
  "labels": [
    "label1",
    "label2"
  ],
  "entityLabels": [
    {
      "name": "Personal Data Processing",
      "nameKey": "label.personal.data.processing",
      "referenceEntity": "DATA_CATEGORY",
      "valueRefId": "123e4567-e89b-12d3-a456-426614174000",
      "valueKey": "data.category.personal.information"
    }
  ],
  "attachmentRequests": [
    {
      "attachmentId": "456e7890-e89b-12d3-a456-426614174000",
      "fileName": "Privacy_Impact_Assessment_Report.pdf",
      "fileDescription": "Comprehensive privacy impact assessment report for customer data processing activities"
    }
  ]
}

Response

Created

string uuid required