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

Natural Persons

Beneficial Owners

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

Legal Entities

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

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

Joint Persons

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)

Proxies

Customer Labels

Identification Verification

Documents

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

Onboarding & Offboarding (Centralized → Distributed)

Important: Onboarding is now domain-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

Customer Statistics

Natural Person Wizard (Completely 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 → domain-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": "+49123456789",
    "email": "john.doe@example.com"
  },
  "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": "+49123456789",
    "email": "john.doe@example.com"
  },
  "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 domain-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)

Process-Related Webhooks (New)

Enhanced Existing Webhooks

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