---
title: "Update Engagement"
method: PUT
path: "/api/vendor/v1/engagements/{engagementId}"
tags: ["Engagements"]
---

# Update Engagement

`PUT /api/vendor/v1/engagements/{engagementId}`

## Request

- Base URL: `https://hostname`
- URL: `https://hostname/api/vendor/v1/engagements/{engagementId}`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://{hostname}/api/access/v1/oauth/token` scopes: `GENERIC`, `VRM`

Use this API to update an existing engagement.

> 🗒 Things to Know
> 
> - For date and time attributes, the formatting should follow the `YYYY-MM-DDTHH:MM:SSZ` format.
> - An engagement's workflow or stage cannot be updated using this API.
> - 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.

## Path parameters

- `engagementId` string, uuid, required

## Request body

- ExternalEngagementUpdateRequest
  - `name` string, required: The updated name of the engagement.
  - `orgGroupId` string, uuid: The organization identifier for engagement.
  - `internalOwnerEmail` string, email: The email of internal owner for engagement.
  - `externalContact` string: The external contact for the engagement.
  - `notes` string: The notes about the engagement.
  - `startDate` string, date: The start date of the engagement.
  - `endDate` string, date: The end date of the engagement.
  - `scope` string: The scope of the engagement.
  - `attributeValues` object: The custom attributes for the engagement.

## Response `200`

OK

- 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.dev/onetrust/apis/third-party-management-third-party-risk-management.md) - [All operations](https://skmtc.dev/onetrust/apis/third-party-management-third-party-risk-management/llms.txt) - [OpenAPI document](https://skmtc.dev/onetrust/apis/third-party-management-third-party-risk-management/revisions/64a31041f3ef?raw)