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.

This is a read-only surface in v1. Creating, updating, and terminating engagements happens in the Novantra UI (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. The party record itself is not currently a v1 endpoint; integrations needing party identity detail look it up in the in-product UI today.

Snapshots

Engagements, due diligence reviews, right-to-audit records, supplier assurance reviews, and service reviews all carry rich encrypted snapshots in the in-product UI (service scope, methodology, findings detail). In v1 these structured snapshots are not exposed in the API surface; 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.