# Onboarding

* [Onboarding](#onboarding)
  * [Onboarding Process Overview](#onboarding-process-overview)
  * [Entity Preparation](#entity-preparation)
  * [Role Assignment](#role-assignment)
    * [Customer Role Assignment](#customer-role-assignment)
    * [Proxy Role Assignment](#proxy-role-assignment)
  * [Onboarding Types](#onboarding-types)
    * [Customer Onboarding](#customer-onboarding)
      * [How Customer Onboarding Works](#how-customer-onboarding-works)
      * [Validation Types](#validation-types)
      * [Customer Type Specific Validations](#customer-type-specific-validations)
        * [Natural Person Customer Validations](#natural-person-customer-validations)
        * [Legal Entity Customer Validations](#legal-entity-customer-validations)
        * [Joint Person Customer Validations](#joint-person-customer-validations)
      * [Proxy Specific Validations](#proxy-specific-validations)
      * [Validation Process Flow](#validation-process-flow)
        * [Validation Outcomes](#validation-outcomes)
      * [KYC and Compliance Integration](#kyc-and-compliance-integration)
      * [Error Handling and Notifications](#error-handling-and-notifications)
    * [Proxy Onboarding](#proxy-onboarding)
      * [Proxy Onboarding Validation Types](#proxy-onboarding-validation-types)
    * [Beneficial Owner Onboarding](#beneficial-owner-onboarding)
  * [Document Management](#document-management)
  * [Onboarding Scenarios and Sequence Diagrams](#onboarding-scenarios-and-sequence-diagrams)
    * [Natural Person Customer Onboarding Sequence](#natural-person-customer-onboarding-sequence)
    * [Legal Entity Customer Onboarding Sequence](#legal-entity-customer-onboarding-sequence)
    * [Joint Person Customer Onboarding Sequence](#joint-person-customer-onboarding-sequence)
    * [Proxy Onboarding Sequence](#proxy-onboarding-sequence)
    * [Beneficial Owner Onboarding Sequence](#beneficial-owner-onboarding-sequence)

## Onboarding Process Overview

The platform supports three types of entities that can be prepared and managed:

* Natural persons
* Legal entities
* Joint persons

The onboarding process follows a structured approach:

1. **Entity Preparation** - Creating and preparing the entity with all required data and documents
2. **Role Assignment** - Assigning appropriate roles to entities (customer, proxy)
3. **Document Readiness** - Waiting for all required documents to reach `CREATED` status (confirmed via `Document Notification` webhooks)
4. **Onboarding Initiation** - Starting the appropriate onboarding process based on the entity type and business need

The platform offers three distinct onboarding processes:

1. **Customer Onboarding** (Role) - A comprehensive process that handles onboarding of a customer role and all related entities (proxies, beneficial owners). This is the primary method for onboarding new customers using `POST /roles/onboardings`.
2. **Proxy Onboarding** (Role) - A specialized process for adding a new proxy to an already active customer using `POST /roles/onboardings` with the appropriate type parameter.
3. **Beneficial Owner Onboarding** (Entity) - A specialized process for adding a new beneficial owner to an already active legal entity customer using `POST /entities/onboardings`.

Each onboarding process is asynchronous and involves:

* Validation of entity and role data along with required documents
* Validation of reference account IBANs (for customers)
* Performing additional checks like Know Your Customer (KYC)

Upon completion of each process, notifications are sent to the partner via webhooks:

* `Onboarding Notification`
* `Customer Notification`
* `Natural Person Notification`
* `Joint Person Notification`
* `Legal Entity Notification`
* `Beneficial Owner Notification`
* `Proxy Notification`
* `Document Notification`

Onboarded customers do not have any products activated by default. Partners must create customer products to allow\
customers to create transfers and orders. Partners should use the Get Product Definitions API to get the list of active\
products that can be created for their customers.

## Entity Preparation

Before starting any onboarding process, the relevant entities must be created and prepared.

* **Natural Person and Joint Person Preparation**: For detailed information on preparing natural persons (adults and children) and joint persons, including identification verification methods, see [Natural Person Management](/documentation/entity_role_management_after_refactor/natural_person_management.md).
* **Legal Entity Preparation**: For detailed information on preparing legal entities, including beneficial owners and legal representatives, see [Legal Entity Management](/documentation/entity_role_management_after_refactor/legal_entity_management.md).

## Role Assignment

After preparing the entities, roles can be assigned to them.

For comprehensive information about role management, assignment, and onboarding processes, see [Role Management](/documentation/entity_role_management_after_refactor/roles_management.md).

### Customer Role Assignment

To assign a customer role to an entity, the partner must:

1. Assign the customer role to the entity using `POST /roles/customers` with the `entityId` and `entityType`
2. Upload required documents related to the customer role using `POST /v2/documents/` with `resourceType` set to\
   CUSTOMER

### Proxy Role Assignment

To assign a proxy role, the partner must:

1. Ensure both the representing natural person and the entity to be represented are already created
2. Assign the proxy role using `POST /roles/proxies` with the natural person's ID and the `entityId` and `entityType` of the entity to be represented
3. Upload required proxy-specific documents using `POST /v2/documents/` with `resourceType` set to PROXY:
   * For Guardian proxies: `PROOF_OF_SINGLE_CUSTODY`, `PROOF_OF_CUSTODY`
   * For Liquidator proxies: `INSOLVENCY_ORDER`
   * For General Power of Attorney with death validity: `INHERITANCE_LEGITIMATION`
   * For other proxy types: General documents (`GENERAL`, `CONTRACTS`, etc.)

## Onboarding Types

### Customer Onboarding

Customer onboarding is a comprehensive process that handles the onboarding of the customer role and all related entities (proxies, beneficial owners). It is initiated by calling `POST /roles/onboardings`.

For detailed role management information, see [Role Management](/documentation/entity_role_management_after_refactor/roles_management.md).

Unlike entity creation processes, **customer onboarding does not perform any static validations at the API level**. Instead, all validation, verification, and processing happens asynchronously through internal system processing after the onboarding process is initiated. The process consists of multiple asynchronous steps: initial validation, KYC verification, and potential manual review processes, all coordinated through the system's internal process framework.

{% hint style="danger" %}
**Prerequisite: Document Readiness.** Before calling the Start Onboarding endpoint, all required documents must have reached `CREATED` status. Document uploads via `POST /v2/documents/` are processed asynchronously — the document is not immediately available. Partners must wait for the `Document Notification` webhook confirming `CREATED` status for each required document before initiating onboarding. Failing to do so will result in onboarding rejection with a validation error such as `required documents [DOCUMENT_TYPE] do not exist for ENTITY_TYPE`.
{% endhint %}

#### How Customer Onboarding Works

1. **Process Initiation**: Customer onboarding is started by calling `POST /roles/onboardings` with the customer ID.
2. **Asynchronous Processing**: The system creates an onboarding record and begins asynchronous processing.
3. **Data Fetching**: The system fetches all related entities, roles, and documents for the customer.
4. **Validation Execution**: All validations are performed asynchronously by the system.
5. **Process Flow**: Based on validation results, the process either completes successfully or routes to review/rejection.

#### Validation Types

All validations in customer onboarding are asynchronous and performed by the system:

**Customer and Entity Validation:**

* Customer status verification (must be CREATED)
* Entity-specific status validation (Natural Person, Legal Entity, Joint Person)
* Death day validation for natural persons
* Entity identification verification

**Document Validation:**

* Required document presence validation based on entity type
* Document status verification
* Document signature validation
* Entity-specific document requirements

**Relationship Validation:**

* Proxy validation and status verification
* Guardian validation for minor customers

**Business Logic Validation:**

* Know Your Customer (KYC) verification processes
* Vendor data verification for legal entities

#### Customer Type Specific Validations

**Natural Person Customer Validations**

**Entity Status Validations:**

* Natural person status must be CREATED or ACTIVE
* Customer status must be CREATED
* Death day must not be set during onboarding

**Document Validations:**

* `IDENTIFICATION_CERTIFICATE` (required)
* `PROOF_OF_RESIDENCE` (required for non-German main addresses - when main address country is not DE)
* Natural person identification must be complete and valid
* Document signatures must be present for required documents
* For minors: `BIRTH_CERTIFICATE` (required)

**Legal Entity Customer Validations**

**Entity Status Validations:**

* Legal entity status must be CREATED or ACTIVE
* Customer status must be CREATED

**Document Validations (based on legal form):**

* `CURRENT_REGISTRY_EXTRACT` (required for most legal forms)
* `SHAREHOLDER_LIST` (required for certain legal forms)
* `PARTNERSHIP_AGREEMENT` (required for partnerships)
* `TRANSPARENCY_REGISTER_EXTRACT` (required in specific cases)
* `BUSINESS_REGISTRATION` (required for certain legal forms)
* `STATUTE` (required for certain legal forms)
* Unknown legal forms trigger manual verification

**Vendor Data Verification:**

* Verification against external legal entity data providers
* Comparison of submitted data with vendor records
* Detection of differences requiring manual review
* Automatic creation of admin tasks for discrepancies

**Joint Person Customer Validations**

**Entity Status Validations:**

* Both natural persons must have valid status (CREATED or ACTIVE)
* Both natural persons must have different IDs (cannot be the same person)
* Customer status must be CREATED
* Death day validation for both natural persons

**Document Validations:**

* `IDENTIFICATION_CERTIFICATE` for both natural persons (required)
* `PROOF_OF_RESIDENCE` for both natural persons (required for non-German main addresses - when main address country is not DE)
* Complete identification for both natural persons
* Document signatures must be present for both natural persons
* Both natural persons must be adults (18 or older)

**Proxy Specific Validations**

**Guardian Proxy:**

* Guardian proxy validation for natural person customers under 18:
  * At least one guardian is required.
  * Guardian must be of legal age (18 or older) and not the same person as the customer.
  * Custody validation: `JOINT_CUSTODY` requires two guardians, `SINGLE_CUSTODY` allows only one.
* Proxy's Natural Person:
  * status must be CREATED or ACTIVE
  * has valid Identification
  * has a `IDENTIFICATION_CERTIFICATE`
  * has signed Partner Documents
* Proxy status must be CREATED or ACTIVE.
* Required proxy documents for a Guardian:
  * `PROOF_OF_CUSTODY` is always required.
  * `PROOF_OF_SINGLE_CUSTODY` is additionally required for the `SINGLE_CUSTODY` type.

**Signatory Proxy**

* Proxy's Natural Person:
  * status must be CREATED or ACTIVE
  * has valid Identification
  * has a `IDENTIFICATION_CERTIFICATE`
  * has signed Partner Documents
* Proxy status must be CREATED or ACTIVE.
* For any signatory proxy there must be a matching legal entity legal representative
* If legal representative has SoleSignatureAuthorized=true, then proxy's scope type must be set to `INDIVIDUAL`, otherwise it should be set to `JOINT`
* Scope type validation (INDIVIDUAL for sole signature, JOINT for joint signature)

**Joint Account Holder Validations:**

* Joint Account Holder proxies are automatically created during Joint Person Customer onboarding
* These proxies are created with ACTIVE status for both natural persons in the joint person customer
* Joint Account Holder proxies cannot be created manually - they are system-generated
* Proxy validation follows standard natural person proxy rules (valid identification, documents, etc.)

**General Power of Attorney Validations**

* Proxy's Natural Person:
  * status must be CREATED or ACTIVE
  * has valid Identification
  * has a `IDENTIFICATION_CERTIFICATE`
  * has signed Partner Documents
* Proxy status must be CREATED or ACTIVE.
* For validity type `IN_CASE_OF_DEATH` proxy must have `INHERITANCE_LEGITIMATION` document

#### Validation Process Flow

The customer onboarding validation process follows these steps:

1. **Initialize Process**: Onboarding is created with CREATED status.
2. **Fetch Customer Data**: System retrieves customer compound with all related entities.
3. **Fetch Relations**: System gets all related proxies and beneficial owners in CREATED status.
4. **Fetch Documents**: System retrieves all required documents for the customer and related entities.
5. **Execute Validations**: All validations are performed against the fetched data.
6. **Process Results**: Based on validation outcomes.

**Validation Outcomes**

**Immediate Rejection**:

* Critical validation failures (invalid status, death day set, etc.) result in rejection of onboarding and all related entities. Customer and entities are set to REJECTED status.

**Onboarding Only Rejection**:

* Non-critical validation failures result in rejection of onboarding only. Customer and entities remain in CREATED status.

**Manual Review Required**:

* Legal entity vendor verification differences or unknown legal forms result in admin task creation and REVIEW status.

**Successful Validation**:

* All validations pass, entities are set to PENDING status, and the KYC verification process is automatically initiated.

#### KYC and Compliance Integration

After successful validation, the customer onboarding process integrates with KYC (Know Your Customer) verification:

**KYC Verification Process:**

* KYC verification is automatically initiated after validations pass.
* The system sends the customer and related entities to automated KYC screening.
* KYC verification is performed against compliance databases and external services.

**KYC Outcomes:**

* **Valid**: Automatic approval and activation of entities.
* **Manual Review Required**: An admin task is created for manual verification.
* **Repeat KYC**: Additional verification rounds may be triggered.
* **Rejected**: Entities may be rejected based on KYC findings.

**Admin Task Integration:**

* Admin tasks are automatically created for manual review cases (data discrepancies, KYC).
* Callback mechanisms continue processing after admin decisions.

#### Error Handling and Notifications

* **Validation Errors**: Failures result in appropriate `Onboarding Notification` with error details.
* **Process Monitoring**: All steps are tracked, with retry mechanisms for transient failures.
* **Notification System**: Partners receive webhook notifications for all status changes on onboarding, entities, documents, and roles.

### Proxy Onboarding

Proxy onboarding is used specifically for adding new proxies to existing customers. This specialized process:

* Only handles the proxy role, not the entire customer profile
* Requires an existing customer with appropriate status:
  * `ACTIVE` customer for most proxy types
  * `ESTATE` customer for General Power of Attorney with `IN_CASE_OF_DEATH` validity type
* Is used when an existing customer needs a new proxy added

To start the proxy onboarding process, use: `POST /roles/onboardings` with the appropriate onboarding type specified in the request.

#### Proxy Onboarding Validation Types

All validations in proxy onboarding are asynchronous and performed by the system:

**Entity Status Validation:**

* Natural person status must be CREATED or ACTIVE
* Special case: For GPoA with `IN_CASE_OF_DEATH` validity type:
  * Natural person status must be `DECEASED`
  * Customer status must be `ESTATE` (required)
* Customer must exist and be ACTIVE for all other proxy types
* Death day validation (except for GPoA with IN\_CASE\_OF\_DEATH validity type)

**Proxy Status Validation:**

* Proxy status must be CREATED or ACTIVE

**Document Validation:**

* `IDENTIFICATION_CERTIFICATE` (required for natural person)
* Natural person identification must be complete and valid
* Document signatures must be present for required partner documents
* Proxy-specific documents based on proxy type:
  * Guardian: `PROOF_OF_CUSTODY`, `PROOF_OF_SINGLE_CUSTODY` (for single custody)
  * GPoA with death validity: `INHERITANCE_LEGITIMATION`

**Business Logic Validation:**

* Proxy type specific validations (Guardian custody logic, Signatory scope matching)
* Guardian validation for minor customers (custody type requirements)
* Signatory matching to legal representatives (for legal entity customers)
* Know Your Customer (KYC) verification processes

For detailed proxy role management information, see [Role Management](/documentation/entity_role_management_after_refactor/roles_management.md).

### Beneficial Owner Onboarding

Beneficial owner onboarding is used specifically for adding new beneficial owners to already active legal entity customers. This specialized process:

* Only handles the beneficial owner entity
* Requires an already active legal entity customer
* Is used when an existing legal entity customer needs a new beneficial owner added

To start the beneficial owner onboarding process, use: `POST /entities/onboardings`.

#### Beneficial Owner Onboarding Validation Types

All validations in beneficial owner onboarding are asynchronous and performed by the system:

**Entity Status Validation:**

* Beneficial owner status must be CREATED
* Legal entity status must be ACTIVE
* Death day must not be set during onboarding

**Business Logic Validation:**

* Beneficial owner type validation (REAL\_UBO\_25, etc.)
* Share and voting rights validation:
  * For share > 0, type must be REAL\_UBO\_25
  * For voting rights > 0, type must be REAL\_UBO\_25
* UBO relationship validation for REAL\_UBO\_25 type
* Legal entity ownership structure validation
* FATCA controlling person validation
* Know Your Customer (KYC) verification processes
* Compliance checks for beneficial ownership requirements

**Document Validation:**

* Document requirements depend on beneficial owner's personal data:
  * `IDENTIFICATION_CERTIFICATE` (required for adults)
  * `BIRTH_CERTIFICATE` (required for minors under 18)
  * `PROOF_OF_RESIDENCE` (required for non-German main addresses - when main address country is not DE)
  * `TIN_NA_CONFIRMATION` (required if NoTinConfirmation is true)
* Document signatures must be present for required partner documents
* Whitelisted residencies validation for addresses

## Document Management

For comprehensive information about document management, including document endpoints, document types, upload processes, verification methods, and entity-specific requirements, see [Document Management](/documentation/entity_role_management_after_refactor/document_management.md).

## Onboarding Scenarios and Sequence Diagrams

### Natural Person Customer Onboarding Sequence

```mermaid
sequenceDiagram
    participant PW as Partner's webhook
    participant P as Partner's API Client
    participant T as Our API
    autonumber
    P ->>+ T: POST /entities/natural-persons
    T -->>- P: OK
    T ->> PW: Natural Person Notification - CREATED

    alt Document Upload Method
        P ->>+ T: POST /entities/natural-persons/{naturalPersonId}/identifications
        T -->>- P: OK
        T ->> PW: Natural Person Notification - UPDATED

        loop Natural Person Documents
            P ->>+ T: POST /v2/documents
            T -->>- P: OK
            T ->> PW: Document Notification - CREATED
        end
    else External Verifier Method
        P ->>+ T: POST /entities/identification-verifications
        T -->>- P: OK (with identificationUrl)
        Note over P: Partner redirects user to identificationUrl
        Note over T: External verification completed
        T ->> PW: Document Notification - CREATED (auto-generated IDENTIFICATION_CERTIFICATE)
        T ->> PW: Natural Person Notification - UPDATED (identity record created)
    end

    P ->>+ T: POST /v2/documents/sign
    T -->>- P: OK
    T ->> PW: Natural Person Notification - UPDATED
    P ->>+ T: POST /roles/customers
    T -->>- P: OK
    T ->> PW: Customer Notification - CREATED

    opt Create Guardian - Child Customer
        loop Customer Guardians
            opt Natural Person for Guardian (if not exists)
                P ->>+ T: POST /entities/natural-persons
                T -->>- P: OK
                T ->> PW: Natural Person Notification - CREATED
                P ->>+ T: POST /entities/natural-persons/{naturalPersonId}/identifications
                T -->>- P: OK
                T ->> PW: Natural Person Notification - UPDATED
                P ->>+ T: POST /v2/documents/sign
                T -->>- P: OK
                T ->> PW: Natural Person Notification - UPDATED
            end

            P ->>+ T: POST /roles/proxies
            T -->>- P: OK
            T ->> PW: Proxy Notification - CREATED

            opt Child Customer with single custody
                loop Guardian Documents
                    P ->>+ T: POST /v2/documents
                    T -->>- P: OK
                    T ->> PW: Document Notification - CREATED
                end
            end
        end
    end

    P ->>+ T: POST /roles/onboardings (Customer onboarding)
    T -->>- P: OK
    T ->> PW: Onboarding Notification - CREATED
    T ->> PW: Onboarding Notification - PENDING
    T ->> PW: Natural Person Notification - PENDING
    T ->> PW: Customer Notification - PENDING

    opt For Child Customer
        loop Customer Guardians
            T ->> PW: Proxy Notification - PENDING
            T ->> PW: Natural Person Notification - PENDING
            loop Guardian Documents
                T ->> PW: Document Notification - PENDING
            end
        end
    end

    loop Natural Person Documents
        T ->> PW: Document Notification - PENDING
    end

    T ->> PW: Onboarding Notification - APPROVED
    T ->> PW: Natural Person Notification - ACTIVE
    T ->> PW: Customer Notification - ACTIVE

    opt For Child Customer
        loop Customer Guardians
            T ->> PW: Proxy Notification - ACTIVE
            T ->> PW: Natural Person Notification - ACTIVE
            loop Guardian Documents
                T ->> PW: Document Notification - APPROVED
            end
        end
    end

    loop Natural Person Documents
        T ->> PW: Document Notification - APPROVED
    end
```

The natural person onboarding process may encounter several different scenarios:

1. **Manual Review Required**: If data provided in `POST /entities/natural-persons` requires manual review, the Natural\
   Person status is set to REVIEW and the partner is notified.
2. **Natural Person Verification Failed**: If data provided in `POST /entities/natural-persons` is deemed invalid, the\
   Natural Person status is set to REJECTED and the partner is notified.
3. **Customer Verification Failed**: If data provided during customer role creation is invalid, the Customer status is\
   set to REJECTED and the partner is notified.
4. **Onboarding Validation Failed**: If data validation fails during `POST /roles/onboardings`, the status is changed\
   from PENDING to REJECTED for all relevant roles and entities, and the partner is notified.
5. **KYC Verification Failed**: If KYC verification fails for any entity or role, a manual verification process is\
   initiated and status REVIEW is set. The review process awaits administrator action, who can accept or reject the\
   entity or role.

### Legal Entity Customer Onboarding Sequence

For legal entity customers, the onboarding process will:

1. Verify and activate the customer role
2. Verify and activate the underlying legal entity
3. Verify and activate all beneficial owners associated with the legal entity
4. Verify and activate all proxies roles (e.g., signatories) associated with the customer
5. Verify and activate all natural persons associated with the role of proxy
6. Verify and approve all required documents

```mermaid
sequenceDiagram
    participant PW as Partner's webhook
    participant P as Partner's API Client
    participant T as Our API
    autonumber

    opt Search Legal Entities
        P ->>+ T: GET /entities/vendor/legal-entities
        T -->>- P: OK
    end

    opt Prepare Legal Entities
        P ->>+ T: POST /entities/vendor/legal-entities
        T -->>- P: OK
        T ->> PW: Legal Entity Search Notification - COMPLETED
    end

    P ->>+ T: POST /entities/legal-entities
    T -->>- P: OK
    T ->> PW: Legal Entity Notification - CREATED

    opt Fetched Documents
        loop Auto-created Documents
            T ->> PW: Document Notification - CREATED
        end
    end

    loop Legal Representatives
        P ->>+ T: POST /entities/{legalEntityId}/legal-representatives
        T -->>- P: OK
        T ->> PW: Legal Representative Notification - CREATED
    end

    opt Beneficial Owners
        loop Beneficial Owners
            P ->>+ T: POST /entities/{legalEntityId}/beneficial-owners
            T -->>- P: OK
            T ->> PW: Beneficial Owner Notification - CREATED
        end
    end

    opt Legal Entity Documents
        loop Legal Entity Documents
            P ->>+ T: POST /v2/documents
            T -->>- P: OK
            T ->> PW: Document Notification - CREATED
        end
    end

    P ->>+ T: POST /roles/customers
    T -->>- P: OK
    T ->> PW: Customer Notification - CREATED

    loop Proxies (e.g., Signatories)
        opt Natural Person for Proxy (if not exists)
            P ->>+ T: POST /entities/natural-persons
            T -->>- P: OK
            T ->> PW: Natural Person Notification - CREATED

            alt Document Upload Method
                P ->>+ T: POST /entities/natural-persons/{naturalPersonId}/identifications
                T -->>- P: OK
                T ->> PW: Natural Person Notification - UPDATED

                loop Natural Person Documents
                    P ->>+ T: POST /v2/documents
                    T -->>- P: OK
                    T ->> PW: Document Notification - CREATED
                end
            else External Verifier Method
                P ->>+ T: POST /entities/identification-verifications
                T -->>- P: OK (with identificationUrl)
                Note over P: Partner redirects user to identificationUrl
                Note over T: External verification completed
                T ->> PW: Document Notification - CREATED (auto-generated IDENTIFICATION_CERTIFICATE)
                T ->> PW: Natural Person Notification - UPDATED (identity record created)
            end

            P ->>+ T: POST /v2/documents/sign
            T -->>- P: OK
            T ->> PW: Natural Person Notification - UPDATED
        end

        P ->>+ T: POST /roles/proxies
        T -->>- P: OK
        T ->> PW: Proxy Notification - CREATED

        loop Proxy Documents
            P ->>+ T: POST /v2/documents
            T -->>- P: OK
            T ->> PW: Document Notification - CREATED
        end
    end

    P ->>+ T: POST /roles/onboardings (Customer onboarding)
    T -->>- P: OK
    T ->> PW: Onboarding Notification - CREATED
    T ->> PW: Onboarding Notification - PENDING
    T ->> PW: Legal Entity Notification - PENDING
    T ->> PW: Customer Notification - PENDING

    loop Beneficial Owners
        T ->> PW: Beneficial Owner Notification - PENDING
    end

    loop Proxies
        T ->> PW: Natural Person Notification - PENDING
        T ->> PW: Proxy Notification - PENDING

        loop Natural Person Documents
            T ->> PW: Document Notification - PENDING
        end

        loop Proxy Documents
            T ->> PW: Document Notification - PENDING
        end
    end

    loop Legal Entity Documents
        T ->> PW: Document Notification - PENDING
    end

    T ->> PW: Onboarding Notification - APPROVED
    T ->> PW: Legal Entity Notification - ACTIVE
    T ->> PW: Customer Notification - ACTIVE

    loop Beneficial Owners
        T ->> PW: Beneficial Owner Notification - ACTIVE
    end

    loop Proxies
        T ->> PW: Proxy Notification - ACTIVE
        T ->> PW: Natural Person Notification - ACTIVE

        loop Natural Person Documents
            T ->> PW: Document Notification - APPROVED
        end

        loop Proxy Documents
            T ->> PW: Document Notification - APPROVED
        end
    end

    loop Legal Entity Documents
        T ->> PW: Document Notification - APPROVED
    end
```

The legal entity onboarding process may encounter several different scenarios:

1. **Manual Review Required**: If data provided in `POST /entities/legal-entities` requires manual review, the Legal Entity status is set to REVIEW and the partner is notified. In this case, the partner must wait until an administrator reviews and approves the data. Once approved by the administrator, the onboarding process will continue automatically. If the data is rejected by the administrator, not only the Legal Entity status will be set to REJECTED, but also the status of the onboarding and all related entities (customer role, proxies, beneficial owners, etc.) will be changed to REJECTED, effectively stopping the entire onboarding process.
2. **Onboarding Validation Failed**: There are two different scenarios that can occur when validation fails during `POST /roles/onboardings`:

   a) **Fixable Validation Issues**: If the validation failure is related to issues that can be fixed (such as missing documents or missing proxy), only the onboarding status is set to REJECTED while all related elements return to their CREATED status. The partner is notified about the specific validation errors and must make the necessary corrections (adding the missing document or proxy) before initiating a new onboarding request.

   b) **Critical Validation Issues**: If the validation failure involves sensitive data that cannot be corrected or if the entity should not be onboarded in the system for compliance reasons, all elements of the onboarding will be rejected:

   * Onboarding
   * Legal Entity
   * Customer role
   * All Beneficial Owners related to the Legal Entity
   * All Proxies related to the Legal Entity
   * All Natural Person related to the Proxy

   The partner is notified about the validation outcome in both cases.
3. **KYC Verification Failed**: If KYC verification fails for any role or entity (customer, proxies, beneficial owners), a manual verification process is initiated and status REVIEW is set. The review process awaits administrator action, who can accept or reject the role or entity.

   If the administrator accepts the role or entity, the process continues with activation of:

   * Onboarding
   * Legal Entity
   * Customer role
   * Legal Entity Documents
   * All Beneficial Owners related to the Legal Entity
   * All Proxies related to the Legal Entity
   * All Natural Person related to the Proxy

   If any role or entity is rejected by the administrator, the onboarding process stops, the onboarding status changes to REJECTED, and the following are globally rejected:

   * Legal Entity
   * Customer role
   * All Proxies related to the Legal Entity
   * Proxies customers (when proxy type is other than General\_Power\_of\_Attorney/Liquidator/Information\_Proxy)
   * All Beneficial Owners related to the Legal Entity

   The partner is notified about all changes.
4. **Resource Validation Failed**: During the preparation process, any resource being created might fail validation checks. This includes natural persons, legal entities, beneficial owners, legal representatives, customer roles, proxy roles, or documents. In such cases, the resource status is set to INVALID, and the partner receives a notification with the specific validation errors. The partner must correct the data and retry the creation step before proceeding with the onboarding process. Examples of such validation failures include:
   * Missing required fields
   * Invalid data formats
   * Business rule violations
   * Inconsistent data across related resources

### Joint Person Customer Onboarding Sequence

```mermaid
sequenceDiagram
    participant PW as Partner's webhook
    participant P as Partner's API Client
    participant T as Our API
    autonumber
    P ->>+ T: POST /entities/natural-persons (Person 1)
    T -->>- P: OK
    T ->> PW: Natural Person Notification - CREATED

    alt Document Upload Method (Person 1)
        P ->>+ T: POST /entities/natural-persons/{naturalPersonId}/identifications
        T -->>- P: OK
        T ->> PW: Natural Person Notification - UPDATED
    else External Verifier Method (Person 1)
        P ->>+ T: POST /entities/identification-verifications
        T -->>- P: OK (with identificationUrl)
        Note over P: Partner redirects user to identificationUrl
        Note over T: External verification completed
        T ->> PW: Document Notification - CREATED (auto-generated IDENTIFICATION_CERTIFICATE)
        T ->> PW: Natural Person Notification - UPDATED (identity record created)
    end

    P ->>+ T: POST /entities/natural-persons (Person 2)
    T -->>- P: OK
    T ->> PW: Natural Person Notification - CREATED

    alt Document Upload Method (Person 2)
        P ->>+ T: POST /entities/natural-persons/{naturalPersonId}/identifications
        T -->>- P: OK
        T ->> PW: Natural Person Notification - UPDATED
    else External Verifier Method (Person 2)
        P ->>+ T: POST /entities/identification-verifications
        T -->>- P: OK (with identificationUrl)
        Note over P: Partner redirects user to identificationUrl
        Note over T: External verification completed
        T ->> PW: Document Notification - CREATED (auto-generated IDENTIFICATION_CERTIFICATE)
        T ->> PW: Natural Person Notification - UPDATED (identity record created)
    end

    P ->>+ T: POST /entities/joint-persons
    T -->>- P: OK
    T ->> PW: Joint Person Notification - CREATED

    loop Both Natural Persons Documents (if using Document Upload Method)
        P ->>+ T: POST /v2/documents
        T -->>- P: OK
        T ->> PW: Document Notification - CREATED
    end

    P ->>+ T: POST /roles/customers
    T -->>- P: OK
    T ->> PW: Customer Notification - CREATED
    P ->>+ T: POST /roles/onboardings (Customer onboarding)
    T -->>- P: OK
    T ->> PW: Onboarding Notification - CREATED
    T ->> PW: Onboarding Notification - PENDING
    T ->> PW: Joint Person Notification - PENDING
    T ->> PW: Natural Person Notification - PENDING (Both persons)
    T ->> PW: Customer Notification - PENDING
    T ->> PW: Onboarding Notification - APPROVED
    T ->> PW: Joint Person Notification - ACTIVE
    T ->> PW: Natural Person Notification - ACTIVE (Both persons)
    T ->> PW: Customer Notification - ACTIVE
```

The joint person onboarding process may encounter several different scenarios:

1. **Manual Review Required**: If data provided in `POST /entities/natural-persons` for either person requires manual\
   review, the Natural Person status is set to REVIEW and the partner is notified.
2. **Natural Person Verification Failed**: If data provided in `POST /entities/natural-persons` for either person is\
   deemed invalid, the Natural Person status is set to REJECTED and the partner is notified.
3. **Customer Verification Failed**: If data provided during customer role creation is invalid, the Customer status is\
   set to REJECTED and the partner is notified.
4. **Onboarding Validation Failed**: If data validation fails during `POST /roles/onboardings`, the status is changed\
   from PENDING to REJECTED for all relevant roles and entities, and the partner is notified:
   * Onboarding
   * Joint Person
   * Customer role
   * All Joint Person Natural Persons documents
5. **KYC Verification Failed**: If KYC verification fails for any role or entity, a manual verification process is\
   initiated and status REVIEW is set. The review process awaits administrator action, who can accept or reject the role or entity.

   If the administrator accepts the role or entity, the process continues with activation of:

   * Onboarding
   * Customer
   * First Natural Person
   * Second Natural Person
   * Natural Persons Documents
   * All Customer Proxies roles
   * All Customer Proxies Documents

   If any role or entity is rejected by the administrator, the onboarding process stops, the onboarding status changes\
   to REJECTED, and the following are globally rejected:

   * First Natural Person
   * Second Natural Person
   * Joint Person
   * Customer role
   * Proxies related to joint person
   * Proxies customers (when proxy type is other than General\_Power\_of\_Attorney/Liquidator/Information\_Proxy)

   The partner is notified about all changes.

### Proxy Onboarding Sequence

```mermaid
sequenceDiagram
    participant PW as Partner's webhook
    participant P as Partner's API Client
    participant T as Our API
    autonumber
    P ->>+ T: POST /entities/natural-persons
    T -->>- P: OK
    T ->> PW: Natural Person Notification - CREATED

    alt Document Upload Method
        P ->>+ T: POST /entities/natural-persons/{naturalPersonId}/identifications
        T -->>- P: OK
        T ->> PW: Natural Person Notification - UPDATED

        loop Natural Person Documents
            P ->>+ T: POST /v2/documents
            T -->>- P: OK
            T ->> PW: Document Notification - CREATED
        end
    else External Verifier Method
        P ->>+ T: POST /entities/identification-verifications
        T -->>- P: OK (with identificationUrl)
        Note over P: Partner redirects user to identificationUrl
        Note over T: External verification completed
        T ->> PW: Document Notification - CREATED (auto-generated IDENTIFICATION_CERTIFICATE)
        T ->> PW: Natural Person Notification - UPDATED (identity record created)
    end

    P ->>+ T: POST /roles/proxies
    T -->>- P: OK
    T ->> PW: Proxy Notification - CREATED

    loop Proxy Documents
        P ->>+ T: POST /v2/documents/
        T -->>- P: OK
        T ->> PW: Document Notification - CREATED
    end

    P ->>+ T: POST /roles/onboardings (Proxy onboarding)
    T -->>- P: OK
    T ->> PW: Onboarding Notification - CREATED
    T ->> PW: Onboarding Notification - PENDING
    T ->> PW: Natural Person Notification - PENDING
    T ->> PW: Proxy Notification - PENDING
    T ->> PW: Onboarding Notification - APPROVED
    T ->> PW: Natural Person Notification - ACTIVE
    T ->> PW: Proxy Notification - ACTIVE
```

The proxy onboarding process may encounter several different scenarios:

1. **Natural Person Verification Failed**: If data provided in `POST /entities/natural-persons` is deemed invalid, the\
   Natural Person status is set to REJECTED and the partner is notified.
2. **Proxy Creation Failed**: If data provided in `POST /roles/proxies` is deemed invalid, the Proxy status is set to\
   REJECTED and the partner is notified.
3. **Onboarding Validation Failed**: If data validation fails during `POST /roles/onboardings`, the onboarding process\
   stops and the status is changed from PENDING to REJECTED for the following:

   * Onboarding
   * Proxy role
   * All Natural Person and Proxy documents

   The partner is notified about these changes.
4. **KYC Verification Failed**: If KYC verification fails, a manual verification process is initiated with status REVIEW set. The review process awaits administrator action, who can accept or reject the role or entity.

### Beneficial Owner Onboarding Sequence

```mermaid
sequenceDiagram
    participant PW as Partner's webhook
    participant P as Partner's API Client
    participant T as Our API
    autonumber
    P ->>+ T: POST /entities/{legalEntityId}/beneficial-owners
    T -->>- P: OK
    T ->> PW: Beneficial Owner Notification - CREATED
    P ->>+ T: POST /entities/onboardings (Beneficial Owner onboarding)
    T -->>- P: OK
    T ->> PW: Onboarding Notification - CREATED
    T ->> PW: Onboarding Notification - PENDING
    T ->> PW: Beneficial Owner Notification - PENDING
    T ->> PW: Onboarding Notification - APPROVED
    T ->> PW: Beneficial Owner Notification - ACTIVE
```

The beneficial owner onboarding process may encounter several different scenarios:

1. **Beneficial Owner Creation Failed**: If data provided in `POST /entities/{legalEntityId}/beneficial-owners` is\
   deemed invalid, the Beneficial Owner status is set to REJECTED and the partner is notified.
2. **Onboarding Validation Failed**: If data validation fails during `POST /entities/onboardings` or KYC verification\
   fails, the onboarding process stops and the status is changed from PENDING to REJECTED for the following:

   * Onboarding
   * Beneficial Owner

   The partner is notified about these changes.
3. **KYC Verification Failed**: If KYC verification fails, a manual verification process is initiated with status REVIEW set. The review process awaits administrator action, who can either accept or reject the entity.


---

# 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/documentation/entity_role_management_after_refactor/onboarding.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.