Migration Guide: The New Entity-Role Model

Overview

The TradeVest API has been restructured to improve clarity and separation of concerns. The monolithic customers.yaml has been split into two specialized APIs:

• entities.yaml: Manages entity data (natural persons, legal entities, joint persons, beneficial owners, legal representatives)

• roles.yaml: Manages role assignments (customers, proxies)

Quick Reference: Endpoint Mapping

General

Old Endpoint (customers.yaml)	New Endpoint (entities.yaml)	Change Type
GET /partner-details	GET /v2/partner-details	✏️ Path change

Natural Persons

Old Endpoint (customers.yaml)	New Endpoint (entities.yaml)	Change Type
GET /natural-persons	GET /entities/natural-persons	✏️ Path change
POST /natural-persons	POST /entities/natural-persons	✏️ Path change
GET /natural-persons/{id}	GET /entities/natural-persons/{id}	✏️ Path change
PATCH /natural-persons/{id}	PATCH /entities/natural-persons/{id}	✏️ Path change
POST /natural-persons/{id}/identification	POST /entities/natural-persons/{id}/identification	✏️ Path change

Beneficial Owners

Old Endpoint (customers.yaml)	New Endpoint (entities.yaml)	Change Type
POST /customers/natural-persons/{customerId}/beneficial-owners	POST /entities/{legalEntityId}/beneficial-owners	🔄 Breaking change
GET /customers/natural-persons/{customerId}/beneficial-owners	GET /entities/{legalEntityId}/beneficial-owners	🔄 Breaking change
GET /customers/natural-persons/{customerId}/beneficial-owners/{id}	GET /entities/beneficial-owners/{id}	🔄 Breaking change
PATCH /customers/natural-persons/{customerId}/beneficial-owners/{id}	PATCH /entities/beneficial-owners/{id}	🔄 Breaking change

Important: Beneficial owners are now associated directly with legal entities, not with customer roles.

Legal Entities

Old Endpoint (customers.yaml)	New Endpoint (entities.yaml + roles.yaml)	Change Type
POST /customers/legal-entities	🔀 Split → ➕ POST /entities/legal-entities + POST /roles/customers	🔄 Breaking change
GET /customers/legal-entities/{customerId}	GET /roles/customers/{customerId} (role data) + GET /entities/legal-entities/{id} (entity data)	🔄 Breaking change
PATCH /customers/legal-entities/{customerId}	PATCH /roles/customers/{customerId} + PATCH /entities/legal-entities/{id}	🔄 Breaking change
GET /customers/vendor/search/legal-entities	GET /entities/vendor/legal-entities	✏️ Path change
POST /customers/vendor/prepare/legal-entities	POST /entities/vendor/legal-entities	✏️ Path change
GET /customers/vendor/prepare/legal-entities/{searchId}	GET /entities/vendor/legal-entities/{searchId}	✏️ Path change

Important: Legal entities are now independent entities with their own UUID and status, no longer embedded as customer sub-objects. They have dedicated endpoints for full CRUD operations.

Legal Representatives

Old Endpoint (customers.yaml)	New Endpoint (entities.yaml)	Change Type
Inline in POST /customers/legal-entities	➕ POST /entities/{legalEntityId}/legal-representatives	🔄 Breaking change
Inline in GET /customers/legal-entities/{id}	➕ GET /entities/{legalEntityId}/legal-representatives	🔄 Breaking change
Inline in PATCH /customers/legal-entities/{id}	➕ GET /entities/legal-representatives/{id}	🔄 Breaking change
-	➕ PATCH /entities/legal-representatives/{id}	➕ New endpoint
-	➕ DELETE /entities/legal-representatives/{id}	➕ New endpoint

Important: Legal representatives are no longer embedded in legal entity payloads. They have dedicated endpoints for full CRUD operations.

Joint Persons

Old Endpoint (customers.yaml)	New Endpoint (entities.yaml)	Change Type
POST /customers/joint-persons	🔀 Split → ➕ POST /entities/joint-persons + POST /roles/customers	🔄 Breaking change
GET /customers/joint-persons/{customerId}	🔀 Split → ➕ GET /roles/customers/{customerId} + GET /entities/joint-persons/{id}	🔄 Breaking change
PATCH /customers/joint-persons/{customerId}	PATCH /roles/customers/{customerId} + PATCH /entities/joint-persons/{id}	🔄 Breaking change
-	GET /entities/joint-persons	➕ New endpoint

