---
title: "Create Engagement"
method: POST
path: "/api/vendor/v1/vendor-engagements"
tags: ["Engagements"]
---

# Create Engagement

`POST /api/vendor/v1/vendor-engagements`

Use this API to create a new engagement.

> 🗒 Things to Know
>
> - For date and time attributes, the formatting should follow the `YYYY-MM-DDTHH:MM:SSZ` format.
> - If the `orgGroupId` parameter is not passed in the request, the engagement will be created with the same organization assigned to the engagement's vendor. If the `orgGroupId` parameter value is invalid, then an invalid organization error will be sent.
> - The name of the engagement must be 500 characters or less.

## Request body

- ExternalEngagementCreateRequest
  - `name` string, required — The name for new engagement creation.
  - `vendor` Key, required
    - `id` string, uuid — The vendor identifier in results.
    - `name` string, required — The vendor name in results.
    - `orgGroupId` string, uuid, required — The vendor organization in results.
    - `orgGroupName` string — The vendor organization name in results.
    - `vendorType` InventoryValue
      - `id` string, uuid — The GUID of the Inventory Type.
      - `value` string — The Value of the Inventory Type.
      - `valueKey` string — Translation key used for localizing the value
  - `orgGroupId` string, uuid — The organization identifier for new engagement.
  - `type` 'VendorEngagement' | 'ProductEngagement' | 'ServiceEngagement' — The type for new engagement creation.
  - `internalOwnerEmail` string, email — The internal owner email for new engagement.
  - `externalContact` string — The external contact for new engagement.
  - `notes` string — The notes for new engagement creation.
  - `startDate` string, date — The start date for new engagement.
  - `endDate` string, date — The end date for new engagement.
  - `scope` string — The scope for new engagement creation.
  - `attributeValues` object — The custom attributes for new engagement.

## Response `201`

Created

- EngagementDetailInformation
  - `engagementId` string, uuid — The engagement identifier for created response.
  - `number` integer — The sequential number of created engagement.
  - `name` string — The name of created engagement.
  - `orgGroupName` string — The organization name of created engagement.
  - `orgGroupId` string, uuid — The organization identifier of created engagement.
  - `type` 'VendorEngagement' | 'ProductEngagement' | 'ServiceEngagement' — The type of created engagement.
  - `startDate` string, date — The start date of created engagement.
  - `endDate` string, date — The end date of created engagement.
  - `internalOwnerId` string, uuid — The internal owner identifier of created engagement.
  - `internalOwnerUser` string — The internal owner name of created engagement.
  - `internalOwnerEmail` string, email — The internal owner email of created engagement.
  - `externalContact` string — The external contact of created engagement.
  - `notes` string — The notes of created engagement.
  - `scope` string — The scope of created engagement.
  - `schemaId` string, uuid — The schema identifier of created engagement.
  - `vendor` Key
    - `id` string, uuid — The vendor identifier in results.
    - `name` string, required — The vendor name in results.
    - `orgGroupId` string, uuid, required — The vendor organization in results.
    - `orgGroupName` string — The vendor organization name in results.
    - `vendorType` InventoryValue
      - `id` string, uuid — The GUID of the Inventory Type.
      - `value` string — The Value of the Inventory Type.
      - `valueKey` string — Translation key used for localizing the value
  - `workflow` EngagementWorkflowInformation
    - `id` string, uuid — The workflow identifier in results.
    - `nameKey` string — The workflow translation key in results.
    - `name` string — The workflow name in results.
    - `stageId` string, uuid — The workflow stage identifier in results.
    - `stageNameKey` string — The workflow stage key in results.
    - `stageName` string — The workflow stage name in results.
    - `stageBadgeColor` string — The workflow stage color in results.
  - `attributeValues` object — The custom attributes of created engagement.
  - `viewOnly` boolean — The view access flag of created engagement.
  - `forceAbac` boolean — The organizational context flag of created engagement.
  - `riskLevel` 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL' — The risk level of created engagement.
  - `riskScore` number — The risk score of created engagement.
  - `inherentRiskLevel` 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL' — The inherent risk level of created engagement.
  - `inherentRiskScore` number — The inherent risk score of created engagement.
  - `targetRiskLevel` 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL' — The target risk level of created engagement.
  - `targetRiskScore` number — The target risk score of created engagement.
  - `engagementStatus` 'ACTIVE' | 'PENDING' | 'ARCHIVED' — The status of created engagement.
  - `lastUpdatedDate` string, date-time — The last update date of created engagement.
  - `createdDate` string, date-time — The creation date of created engagement.
  - `createdBy` string, uuid — The creator identifier of created engagement.
  - `createdByUser` string — The creator name of created engagement.
  - `updatedBy` string, uuid — The updater identifier of created engagement.
  - `updatedByUser` string — The updater name of created engagement.
  - `label` string — The display label of created engagement.

## 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.net/onetrust/apis/platform-access-management.md) · [All operations](https://skmtc.net/onetrust/apis/platform-access-management/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/onetrust/platform-access-management/revisions/21de3aa0b170/schema)