Launch Assessment

post

https://{hostname}/api/assessment/v3/assessments

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" permission can be assigned to that section.

🗒
Things to Know

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

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

Body Params

workflowId

uuid

Workflow identifier for which the assessment is associated with

name

string

required

length between 0 and 2500

Name of the assessment

description

string

Description of the assessment

orgGroupId

uuid

Organization group identifier to which the assessment should belong

orgGroupName

string

Organization group name to which the assessment should belong

approverId

uuid

deprecated

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

approverName

string

deprecated

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

approvers

array of objects

List of approvers for the assessment

approvers

templateId

uuid

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

templateRootVersionId

uuid

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

deadline

date-time

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

reminder

int64

Number of days before the deadline when the reminder should be sent to the respondent

reminderSchedules

array of objects

reminderSchedules

respondents

array of objects

required

length between 1 and 2147483647

List of respondents. A minimum of one respondent must be assigned to the assessment

respondents*

respondentId

uuid

Unique identifier for the respondent user

respondentName

string

required

Display name of the respondent

comment

string

Optional comment for the respondent assignment

sectionIds

array

sectionIds

isRespondentOfApproverSection

boolean

Defaults to false

Flag indicating whether this respondent is assigned to approver sections

approverOnlySectionRespondents

array of objects

List of respondents for approver-only sections

approverOnlySectionRespondents

respondentCreationType

string

enum

Defaults to INVITED

Type of user creation for respondents

Allowed:

inventoryDetails

object

If the assessment is for an inventory, contains the inventory identifier and type

incidentDetails

object

If the assessment is for an incident, contains the incident identifier and type

controlImplementationDetails

array of objects

Populated when Control Implementations are selected as Primary for Assessment

controlImplementationDetails

primaryEntityDetails

array of objects

Populated when Business Object needs to be selected as Primary for Assessment (except Inventory, Incident, Control Implementations and Engagements)

primaryEntityDetails

primaryRecordTypeReference

string

Type of primary record when primaryEntityDetails are populated

engagementLink

object

If the assessment is launched from engagement, contains the engagement identifier

ruleId

uuid

Identifier of the rule that triggered this assessment creation

triggeredByAssessmentId

uuid

Identifier of the assessment that triggered this assessment creation

triggeredByAssessmentName

string

Name of the assessment that triggered this assessment creation

201Created

429Too Many Requests. For more information, see API Rate Limits.