Party Engagements

The Party Engagements endpoints expose your governed third-party register: each engagement with an external party, plus the due diligence reviews, right-to-audit records, supplier assurance reviews, and service reviews associated with it.

These endpoints provide read access to the register. Creating, updating, and terminating engagements happens in the Novantra workspace (see the Party Engagements user guide).

For shared conventions (auth, errors, pagination, ID format), read v1 conventions first.

Scope required

Endpoints

List party engagements

GET /api/v1/party-engagements
Authorization: Bearer <access-token>

Query parameters:

Response:

{
  "engagements": [
    {
      "id": "peng_01HXY...",
      "engagementKey": "manufacturer-partner-a-msa-2026",
      "engagementKind": "supplier",
      "title": "Manufacturing partner A master agreement",
      "providerPartyId": "party_01HXY...",
      "status": "active",
      "ownerResponsibilityId": "ra_01HXY...",
      "createdAt": "2026-01-15T08:21:43.000Z",
      "updatedAt": "2026-05-25T14:08:33.000Z"
    }
  ],
  "pagination": {}
}

Get one engagement

GET /api/v1/party-engagements/:engagementId
Authorization: Bearer <access-token>

Returns the single-engagement shape from the list above.

List due diligence reviews

GET /api/v1/party-engagements/due-diligence-reviews
Authorization: Bearer <access-token>

Query parameters:

Response:

{
  "dueDiligenceReviews": [
    {
      "id": "pengdd_01HXY...",
      "engagementId": "peng_01HXY...",
      "reviewKey": "manufacturer-partner-a-onboarding-dd-2026-Q1",
      "reviewKind": "onboarding",
      "status": "completed",
      "performedAt": "2026-01-22T10:00:00.000Z",
      "createdAt": "2026-01-10T08:21:43.000Z",
      "updatedAt": "2026-01-22T10:30:00.000Z"
    }
  ],
  "pagination": {}
}

List right-to-audit records

GET /api/v1/party-engagements/right-to-audit
Authorization: Bearer <access-token>

Query parameters:

Response:

{
  "rightToAuditRecords": [
    {
      "id": "pengrta_01HXY...",
      "engagementId": "peng_01HXY...",
      "recordKey": "manufacturer-partner-a-msa-rta-clause-7-3",
      "status": "active",
      "lastExercisedAt": "2025-09-15T00:00:00.000Z",
      "nextPlannedExerciseAt": "2026-09-15T00:00:00.000Z",
      "createdAt": "2024-01-15T08:21:43.000Z",
      "updatedAt": "2025-09-20T14:08:33.000Z"
    }
  ],
  "pagination": {}
}

Field notes

engagementKind

Free text. Common values: supplier, processor, outsourcing, subcontractor, joint-venture, professional-services, agent.

providerPartyId

Points at the party record (in the Party module) that identifies the provider. Party identity detail is available in the Novantra workspace; integrations needing it can look it up there.

Snapshots

Engagements, due diligence reviews, right-to-audit records, supplier assurance reviews, and service reviews all carry rich encrypted snapshots in the Novantra workspace (service scope, methodology, findings detail). These API reads return the durable identifying fields.

Real-case integration: surfacing supplier risk posture in a procurement system

A procurement system makes vendor selection and renewal decisions. The procurement team wants the governance posture of each vendor visible in the procurement system at the moment of decision: active engagement, recent due diligence outcome, next supplier assurance review, open findings.

The integration:

1. Calls GET /api/v1/party-engagements?status=active to pull active engagements.
2. For each engagement of interest, calls GET /api/v1/party-engagements/due-diligence-reviews?engagementId=<id> to pull the latest due diligence review.
3. Joins on the procurement system’s own vendor table using providerPartyId as the key (the procurement system maintains its own party-to-vendor mapping).
4. Surfaces a “governance posture” widget on each vendor page in the procurement system: green for engagements with recent, clean reviews; amber for engagements with stale or limited reviews; red for engagements without an active due diligence.

The service account holds party-engagements:read and governance.findings:read (to surface open findings against the engagement’s controls). Daily refresh is sufficient; per-vendor lookups against the cached register are fast.

A complementary pattern: a contract management system that reads the right-to-audit records to remind contract owners of approaching scheduled exercises.

Related

• Party Engagements user guide - what the module does and when to reach for it.
• v1 conventions - shared request and response patterns.
• Authentication - service accounts and scopes.