Important: Joint persons are now independent entities with their own UUID and status, no longer embedded as customer sub-objects. They require separate entity creation and customer role assignment.

Customers (Role Management)

Old Endpoint (customers.yaml)	New Endpoint (roles.yaml)	Change Type
GET /customers	GET /roles/customers	🔄 Breaking change
GET /customers/{customerId}	GET /roles/customers/{customerId}	✏️ Path change
POST /customers/natural-persons	🔀 Split → ➕ POST /entities/legal-entities + POST /roles/customers	🔄 Breaking change
POST /customers/joint-persons	🔀 Split → ➕ POST /entities/joint-persons + POST /roles/customers	🔄 Breaking change
PATCH /customers/natural-persons/{customerId}	PATCH /roles/customers/{customerId}	✏️ Path change
PATCH /customers/joint-persons/{customerId}	PATCH /roles/customers/{customerId}	✏️ Path change

Proxies

Old Endpoint (customers.yaml)	New Endpoint (roles.yaml)	Change Type
POST /natural-persons/{naturalPersonId}/proxy	POST /roles/proxies	🔄 Breaking change
GET /proxies	GET /roles/proxies	✏️ Path change
GET /proxies/{proxyId}	GET /roles/proxies/{proxyId}	✏️ Path change
PATCH /proxies/{proxyId}	PATCH /roles/proxies/{proxyId}	✏️ Path change

Customer Labels

Old Endpoint (customers.yaml)	New Endpoint (roles.yaml)	Change Type
GET /customer-labels	GET /roles/customer-labels	✏️ Path change
PATCH /customer-labels/{labelName}	PATCH /roles/customer-labels/{labelName}	✏️ Path change
DELETE /customer-labels/{labelName}	DELETE /roles/customer-labels/{labelName}	✏️ Path change
PATCH /customer-labels/{labelName}/customers	PATCH /roles/customer-labels/{labelName}/customers	✏️ Path change
POST /customer-labels/{labelName}/customers	POST /roles/customer-labels/{labelName}/customers	✏️ Path change

Identification Verification

Old Endpoint (customers.yaml)	New Endpoint (entities.yaml)	Change Type
POST /identification-verifications	POST /entities/identification-verifications	✏️ Path change
GET /identification-verifications	GET /entities/identification-verifications	✏️ Path change
GET /identification-verifications/{id}	GET /entities/identification-verifications/{id}	✏️ Path change

Documents

Old Endpoint (customers.yaml)	New Endpoint (documents.yaml)	Change Type
GET /documents	GET /v2/documents	🔄 Breaking change
POST /documents	POST /v2/documents	🔄 Breaking change
GET /documents/{id}	GET /v2/documents/{id}	✏️ Path change
GET /documents/{id}/file	GET /v2/documents/{id}/file	✏️ Path change
POST /documents/sign	POST /v2/documents/sign	✏️ Path change

Important: Document model has changed - entityType → resourceType with new enum values and improved resource categorization.

Onboarding & Offboarding (Centralized → Distributed)

Old Endpoint (onboardings.yaml)	New Endpoint (entities.yaml + roles.yaml)	Change Type
POST /onboardings	POST /entities/onboardings OR POST /roles/onboardings OR POST /user-onboardings	🔄 Breaking change
GET /onboardings	GET /entities/onboardings OR GET /roles/onboardings OR GET /user-onboardings	🔄 Breaking change
GET /onboardings/{id}	GET /entities/onboardings/{id} OR GET /roles/onboardings/{id} OR GET /user-onboardings/{id}	🔄 Breaking change
POST /offboardings	POST /entities/offboardings OR POST /roles/offboardings	🔄 Breaking change
GET /offboardings	GET /entities/offboardings OR GET /roles/offboardings	🔄 Breaking change
GET /offboardings/{id}	GET /entities/offboardings/{id} OR GET /roles/offboardings/{id}	🔄 Breaking change
DELETE /offboardings/{id}	DELETE /entities/offboardings/{id} OR DELETE /roles/offboardings/{id}	🔄 Breaking change

Important: Onboarding is now dorelease-test-specific. Use entities.yaml for entity onboarding (beneficial owners), roles.yaml for role onboarding (customers, proxies) and users.yaml for user onboarding..

