--- title: "Launch Assessment" method: POST path: "/api/assessment/v3/assessments" tags: ["Assessment Actions"] --- # Launch Assessment `POST /api/assessment/v3/assessments` ## Request - Base URL: `https://hostname` - URL: `https://hostname/api/assessment/v3/assessments` - Auth: OAuth 2 - Client credentials - Token URL: `https://{hostname}/api/access/v1/oauth/token` scopes: `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. ## Query parameters - `oneAgent` boolean ## Request body - PrivacyAutomationAssessmentAutomationAssessmentCreateRequest - `workflowId` string, uuid: Workflow identifier for which the assessment is associated with - `name` string, required: Name of the assessment - `description` string: Description of the assessment - `orgGroupId` string, uuid: Organization group identifier to which the assessment should belong - `orgGroupName` string: Organization group name to which the assessment should belong - `approverId` string, uuid: Approver identifier of the assessment (deprecated, use approvers list instead) - `approverName` string: Approver name of the assessment (deprecated, use approvers list instead) - `approvers` PrivacyAutomationAssessmentAutomationAssessmentApproverRequest[]: List of approvers for the assessment - `approverId` string, uuid, required: Unique identifier for the approver - `approverName` string: Display name of the approver - `comment` string: Optional comment for the approver assignment - `workflowStageIds` string[] - `templateId` string, uuid: Template identifier for which the assessment has to be created (mandatory if templateRootVersionId is not provided) - `templateRootVersionId` string, uuid: Template root version identifier for which the assessment has to be created - `templateType` 'PIA' | 'VENDOR' | 'RA' | 'GRA' | 'DINA' | 'BENCHMARKING' | 'ITRM' | 'CONTROL' | 'INCIDENT' | 'EXCHANGE' | 'ESG' | 'DISCLOSURE' | 'DISCLOSURE_YOY' | 'ERM' | 'TPDD' | 'AIGOVERNANCE' | 'DYNAMIC': Type of the template to use when creating the assessment. Used together with 'templateName' if templateId nor 'templateRootVersionId' is not provided - `templateName` string: Template name for which the assessment has to be created. Used together with 'templateType' if templateId nor 'templateRootVersionId' is not provided - `suggestedTemplateId` string, uuid: Suggested template identifier provided by AI agent - `suggestedTemplateName` string: Suggested template name provided by AI agent - `deadline` string, date-time: Deadline to complete the assessment (format: YYYY-MM-DDTHH:MM:SS.FFFZ) - `reminder` integer: 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` PrivacyAutomationAssessmentAutomationReminderScheduleDto[] - `id` string, uuid: Unique identifier for the reminder schedule. - `assessmentId` string, uuid: Identifier of the assessment this reminder schedule applies to. - `sectionId` string, uuid: Identifier of a specific assessment section this reminder schedule targets (optional). - `reminderInterval` integer: Interval in days between consecutive reminders. - `reminderReceiverEntityType` 'APPROVER' | 'RESPONDENT' | 'ALL', required: Recipient type who will receive the reminder notifications. - `respondents` PrivacyAutomationAssessmentAutomationAssessmentRespondentRequest[], required - `respondentId` string, uuid: Unique identifier for the respondent user - `respondentName` string, required: Display name of the respondent - `comment` string: Optional comment for the respondent assignment - `sectionIds` string[] - `isRespondentOfApproverSection` boolean: Flag indicating whether this respondent is assigned to approver sections - `approverOnlySectionRespondents` PrivacyAutomationAssessmentAutomationApproverOnlySectionRespondentRequest[]: List of respondents for approver-only sections - `respondentId` string, uuid: Id of the respondent for approver only sections - `respondentName` string: Name of the respondent for approver only sections - `respondentCreationType` 'INVITED' | 'PROJECT_RESPONDENT': Type of user creation for respondents - `inventoryDetails` PrivacyAutomationAssessmentAutomationAssessmentInventoryRequest - `inventoryId` string, uuid, required: Inventory ID for which the assessment is created - `inventoryTypeId` integer, required: Type of the inventory for which the assessment is created - `inventoryTypeName` string: type name of the inventory for which the assessment is created. - `inventoryNumber` integer, required: External number of the inventory for which the assessment is created - `inventoryName` string, required: Name of the inventory for which the assessment is created - `valid` boolean - `incidentDetails` PrivacyAutomationAssessmentAutomationAssessmentIncidentRequest - `incidentId` string, uuid, required: Unique identifier for the incident associated with the assessment - `incidentName` string, required: Name of the incident associated with the assessment - `controlImplementationDetails` PrivacyAutomationAssessmentAutomationControlImplementationRequest[]: Populated when Control Implementations are selected as Primary for Assessment - `controlImplementationId` string, uuid, required: Unique identifier for the control implementation - `controlImplementationName` string, required: Name of the control implementation - `controlImplementationNumber` integer: External number of the control implementation - `sourceId` string, uuid: Unique identifier for the source entity associated with the control implementation - `sourceName` string: Name of the source entity associated with the control implementation - `sourceType` 'APPLICATION' | 'SYSTEM' | 'DATABASE' | 'NETWORK' | 'INFRASTRUCTURE': Type of the source entity associated with the control implementation - `entityBusinessKey` string: Business key for the control implementation entity - `primaryEntityDetails` PrivacyAutomationAssessmentAutomationAssessableEntityDetail[]: Populated when Business Object needs to be selected as Primary for Assessment (except Inventory, Incident, Control Implementations and Engagements) - `id` string, uuid: ID of the assessable entity - `name` string: Name of the assessable entity - `number` integer: Number of the assessable entity - `relationshipResponseDetails` PrivacyAutomationAssessmentAutomationRelationshipResponseDetailsDto[] - `relationshipNodeType` string: Type of the relationship node - `entityId` string, uuid, required: Unique identifier of the related entity - `entityDisplayName` string: Display name of the related entity - `entityType` PrivacyAutomationAssessmentAutomationEntityTypeInformation, required - `id` string, uuid: Unique identifier of the entity type - `name` string: Name of the entity type - `nameKey` string: Translation key for the entity type name - `moduleName` string: Module name that owns this entity type - `schemaName` string: Schema name for this entity type - `seeded` boolean: Whether this entity type is seeded - `validEntityType` boolean - `displayName` string: Display name of the entity - `entityBusinessKey` string: Business Key of the entity - `primaryRecordTypeReference` string: Type of primary record when primaryEntityDetails are populated - `engagementLink` PrivacyAutomationAssessmentAutomationAssessmentEngagementLinkRequest - `engagementId` string, uuid, required: Engagement identifier for which the assessment is created - `engagementName` string, required: Name of the engagement linked to the assessment - `number` integer: Sequential number assigned to the engagement - `ruleId` string, uuid: Identifier of the rule that triggered this assessment creation - `triggeredByAssessmentId` string, uuid: Identifier of the assessment that triggered this assessment creation - `triggeredByAssessmentName` string: Name of the assessment that triggered this assessment creation - `tags` string[]: List of tag identifiers to attach to the assessment during creation - `userAssignmentMode` 'ASSESSMENT' | 'SECTION': Mode of user assignment for the assessment - `creationSource` 'RULE_ENGINE_ASSESSMENT_SOURCE' | 'DEFAULT' | 'COPY' | 'REASSESS' | 'BULK_IMPORT' | 'INVENTORY_STAGE_RULES' | 'PRIVACY_RISK_AGENT' | 'THIRD_PARTY_RISK_AGENT': Source of assessment creation - `checkForInFlightAssessments` boolean: Whether to check if any in-flight (status < COMPLETED) assessments exist with the same templateRootVersionId - `defaultTemplateDeadlineReminder` boolean - `labels` string[]: List of labels to attach to the assessment - `entityLabels` PrivacyAutomationAssessmentAutomationAssessmentQuestionLabelDto[]: List of entity attribute labels for the assessment - `name` string, required: Display name of the label - `nameKey` string: Internationalization key for the label name - `referenceEntity` 'DATA_CATEGORY' | 'PROCESSING_PURPOSE' | 'LEGAL_BASIS' | 'DATA_SUBJECT' | 'RETENTION_PERIOD' | 'TRANSFER_METHOD' | 'SECURITY_MEASURE': Type of the reference entity this label is associated with - `valueRefId` string, uuid: Unique identifier of the referenced entity value. Null for custom labels. - `valueKey` string: Internationalization key for the referenced entity value - `duplicateNotAllowed` boolean - `attachmentRequests` PrivacyAutomationAssessmentAutomationAssessmentAttachmentRequest[]: List of assessment attachment request - `attachmentId` string, uuid, required: Unique identifier for the attachment - `fileName` string, required: Name of the file being attached to the assessment - `fileDescription` string: Optional description of the attached file and its relevance to the assessment - `attachmentIntent` 'AI_CONTEXT' | 'QUESTION_EVIDENCE' | 'ASSESSMENT_LEVEL': Intent or purpose of the attachment. Defaults to QUESTION_EVIDENCE if not provided. - `recordAdminId` string, uuid: Identifier of the record admin for this assessment ## Response `200` OK - PrivacyAutomationAssessmentAutomationAssessmentBasicInformation - `assessmentId` string, uuid: UUID of the created assessment - `number` integer: Number of the created assessment - `name` string: Name of the created assessment - `assessmentDetailUrl` string: URL to open the assessment in the application. When oneAgent is true, the URL opens the assessment for the OneAgent stage-transition flow. - `assessmentDetailsFollowUpRequest` PrivacyAutomationAssessmentAutomationAssessmentDetailsFollowUpRequest[]: Follow-up requests to run after creation. Returned only when oneAgent is true. - `url` string: URL for the follow-up request to fetch assessment details - `method` string: HTTP method for the follow-up request - `requestObject` string: Request body object as a JSON string for the follow-up request ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `429`: Too Many Requests. For more information, see [API Rate Limits](https://developer.onetrust.com/onetrust/reference/rate-limits-overview). - `500`: Internal Server Error --- [API](https://skmtc.dev/onetrust/apis/privacy-automation-assessment-automation.md) - [All operations](https://skmtc.dev/onetrust/apis/privacy-automation-assessment-automation/llms.txt) - [OpenAPI document](https://skmtc.dev/onetrust/apis/privacy-automation-assessment-automation/revisions/fbdf0c71bfe5?raw)