# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tradevest.ai/release-notes/archive/v1.2.0-test-environment/api_migration_guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.