Search NACE Sectors

Old Endpoint (customers.yaml)	New Endpoint (entities.yaml)	Change Type
GET /customers/natural-persons/search/nace-sectors	GET /entities/natural-persons/search/nace-sectors	✏️ Path change
GET /customers/legal-entities/search/nace-sectors	GET /entities/legal-entities/search/nace-sectors	✏️ Path change

Customer Statistics

Old Endpoint (customers.yaml)	New Endpoint (roles.yaml)	Change Type
GET /customers/status-counts	GET /roles/customers/statistics/status-counts	✏️ Path change

Natural Person Wizard (Completely Removed)

Old Endpoint (customers.yaml)	New Endpoint	Change Type
POST /customers/natural-persons/wizard	-	❌ Removed
GET /customers/natural-persons/wizard	-	❌ Removed
GET /customers/natural-persons/wizard/{wizardInstanceId}	-	❌ Removed
PATCH /customers/natural-persons/wizard/{wizardInstanceId}	-	❌ Removed
DELETE /customers/natural-persons/wizard/{wizardInstanceId}	-	❌ Removed

Important: Natural person wizard functionality has been completely removed. Use the comprehensive onboarding process available in entities.yaml and roles.yaml instead.

New Endpoints (Not Available in customers.yaml)

Entity Management

• GET /entities - Unified view of all entities

• GET /entities/legal-representatives/{id} - Get specific legal representative

• PATCH /entities/legal-representatives/{id} - Update legal representative

• DELETE /entities/legal-representatives/{id} - Delete legal representative

• POST /entities/{legalEntityId}/legal-representatives - Create legal representative

• GET /entities/{legalEntityId}/legal-representatives - List legal representatives

Onboarding & Offboarding

• POST /entities/onboardings - Start entity onboarding

• GET /entities/onboardings - List entity onboardings

• GET /entities/onboardings/{id} - Get entity onboarding

• POST /entities/offboardings - Start entity offboarding

• GET /entities/offboardings - List entity offboardings

• GET /entities/offboardings/{id} - Get entity offboarding

• DELETE /entities/offboardings/{id} - Cancel entity offboarding

Role Onboarding & Offboarding

• POST /roles/onboardings - Start role onboarding

• GET /roles/onboardings - List role onboardings

• GET /roles/onboardings/{id} - Get role onboarding

• POST /roles/offboardings - Start role offboarding

• GET /roles/offboardings - List role offboardings

• GET /roles/offboardings/{id} - Get role offboarding

• DELETE /roles/offboardings/{id} - Cancel role offboarding

User Onboarding

• POST /user-onboardings - Start user onboarding

• GET /user-onboardings - List user onboardings

• GET /user-onboardings/{id} - Get user onboarding

Document Management (v2)

• GET /v2/documents - Get documents with new resource model

• POST /v2/documents - Upload documents with new resource model

• GET /v2/documents/{id} - Get document with new model

• GET /v2/documents/{id}/file - Get document file

• POST /v2/documents/sign - Sign document with new model

Key Model Changes

Beneficial Owner Model

Old Model (customers.yaml):

{
  "boType": "REAL_UBO_25",
  "share": 30.0,
  "uboRelationship": "DIRECTLY_HOLDING_25"
}

New Model (entities.yaml):

{
  "share": 30.0,
  "votingRights": 30.0,
  "uboRelationship": "DIRECTLY_HOLDING_25"
}

Key Changes:

• ❌ Removed: boType field (all beneficial owners are now REAL_UBO_25)

• ➕ Added: votingRights field (required)

• ✅ Required: uboRelationship field is now mandatory

Proxy Model

Old Model (customers.yaml):

{
  "customerId": "uuid",
  "proxyType": "GENERAL_POWER_OF_ATTORNEY"
}

New Model (roles.yaml):

{
  "entityId": "uuid",
  "entityType": "NATURAL_PERSON",
  "proxyType": "GENERAL_POWER_OF_ATTORNEY"
}

Key Changes:

• 🔄 Changed: customerId → entityId

• ➕ Added: entityType field

Legal Entity Model

Old Model (customers.yaml):

