GET Engagements

Retrieves a paginated and filtered list of engagements associated with the tenant.

Endpoint

Endpoint

/api/engagements

Method

GET

Scope

riskassess.engagement.read

Headers

Header Argument

Authorization

Bearer token

Accept

application/json or application/xml

X-Correlation-Id

(Optional) Request tracing ID

Parameters

Table 1. Query parameters
Parameter Required Description

limit

No

Maximum number of items to return. Default: 50, Maximum: 100.

offset

No

Number of items to skip from start. Default: 0.

order_by

No

Field name for sorting. Supported values: name, createDate, modifiedDate. Default: entityId.

dir

No

Sort direction. Values: Asc or Desc. Default: Asc.

includeDeleted

No

Include deleted engagements. Default: false.
Table 2. Filterable fields
API field Filter Sort (order_by)

name

Yes (contains, eq)

Yes

status

Yes (eq)

No

entityId

Yes (eq)

No

createDate

Yes (gt, lt)

Yes

modifiedDate

Yes (gt, lt)

Yes

engagementNumber

Yes (contains, eq)

No

classification

Yes (eq)

No

category

Yes (eq)

No
Tip: Example filter: /api/engagements?name[contains]=risk&limit=20&offset=0

Elements

The following elements are available in the response:

Element Data Type Available Options Description

success

boolean

Whether the request was successful.

totalCount

integer

Total number of engagements that match the filter criteria across all pages.

Note:

Use the limit and offset query parameters to retrieve additional sets of data if totalCount exceeds the page size.

result

array

Current page of engagement results, with up to 100 engagements per request (determined by limit and offset).

errors

array

List of error objects. Typically empty when the request is successful.

entityId

string (GUID)

Unique, permanent GUID that represents the engagement within the system.

name

string

Display name of the engagement.

status

string

Active, Inactive

Current status of the engagement.

createdAt

datetime

Date and time when the engagement was created.

modifiedAt

datetime

Date and time when the engagement was last modified.

engagementNumber

string

Unique business reference number for the engagement.

startEffectiveDate

datetime

Start date of the contract period.

classification

string

Strategic, Commodity, etc.

Configurable dropdown value indicating the engagement classification.

category

string

Services, etc.

Configurable dropdown value indicating the engagement category.

residualRisk

string

High, Medium, Low

Assessment of residual risk after controls are applied.

inherentRisk

string

High, Medium, Low

Assessment of inherent risk before controls are applied.

candidateSuppliers

array

Array of supplier objects being evaluated for the engagement. Each object contains entityId, name, and links.

organizations

array

Array of organization objects (business units, regions) participating in the engagement. Each object contains entityId, name, and links.

internalManager

object

User object representing the internal client manager responsible for the engagement. Contains entityId, name, and links.

links

array

Array of HATEOAS links to related resources.

Get engagements

Endpoint

GET /api/engagements

Example cURL request
curl --location 'https://<your-instance>.risk.com/api/engagements?limit=50&offset=0' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ••••••'
Example response
{
  "success": true,
  "totalCount": 150,
  "result": [
    {
      "entityId": "3a2edf76-ca80-46cc-bddd-761ecbbdd658",
      "name": "Supplier Onboarding Engagement",
      "status": "Active",
      "createdAt": "2026-01-15T10:30:00Z",
      "modifiedAt": "2026-04-17T14:20:00Z",
      "engagementNumber": "ENG-2026-001",
      "startEffectiveDate": "2026-02-01T00:00:00Z",
      "classification": "Strategic",
      "category": "Services",
      "residualRisk": "Medium",
      "inherentRisk": "High",
      "candidateSuppliers": [
        {
          "entityId": "guid",
          "name": "Acme Corp",
          "links": []
        }
      ],
      "organizations": [
        {
          "entityId": "guid",
          "name": "IT Department",
          "links": []
        }
      ],
      "internalManager": {
        "entityId": "guid",
        "name": "Doe, John",
        "links": []
      }
    }
  ],
  "errors": []
}
Example error response
{
  "success": false,
  "result": null,
  "errors": [
    {
      "message": "Invalid filter parameter",
      "errorCode": "ValidationError"
    }
  ]
}