CSP Intelligence API

Corporate services intelligence layer providing ownership graph traversal, UBO computation, temporal registers, compliance calendars, KYC expiry monitoring, stakeholder exposure analysis, and cross-workspace entity presence. All endpoints require the CSP addon to be installed and active.

Endpoints

Authorization: All endpoints require authentication. POST, PATCH, and DELETE require ADMIN or OWNER role. The CSP addon must be installed for these routes to be available.

Ownership Chain

Traverses the ownership graph upward from an entity, returning the chain of parent entities and computed UBOs (individuals who exceed the beneficial ownership threshold through direct or indirect holdings).

GET /api/csp/graph/ownership/:entityId?threshold=25&maxDepth=10

Query Parameters

Response

{
  "chain": [
    {
      "entityId": "cm...",
      "legalName": "Alpha Holdings Ltd",
      "jurisdiction": "ADGM",
      "depth": 0,
      "parents": [
        {
          "entityId": "cm...",
          "legalName": "Beta Group PLC",
          "ownershipPercentage": 75,
          "roleType": "SHAREHOLDER"
        }
      ]
    }
  ],
  "ubos": [
    {
      "individualId": "cm...",
      "fullName": "John Smith",
      "nationality": "GB",
      "totalOwnership": 75,
      "paths": [["Beta Group PLC", "Alpha Holdings Ltd"]],
      "isDeclared": true,
      "declaredMatch": true
    }
  ]
}

Registers

Temporal register model with immutable entries. Each entry has effectiveFrom / effectiveTo dates for point-in-time register reconstruction. Supports five register types.

GET /api/csp/registers/:entityId?registerType=DIRECTORS
GET /api/csp/registers/:entityId?registerType=DIRECTORS&asAtDate=2025-06-30

Register Types

Response

{
  "entityId": "cm...",
  "registerType": "DIRECTORS",
  "asAtDate": "current",
  "entries": [
    {
      "id": "cm...",
      "registerType": "DIRECTORS",
      "holderType": "INDIVIDUAL",
      "holderName": "Jane Doe",
      "roleTitle": "Director",
      "appointmentDate": "2024-01-15",
      "effectiveFrom": "2024-01-15T00:00:00.000Z",
      "effectiveTo": null,
      "isCurrent": true,
      "metadata": { "nationality": "AE", "residency": "UAE" }
    }
  ],
  "count": 1
}

UBO Analysis

Ultimate Beneficial Owner computation via recursive graph traversal. Compares computed UBOs against declared UBO records to flag mismatches. Snapshots are materialised and stored for audit trail.

GET /api/csp/ubos/:entityId?threshold=25
GET /api/csp/ubos/mismatches
POST /api/csp/ubos/compute  { "entityId": "cm..." }

Mismatch detection: The system automatically compares computed UBOs (from ownership graph traversal) against declared UBOs (from register entries). When they diverge, a mismatch record is created with details of the discrepancy.

Compliance Calendar

Jurisdiction-aware compliance obligations computed from obligation rules. Supports ADGM, DIFC, and Cayman jurisdictions with rule types including annual returns, audited accounts, KYC renewals, UBO declarations, and economic substance reporting.

GET /api/csp/compliance/calendar?entityId=cm...&fromDate=2026-01-01&toDate=2026-12-31
GET /api/csp/compliance/summary/:entityId

Obligation Statuses

Response

{
  "obligations": [
    {
      "id": "cm...",
      "entityId": "cm...",
      "entity": { "legalName": "Alpha Holdings Ltd" },
      "obligationType": "ANNUAL_RETURN",
      "title": "Annual Return Filing",
      "dueDate": "2026-06-30T00:00:00.000Z",
      "status": "UPCOMING",
      "jurisdiction": "ADGM",
      "notes": null
    }
  ],
  "total": 12
}

KYC Expiry Report

Scans all KYC documents across the workspace and reports documents expiring within a configurable window. Integrates with the document intelligence extraction pipeline - when documents are uploaded and extracted, KYC fields (passport numbers, expiry dates, etc.) are auto-populated.

GET /api/csp/compliance/kyc-expiry?daysAhead=90

Response

{
  "expiring": [
    {
      "id": "cm...",
      "holderIndividual": { "fullName": "John Smith" },
      "documentType": "passport",
      "documentNumber": "AB1234567",
      "expiryDate": "2026-05-15T00:00:00.000Z",
      "daysUntilExpiry": 70,
      "status": "pending_review"
    }
  ],
  "expired": [],
  "summary": { "expiringCount": 1, "expiredCount": 0 }
}

Stakeholder Exposure

Analyses an individual's exposure across entities - all roles held, entities connected to, jurisdictions involved, and potential conflicts. Also supports finding stakeholders shared across multiple entities.

GET /api/csp/stakeholders/exposure/:individualId
GET /api/csp/stakeholders/shared?minEntities=3

Document Coverage

Analyses document coverage for a CSP entity: KYC files per active stakeholder, evidence files linked to the company row, extraction status, expiry dates, and an overall coverage score (0.0 to 1.0).

GET /api/csp/entities/:entityId/document-coverage

Response Fields

Cross-Workspace Presence

Entity presence advertises aggregated relationship data via global identity records without revealing entity names or workspace details. Oversight workspaces can query the unified stakeholder view to see an individual's presence across supervised workspaces.

GET /api/csp/presence/:globalIdentityId
GET /api/csp/presence/unified/:globalIdentityId

Response

{
  "globalIdentityId": "cm...",
  "presenceRecords": [
    {
      "workspaceId": "cm...",
      "roleTypes": ["DIRECTOR", "SHAREHOLDER"],
      "entityCount": 3,
      "jurisdictions": ["ADGM", "DIFC"],
      "hasActiveKyc": true,
      "kycExpiryWarning": false,
      "lastUpdated": "2026-03-01T12:00:00.000Z"
    }
  ]
}

Entity Events

Immutable audit trail of entity and stakeholder state changes. Events drive downstream effects: ownership changes trigger UBO recomputation, compliance changes recompute obligations, and role changes refresh cross-workspace presence.

GET /api/csp/events?entityId=cm...&eventCategory=OWNERSHIP_CHANGE&limit=50

Event Categories

Obligation Rules

Jurisdiction-specific compliance rules that generate obligations for entities. Pre-seeded with 18 rules across ADGM (6), DIFC (6), and Cayman (6). Custom workspace-level rules can be added.

GET /api/csp/rules
POST /api/csp/rules  { "jurisdiction": "ADGM", "ruleType": "ANNUAL_RETURN", ... }
PATCH /api/csp/rules/:id  { "isActive": false }
DELETE /api/csp/rules/:id

Document Intelligence Integration

The CSP intelligence layer integrates with the document intelligence extraction pipeline. When files linked to CSP entities or individuals are extracted:

• Extraction classes (passport number, expiry date, etc.) are mapped to KYC document fields
• KYC document records are auto-populated or updated (never overwriting manually-entered data)
• Entity events are fired for the audit trail
• Cross-workspace entity presence is refreshed

Supported fields: Passport, Emirates ID, visa, and generic document fields, plus entity fields (company name, registration number, incorporation date) and individual fields (full name, date of birth, nationality). Field name synonyms are normalised automatically.

AI Tools

When the CSP addon is active, 13 AI tools become available in the AI assistant. These are listed in the AI Tools Reference.