{
  "legalName": "Example Corp",
  "legalForm": "LIMITED_LIABILITY_COMPANY",
  "labels": ["corporate"],
  "refAccounts": [...],
  "legalRepresentatives": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "function": "MANAGING_DIRECTOR"
    }
  ]
}

New Model (entities.yaml + roles.yaml):

// Legal Entity (entities.yaml)
{
  "legalName": "Example Corp", 
  "legalForm": "LIMITED_LIABILITY_COMPANY",
  "mainAddress": {...},
  "contact": {...}
  // NO legal representatives here!
}

// Customer Role (roles.yaml)  
{
  "entityId": "le-uuid",
  "entityType": "LEGAL_ENTITY",
  "labels": ["corporate"],
  "refAccounts": [...]
}

// Legal Representatives (entities.yaml - separate endpoints)
// GET /entities/{legalEntityId}/legal-representatives

Key Changes:

• ❌ Removed: legalRepresentatives array from legal entity payload

• 🔄 Separated: Customer role data moved to roles.yaml

• ➕ Added: Dedicated legal representative endpoints

Document Model

Old Model (documents.yaml):

{
  "name": "example.pdf",
  "entityType": "CUSTOMER",
  "entityId": "customer-uuid",
  "type": "ONBOARDING"
}

New Model (documents.yaml v2):

{
  "name": "example.pdf", 
  "resourceType": "CUSTOMER",
  "resourceId": "customer-uuid",
  "type": "ONBOARDING"
}

Key Changes:

• 🔄 Renamed: entityType → resourceType

• 🔄 Renamed: entityId → resourceId

• ➕ Added: New resource types (LEGAL_ENTITY in addition to existing ones)

Onboarding Model

Old Model (onboardings.yaml - Centralized):

{
  "entityType": "CUSTOMER",
  "entityId": "customer-uuid"
}

New Model (entities.yaml + roles.yaml - Distributed):

// Entity Onboarding (entities.yaml)
{
  "entityType": "BENEFICIAL_OWNER",
  "entityId": "bo-uuid"
}

// Role Onboarding (roles.yaml)
{
  "onboardingRoleType": "CUSTOMER",
  "roleId": "customer-uuid"
}

// User Onboarding (users.yaml)
{
  "userId": "user-uuid"
}

Key Changes:

• 🔄 Split: Centralized onboarding → dorelease-test-specific onboarding

• 🔄 Changed: Different parameters for entity vs role vs user onboarding

• ➕ Added: onboardingRoleType field for role onboarding

Practical Migration Examples

1. Creating a Beneficial Owner

Before (customers.yaml):

POST /customers/natural-persons/{customerId}/beneficial-owners
{
  "firstName": "John",
  "lastName": "Doe",
  "boType": "REAL_UBO_25",
  "share": 30.0,
  "uboRelationship": "DIRECTLY_HOLDING_25"
}

After (entities.yaml):

POST /entities/{legalEntityId}/beneficial-owners  
{
  "firstName": "John", 
  "lastName": "Doe",
  "share": 30.0,
  "votingRights": 30.0,
  "uboRelationship": "DIRECTLY_HOLDING_25"
}

2. Creating a Proxy

Before (customers.yaml):

POST /natural-persons/{naturalPersonId}/proxy
{
  "customerId": "customer-uuid",
  "proxyType": "GENERAL_POWER_OF_ATTORNEY",
  "validityType": "UNLIMITED"
}

After (roles.yaml):

POST /roles/proxies
{
  "entityId": "entity-uuid",
  "entityType": "NATURAL_PERSON", 
  "proxyType": "GENERAL_POWER_OF_ATTORNEY",
  "validityType": "UNLIMITED"
}

3. Creating a Natural Person Customer

Before (customers.yaml) - Two steps:

Step 1: Create Natural Person

POST /natural-persons
{
  "firstName": "John",
  "lastName": "Doe",
  "birthDay": "1990-01-01",
  "birthPlace": "Berlin",
  "birthCountry": "DE",
  "nationalities": ["DE"],
  "contact": {
    "phone": "[phone]",
    "email": "[email protected]"
  },
  "mainAddress": {
    "street": "Main Street",
    "streetNumber": "123",
    "city": "Berlin",
    "zip": "10115",
    "country": "DE"
  }
  // ... other natural person data
}

Step 2: Create Natural Person Customer

