# 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**](#beneficial-owner-model) |
| `GET /customers/natural-persons/{customerId}/beneficial-owners`        | `GET /entities/{legalEntityId}/beneficial-owners`  | 🔄 [**Breaking change**](#beneficial-owner-model) |
| `GET /customers/natural-persons/{customerId}/beneficial-owners/{id}`   | `GET /entities/beneficial-owners/{id}`             | 🔄 [**Breaking change**](#beneficial-owner-model) |
| `PATCH /customers/natural-persons/{customerId}/beneficial-owners/{id}` | `PATCH /entities/beneficial-owners/{id}`           | 🔄 [**Breaking change**](#beneficial-owner-model) |

**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**](#proxy-model) |
| `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**](#document-model) |
| `POST /documents`             | `POST /v2/documents`          | 🔄 [**Breaking change**](#document-model) |
| `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**](#onboarding-model) |
| `GET /onboardings`              | `GET /entities/onboardings` OR `GET /roles/onboardings` OR `GET /user-onboardings`                | 🔄 [**Breaking change**](#onboarding-model) |
| `GET /onboardings/{id}`         | `GET /entities/onboardings/{id}` OR `GET /roles/onboardings/{id}` OR `GET /user-onboardings/{id}` | 🔄 [**Breaking change**](#onboarding-model) |
| `POST /offboardings`            | `POST /entities/offboardings` OR `POST /roles/offboardings`                                       | 🔄 [**Breaking change**](#onboarding-model) |
| `GET /offboardings`             | `GET /entities/offboardings` OR `GET /roles/offboardings`                                         | 🔄 [**Breaking change**](#onboarding-model) |
| `GET /offboardings/{id}`        | `GET /entities/offboardings/{id}` OR `GET /roles/offboardings/{id}`                               | 🔄 [**Breaking change**](#onboarding-model) |
| `DELETE /offboardings/{id}`     | `DELETE /entities/offboardings/{id}` OR `DELETE /roles/offboardings/{id}`                         | 🔄 [**Breaking change**](#onboarding-model) |

**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):**

```json
{
  "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):**

```http
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):**

```http
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):**

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

**After (roles.yaml):**

```http
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**

```http
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**

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

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

**Step 1: Create Natural Person Entity**

```http
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**

```http
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:**

```http
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**

```http
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**

```http
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**

```http
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:**

```http
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**

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

**Step 2: Create Customer Role**

```http
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:**

```http
# 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:**

```http
# 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):**

```http
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):**

```http
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):**

```http
# 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):**

```http
# 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):**

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

**After (roles.yaml):**

```http
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