myOneTrustDeveloper ForumTechnology Partners
API Reference
Subscribe via RSS

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 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.
Body Params
uuid

Workflow identifier for which the assessment is associated with

string
required
length between 0 and 2500

Name of the assessment

string

Description of the assessment

uuid

Organization group identifier to which the assessment should belong

string

Organization group name to which the assessment should belong

uuid
deprecated

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

string
deprecated

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

approvers
array of objects

List of approvers for the assessment

approvers
uuid

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

uuid

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

string
enum

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

string

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

uuid

Suggested template identifier provided by AI agent

string

Suggested template name provided by AI agent

date-time

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

int64

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.

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*
uuid

Unique identifier for the respondent user

string
required

Display name of the respondent

string

Optional comment for the respondent assignment

sectionIds
array
sectionIds
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
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
string

Type of primary record when primaryEntityDetails are populated

engagementLink
object

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

uuid

Identifier of the rule that triggered this assessment creation

uuid

Identifier of the assessment that triggered this assessment creation

string

Name of the assessment that triggered this assessment creation

tags
array of strings

List of tag identifiers to attach to the assessment during creation

tags
string
enum
Defaults to ASSESSMENT

Mode of user assignment for the assessment

Allowed:
string
enum
Defaults to DEFAULT

Source of assessment creation

boolean
Defaults to false

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

boolean
labels
array of strings

List of labels to attach to the assessment

labels
entityLabels
array of objects

List of entity attribute labels for the assessment

entityLabels
boolean
Defaults to false
attachmentRequests
array of objects

List of assessment attachment request

attachmentRequests
Responses

400

Bad Request

401

Unauthorized

403

Forbidden

500

Internal Server Error

Updated 29 days ago

Language
Credentials
OAuth2
Missing 1 required scope
URL
LoadingLoading…
Response
Choose an example:
application/json
*/*

Updated 29 days ago