POST /customers/natural-persons
{
  "naturalPersonId": "{{naturalPersonId}}",
  "labels": ["vip"],
  "refAccounts": [...]
}

After (entities.yaml + roles.yaml) - Two steps:

Step 1: Create Natural Person Entity

POST /entities/natural-persons
{
  "firstName": "John",
  "lastName": "Doe",
  "birthDay": "1990-01-01",
  "birthPlace": "Berlin",
  "birthCountry": "DE",
  "nationalities": ["DE"],
  "contact": {
    "phone": "[phone]",
    "email": "[email protected]"
  },
  "mainAddress": {
    "street": "Main Street",
    "streetNumber": "123",
    "city": "Berlin",
    "zip": "10115",
    "country": "DE"
  }
  // ... other natural person data
}

Step 2: Assign Customer Role

POST /roles/customers  
{
  "entityId": "{{naturalPersonId}}",
  "entityType": "NATURAL_PERSON",
  "labels": ["vip"], 
  "refAccounts": [...]
}

Key Change: Same two-step process, but different API domains:

• Before: /natural-persons → /customers/natural-persons

• After: /entities/natural-persons → /roles/customers

4. Creating a Legal Entity Customer

Before (customers.yaml) - Single step:

POST /customers/legal-entities
{
  "legalName": "Example Corp",
  "legalForm": "LIMITED_LIABILITY_COMPANY",
  "labels": ["corporate"],
  "refAccounts": [...],
  "legalRepresentatives": [...],
  // ... all entity + customer data in one payload
}

After (entities.yaml + roles.yaml) - Three steps:

Step 1: Create Legal Entity

POST /entities/legal-entities
{
  "legalName": "Example Corp", 
  "legalForm": "LIMITED_LIABILITY_COMPANY",
  "mainAddress": {...},
  "contact": {...}
  // ... entity data only (NO legal representatives here!)
}
// Response: { "legalEntityId": "le-uuid" }

Step 2: Create Legal Representatives

POST /entities/le-uuid/legal-representatives
{
  "firstName": "John",
  "lastName": "Doe", 
  "function": "MANAGING_DIRECTOR",
  "soleSignatureAuthorized": true,
  // ... legal representative data
}
// Response: { "legalRepresentativeId": "lr-uuid" }

Step 3: Create Customer Role

POST /roles/customers
{
  "entityId": "le-uuid",
  "entityType": "LEGAL_ENTITY", 
  "labels": ["corporate"],
  "refAccounts": [...]
  // ... customer role data only
}

5. Creating a Joint Person Customer

Before (customers.yaml) - Single step:

POST /customers/joint-persons
{
  "firstNaturalPersonId": "np1-uuid",
  "secondNaturalPersonId": "np2-uuid", 
  "labels": ["family"],
  "refAccounts": [...],
  // ... all entity + customer data in one payload
}

After (entities.yaml + roles.yaml) - Two steps:

Step 1: Create Joint Person

POST /entities/joint-persons
{
  "firstNaturalPersonId": "np1-uuid",
  "secondNaturalPersonId": "np2-uuid",
  "contact": {...},
  "mainAddress": {...}
  // ... entity data only
}
// Response: { "jointPersonId": "jp-uuid" }

Step 2: Create Customer Role

POST /roles/customers
{
  "entityId": "jp-uuid",
  "entityType": "JOINT_PERSON",
  "labels": ["family"],
  "refAccounts": [...]
  // ... customer role data only
}

6. Managing Legal Representatives

Before (customers.yaml) - Inline in legal entity:

# Legal representatives were included in legal entity payload
POST /customers/legal-entities
{
  "legalName": "Example Corp",
  "legalRepresentatives": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "function": "MANAGING_DIRECTOR",
      "soleSignatureAuthorized": true
    }
  ]
}

# Updates also required full legal entity payload
PATCH /customers/legal-entities/{customerId}
{
  "legalRepresentatives": [
    {
      "firstName": "John Updated",
      "lastName": "Doe",
      "function": "MANAGING_DIRECTOR" 
    }
  ]
}

After (entities.yaml) - Dedicated endpoints:

# Create legal representative separately
POST /entities/{legalEntityId}/legal-representatives
{
  "firstName": "John",
  "lastName": "Doe", 
  "function": "MANAGING_DIRECTOR",
  "soleSignatureAuthorized": true,
  "fatcaControllingPerson": false
}

