Sign in

v1

latestOpenAPI 3.1.0Apache 2.02026-07-245981,1853.0 MB
Engagements

Update Engagement

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.
put/api/vendor/v1/engagements/{engagementId}

Path parameters

engagementIdstring uuid required
Example:fbf7843d-bc3c-4ad7-86c7-f6c9a94e873e

The unique identifier of an engagement. The value can be obtained using the Get Engagements API.

Request body

namestring required

The updated name of the engagement.

orgGroupIdstring uuid

The organization identifier for engagement.

internalOwnerEmailstring email

The email of internal owner for engagement.

externalContactstring

The external contact for the engagement.

notesstring

The notes about the engagement.

startDatestring date

The start date of the engagement.

endDatestring date

The end date of the engagement.

scopestring

The scope of the engagement.

attributeValuesobject

The custom attributes for the engagement.

Example request

{
  "name": "Microsoft Azure Cloud Services 2025 - Enterprise Agreement",
  "orgGroupId": "a41972ae-2050-4126-b314-1a58d08ea116",
  "internalOwnerEmail": "john.doe@company.com",
  "externalContact": "Jane Smith (jane.smith@microsoft.com, +1-555-123-4567)",
  "notes": "This engagement covers all Microsoft Azure cloud services used by our IT department. Updated to include new security features and compliance requirements.",
  "startDate": "2025-01-15",
  "endDate": "2026-01-14",
  "scope": "License agreement for Azure cloud services covering the IT business unit only. Updated to include additional data centers and expanded support services.",
  "attributeValues": {
    "priority": [
      {
        "id": "c5c3167e-f8e2-4719-a0a1-491350507fee",
        "value": "High"
      }
    ],
    "department": [
      {
        "id": "d6d4278f-g9f3-5820-b1b2-592461608gff",
        "value": "IT"
      }
    ],
    "complianceLevel": [
      {
        "id": "e7e5389g-h0g4-6931-c2c3-603572719hgg",
        "value": "Enterprise"
      }
    ]
  }
}

Response

OK

engagementIdstring uuid

The engagement identifier for created response.

numberinteger

The sequential number of created engagement.

namestring

The name of created engagement.

orgGroupNamestring

The organization name of created engagement.

orgGroupIdstring uuid

The organization identifier of created engagement.

type'VendorEngagement' | 'ProductEngagement' | 'ServiceEngagement'

The type of created engagement.

startDatestring date

The start date of created engagement.

endDatestring date

The end date of created engagement.

internalOwnerIdstring uuid

The internal owner identifier of created engagement.

internalOwnerUserstring

The internal owner name of created engagement.

internalOwnerEmailstring email

The internal owner email of created engagement.

externalContactstring

The external contact of created engagement.

notesstring

The notes of created engagement.

scopestring

The scope of created engagement.

schemaIdstring uuid

The schema identifier of created engagement.

attributeValuesobject

The custom attributes of created engagement.

viewOnlyboolean

The view access flag of created engagement.

forceAbacboolean

The organizational context flag of created engagement.

riskLevel'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL'

The risk level of created engagement.

riskScorenumber

The risk score of created engagement.

inherentRiskLevel'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL'

The inherent risk level of created engagement.

inherentRiskScorenumber

The inherent risk score of created engagement.

targetRiskLevel'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL'

The target risk level of created engagement.

targetRiskScorenumber

The target risk score of created engagement.

engagementStatus'ACTIVE' | 'PENDING' | 'ARCHIVED'

The status of created engagement.

lastUpdatedDatestring date-time

The last update date of created engagement.

createdDatestring date-time

The creation date of created engagement.

createdBystring uuid

The creator identifier of created engagement.

createdByUserstring

The creator name of created engagement.

updatedBystring uuid

The updater identifier of created engagement.

updatedByUserstring

The updater name of created engagement.

labelstring

The display label of created engagement.

Example response

{
  "engagementId": "41aa71ae-0ace-4073-8947-e6941714bcf1",
  "number": 12345,
  "name": "Microsoft Azure",
  "orgGroupName": "Corporate",
  "orgGroupId": "a41972ae-2050-4126-b314-1a58d08ea116",
  "type": "VendorEngagement",
  "startDate": "2020-10-12",
  "endDate": "2021-06-30",
  "internalOwnerId": "20a61b02-482a-44b6-8bc3-be1d4c83331f",
  "internalOwnerUser": "John Smith",
  "internalOwnerEmail": "test@example.com",
  "externalContact": "Jane Doe (jane.doe@vendor.com)",
  "notes": "This engagement is for Microsoft Office.",
  "scope": "License agreement for the IT business unit only.",
  "schemaId": "36e2d4a1-379f-4263-8e05-6e3a3207a834",
  "vendor": {
    "id": "cd7f767c-c849-412c-abbb-b59845cd5476",
    "name": "Microsoft",
    "orgGroupId": "cd7f767c-c849-412c-abbb-b59845cd5476",
    "vendorType": {
      "id": "41aa71ae-0ace-4073-8947-e6941714bcf1",
      "value": "Technology",
      "valueKey": "VendorsTypeTechnology"
    }
  },
  "workflow": {
    "id": "8ac1bf26-fa0d-43d2-9a1b-81130673030c",
    "nameKey": "DefaultEngagementWorkflow",
    "name": "Default Engagement Workflow",
    "stageId": "c6ce7a8b-de4d-4707-924b-d283f273fe2c",
    "stageNameKey": "New",
    "stageName": "New",
    "stageBadgeColor": "blue"
  },
  "attributeValues": {
    "priority": [
      {
        "id": "c5c3167e-f8e2-4719-a0a1-491350507fee",
        "value": "High"
      }
    ],
    "department": [
      {
        "id": "d6d4278f-g9f3-5820-b1b2-592461608gff",
        "value": "IT"
      }
    ]
  },
  "riskLevel": "MEDIUM",
  "riskScore": 2.5,
  "inherentRiskLevel": "HIGH",
  "inherentRiskScore": 3.7,
  "targetRiskLevel": "LOW",
  "targetRiskScore": 1.2,
  "engagementStatus": "ACTIVE",
  "lastUpdatedDate": "2023-05-10T14:30:00Z",
  "createdDate": "2023-01-15T09:20:00Z",
  "createdBy": "8a732373-9713-4f93-98f6-cae431e61956",
  "createdByUser": "Admin User",
  "updatedBy": "8a732373-9713-4f93-98f6-cae431e61956",
  "updatedByUser": "Admin User",
  "label": "(Microsoft) Azure Cloud Services | Corporate"
}