v1

latestOpenAPI 3.1.0Apache 2.02026-07-245981,1853.0 MB

Engagements

Create Engagement

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.

post/api/vendor/v1/vendor-engagements

Request body

namestring required

The name for new engagement creation.

orgGroupIdstring uuid

The organization identifier for new engagement.

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

The type for new engagement creation.

internalOwnerEmailstring email

The internal owner email for new engagement.

externalContactstring

The external contact for new engagement.

notesstring

The notes for new engagement creation.

startDatestring date

The start date for new engagement.

endDatestring date

The end date for new engagement.

scopestring

The scope for new engagement creation.

attributeValuesobject

The custom attributes for new engagement.

Example request

{
  "name": "Microsoft Azure Cloud Services 2025",
  "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"
    }
  },
  "orgGroupId": "a41972ae-2050-4126-b314-1a58d08ea116",
  "type": "VendorEngagement",
  "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. Includes premium support package and training services.",
  "startDate": "2025-01-15",
  "endDate": "2026-01-14",
  "scope": "License agreement for Azure cloud services covering the IT business unit only. Includes 24/7 technical support and quarterly service reviews.",
  "attributeValues": {
    "priority": [
      {
        "id": "c5c3167e-f8e2-4719-a0a1-491350507fee",
        "value": "High"
      }
    ],
    "department": [
      {
        "id": "d6d4278f-g9f3-5820-b1b2-592461608gff",
        "value": "IT"
      }
    ]
  }
}

Response

Created

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"
}