# List legal representatives for entity
GET /entities/{legalEntityId}/legal-representatives

# Update specific legal representative  
PATCH /entities/legal-representatives/{legalRepresentativeId}
{
  "firstName": "John Updated"
}

# Delete legal representative (new capability!)
DELETE /entities/legal-representatives/{legalRepresentativeId}

7. Uploading Documents

Before (documents.yaml):

POST /documents
Content-Type: multipart/form-data

{
  "document": {
    "name": "contract.pdf",
    "entityType": "CUSTOMER",
    "entityId": "customer-uuid", 
    "type": "CONTRACTS"
  },
  "file": <binary-data>
}

After (documents.yaml v2):

POST /v2/documents
Content-Type: multipart/form-data

{
  "document": {
    "name": "contract.pdf",
    "resourceType": "CUSTOMER",
    "resourceId": "customer-uuid",
    "type": "CONTRACTS"
  },
  "file": <binary-data>
}

8. Starting Onboarding Process

Before (onboardings.yaml - Centralized):

# Customer onboarding
POST /onboardings
{
  "entityType": "CUSTOMER",
  "entityId": "customer-uuid"
}

# Beneficial owner onboarding
POST /onboardings
{
  "entityType": "BENEFICIAL_OWNER",
  "entityId": "bo-uuid"
}

# Proxy onboarding
POST /onboardings
{
  "entityType": "PROXY",
  "entityId": "proxy-uuid"
}

# User onboarding
POST /onboardings
{
  "entityType": "PARTNER_USER",
  "entityId": "partner-user-uuid"
}

After (entities.yaml + roles.yaml + users.yaml- Distributed):

# Customer role onboarding
POST /roles/onboardings
{
  "onboardingRoleType": "CUSTOMER",
  "roleId": "customer-uuid"
}

# Beneficial owner entity onboarding
POST /entities/onboardings
{
  "entityType": "BENEFICIAL_OWNER",
  "entityId": "bo-uuid"
}

# Proxy role onboarding
POST /roles/onboardings
{
  "onboardingRoleType": "PROXY", 
  "roleId": "proxy-uuid"
}

# User onboarding
POST /user-onboardings
{
  "userId": "user-uuid"
}

9. Updating a Customer Role

Before (customers.yaml):

PATCH /customers/natural-persons/{customerId}
{
  "labels": ["premium", "vip"],
  "refAccounts": [
    {
      "bankName": "Deutsche Bank",
      "iban": "DE89370400440532013000",
      "bic": "DEUTDEFF",
      "type": "PRIMARY"
    }
  ]
}

After (roles.yaml):

PATCH /roles/customers/{customerId}
{
  "labels": ["premium", "vip"],
  "refAccounts": [
    {
      "bankName": "Deutsche Bank", 
      "iban": "DE89370400440532013000",
      "bic": "DEUTDEFF",
      "type": "PRIMARY"
    }
  ]
}

Key Change: Customer role updates are now separate from entity updates. To update entity data (like address, contact), use the appropriate entity endpoint (/entities/natural-persons/{entityId} or /entities/legal-entities/{entityId}).

Migration Checklist

Phase 1: Update Base URLs

• Update base URLs to point to entities.yaml for entity operations

• Update base URLs to point to roles.yaml for role operations

Phase 2: Path Updates

• Update all natural person endpoints: /natural-persons/* → /entities/natural-persons/*

• Update legal entity endpoints: /customers/legal-entities/* → /entities/legal-entities/*

• Update customer endpoints: /customers → /roles/customers

• Update proxy endpoints: /proxies/* → /roles/proxies/*

• Update NACE sectors search: /customers/*/search/nace-sectors → /entities/*/search/nace-sectors

• Update customer statistics: /customers/status-counts → /roles/customers/statistics/status-counts

• Update document endpoints: /documents/* → /v2/documents/*

• Update onboarding endpoints: /onboardings/* → /entities/onboardings/* OR /roles/onboardings/* OR /user-onboardings/*

Phase 3: Model Updates

• Beneficial Owners: Remove boType, add votingRights, ensure uboRelationship is provided

• Proxies: Change customerId → entityId, add entityType

• Customers: Update create payload structure

• Documents: Change entityType → resourceType, entityId → resourceId

• Onboarding: Split centralized model into entity-specific and role-specific and user-specific models

Phase 4: Breaking Changes

• Beneficial Owners: Change path parameter from customerId to legalEntityId

• Proxy Creation: Change from natural person sub-resource to direct role creation

• Customer Creation: Replace single-step customer creation with multi-step process (entity + role)

  • Legal Entity Customers: POST /customers/legal-entities → POST /entities/legal-entities + POST /entities/{id}/legal-representatives + POST /roles/customers

  • Joint Person Customers: POST /customers/joint-persons → POST /entities/joint-persons + POST /roles/customers

  • Natural Person Customers: POST /customers/natural-persons → Use existing natural person + POST /roles/customers

• Legal Representatives: Remove from legal entity payloads, use dedicated endpoints

  • Creation: Extract from legal entity payload → POST /entities/{legalEntityId}/legal-representatives

  • Reading: Get from legal entity response → GET /entities/{legalEntityId}/legal-representatives

  • Updates: No longer inline → PATCH /entities/legal-representatives/{id}

  • Deletion: New capability → DELETE /entities/legal-representatives/{id}

• Documents: Update to v2 API with new resource model

  • Upload: Use /v2/documents with resourceType/resourceId instead of entityType/entityId

  • Query: Update query parameters to use new resource-based filtering

  • Resource Types: Map old entity types to new resource types

• Onboarding Process: Choose appropriate dorelease-test-specific endpoint

  • Entity Onboarding: Use /entities/onboardings for beneficial owners

  • Role Onboarding: Use /roles/onboardings for customers and proxies

  • User Onboarding: Use /user-onboardings for users

  • Parameters: Update payload structure with new field names

• Customer Data Retrieval: Combine data from entity and role endpoints

• Customer Updates: Update both entity data and role data separately

Phase 5: New Features

• Unified Entity Search: Implement GET /entities endpoint for cross-entity searching

• Legal Representative Management: Dedicated CRUD endpoints for legal representatives

• Joint Person Management: Dedicated CRUD endpoints for joint persons

• Legal Entity Management: Dedicated CRUD endpoints for legal entities

Validation Rules Changes

Beneficial Owners

• uboRelationship is now required for all beneficial owners

• votingRights is now required (0-100%, multiple of 0.01)

• For DIRECTLY_HOLDING_25 or INDIRECTLY_HOLDING_25: either share OR voting rights must be ≥ 25%

• For DOMINANT_INFLUENCE_OVER_SHARE_CAPITAL: no minimum requirements

New Webhook Notifications

The entity-role architecture introduces several new webhook notifications to support the distributed model:

Entity-Related Webhooks (New)

Webhook Endpoint	Purpose	Entity Type
/joint-person-notification	Joint Person lifecycle events	Joint Persons
/legal-entity-notification	Legal Entity lifecycle events	Legal Entities
/legal-representative-notification	Legal Representative lifecycle events	Legal Representatives
/legal-entity-search-notification	Legal Entity search process updates	Legal Entity Search

Process-Related Webhooks (New)

Webhook Endpoint	Purpose	Description
/offboarding-notification	Offboarding process updates	Entity and role offboarding events

Enhanced Existing Webhooks

Webhook Endpoint	Enhancement	Description
/customer-notification	Role-focused	Now specifically for customer role events
/proxy-notification	Entity-aware	Now supports entity-based proxy relationships
/beneficial-owner-notification	Entity-focused	Now directly associated with legal entities

Notification Types

All new webhooks support standard notification types:

• CREATED - Entity/role was created

• UPDATED - Entity/role was updated

• DELETED - Entity/role was deleted

• VALIDATION_ERROR - Validation failed

Migration Impact: Update your webhook handlers to support the new entity-focused notifications and ensure proper handling of the distributed event model.

Additional Resources

• Check the detailed API reference in entities.yaml, roles.yaml, documents.yaml, and onboardings.yaml

• Review the comprehensive architectural changes in the main README

• Test your migration against the new endpoints in the test environment

• Consult webhooks.yaml for notification updates

Legend:

• ✏️ Simple path change

• 🔄 Breaking change requiring code updates

• ➕ New endpoint/feature

• ❌ Removed field/endpoint

• 🔀 Split into multiple endpoints

• ✅ New requirement