# Onboarding

* [Onboarding](#onboarding)
  * [Onboarding Process Overview](#onboarding-process-overview)
  * [Entity Preparation](#entity-preparation)
    * [Natural Person Preparation](#natural-person-preparation)
      * [Adult Natural Person](#adult-natural-person)
      * [Child Natural Person](#child-natural-person)
      * [Natural Person Wizard](#natural-person-wizard)
      * [Identification Verification](#identification-verification)
    * [Legal Entity Preparation](#legal-entity-preparation)
      * [Legal Entity Preparation Steps](#legal-entity-preparation-steps)
    * [Joint Person Preparation](#joint-person-preparation)
    * [Beneficial Owner Preparation](#beneficial-owner-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)
      * [Natural Person Customer Onboarding](#natural-person-customer-onboarding)
      * [Legal Entity Customer Onboarding](#legal-entity-customer-onboarding)
      * [Joint Person Customer Onboarding](#joint-person-customer-onboarding)
    * [Proxy Onboarding](#proxy-onboarding)
    * [Beneficial Owner Onboarding](#beneficial-owner-onboarding)
  * [Document Management](#document-management)
    * [Document Endpoints](#document-endpoints)
    * [Document Types](#document-types)
  * [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. **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
* Verification of reference accounts via SEPA (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 Preparation

#### Adult Natural Person

To prepare an adult natural person entity, the partner must:

1. Send natural person data using the `POST /entities/natural-persons` endpoint
2. Send natural person identification data using `POST /entities/natural-persons/{naturalPersonId}/identifications`
3. Upload verification document using `POST /v2/documents` endpoint with the appropriate `resourceType` (NATURAL\_PERSON) and `resourceId` (naturalPersonId)
4. Sign required documents using the `POST /v2/documents/sign` endpoint, providing the `partnerDocumentId`, `naturalPersonId`, and optionally `customerId` for terms and conditions

#### Child Natural Person

Preparing a child natural person entity (under 18 years old) requires:

1. Create the child's natural person record using `POST /entities/natural-persons`
2. Send identification data using `POST /entities/natural-persons/{naturalPersonId}/identifications`
3. In the child's contact information, provide the contact details of one of the guardians
4. Upload required documents for the child entity using `POST /v2/documents` with document type `BIRTH_CERTIFICATE`
5. For the guardian of the child, execute `POST /v2/documents/sign` which requires the natural person id and partner document id.\
   Additionally, it is required to sign a Terms and Conditions document in the context of the customer\
   (customer id should be set in request body) for which the proxy is being set up.\
   Data Privacy Policy should only be signed if the natural person has not already signed it (without customer context)

Guardians for child natural persons will be created separately and linked through proxy relationships during role assignment.

#### Natural Person Wizard

The Natural Person Wizard is a tool that helps partners create natural persons. It provides a step-by-step guide for entering all necessary information. To create a new wizard instance, partners should execute `POST /entities/wizards/natural-persons`.

The Natural Person Wizard includes the following sections:

* **Personal Data**
* **Birth Data**
* **Address Data**
* **Contact**
* **Risk Data**
* **Tax Data**
* **Employment Data**
* **Asset Disclosures Data**

Partners can update any number of sections using `PATCH /entities/wizards/natural-persons/{wizardId}`. When the data is considered complete, setting the `createNaturalPerson` flag to true will create a natural person based on the provided data.

#### Identification Verification

During the onboarding process, each natural person must be identified as per KYC requirements. Partners have two options for identification verification:

1. **Document Upload Method**: Partners can upload a certificate of identification through the `POST /v2/documents` endpoint (with document type `IDENTIFICATION_CERTIFICATE`) and create an identity record through `POST /entities/natural-persons/{naturalPersonId}/identifications`.
2. **External Verifier Method**: Partners can use the `POST /entities/identification-verifications` endpoint to initiate an identification verification process with an external service provider (currently supporting WebID with VIDEO\_IDENT identification type).

When using the external verifier method:

1. Create a verification request using `POST /entities/identification-verifications` with the natural person ID, external verifier type, and identification type
2. Retrieve the verification link from the response's `identificationUrl` field or by using `GET /entities/identification-verifications/{identificationVerificationId}`
3. Upon successful completion of the verification process, the system will automatically:
   * Create a document of type `IDENTIFICATION_CERTIFICATE` attached to the natural person
   * Create an identity record (with identifying document metadata such as passport or national ID information)

The verification process status can be tracked using `GET /entities/identification-verifications/{identificationVerificationId}`, and a list of all verification attempts can be retrieved using `GET /entities/identification-verifications`.

### Legal Entity Preparation

#### Legal Entity Preparation Steps

To prepare a legal entity, the partner should:

1. **Search Legal Entities (Optional)**: Partners can search for existing legal entities using `GET /entities/vendor/legal-entities`. This endpoint fetches data from the Legal Entity Data Provider based on country and company name parameters.
2. **Prepare Legal Entity (Optional)**: Partners can prepare data for a legal entity using `POST /entities/vendor/legal-entities`, which returns a unique search ID for use in subsequent requests.
3. **Create Legal Entity**: Create the legal entity using `POST /entities/legal-entities`. If a search ID is provided, some data can be pre-populated from the previous step.
4. **Add Beneficial Owners**: Create beneficial owners for the legal entity using `POST /entities/{legalEntityId}/beneficial-owners`.
5. **Add Legal Representatives**: Add legal representatives using `POST /entities/{legalEntityId}/legal-representatives`.
6. **Upload Documents**: Upload required legal entity documents using `POST /v2/documents` with `resourceType` set to LEGAL\_ENTITY. Required document types may include:

   * `CURRENT_REGISTRY_EXTRACT`
   * `SHAREHOLDER_LIST`
   * `PARTNERSHIP_AGREEMENT`
   * `TRANSPARENCY_REGISTER_EXTRACT`
   * `BUSINESS_REGISTRATION`
   * `STATUTE`

   If a search ID was specified during creation, some documents may be automatically added.
7. **Transforming Legal Representatives (Optional)**: During customer validation, the system checks if beneficial owners\
   with type REAL\_UBO\_25 exist. If not, the platform automatically transforms legal representatives to fictive beneficial owners.\
   Notifications about the beneficial owner status (CREATED) are sent to the Partner's webhook server.

### Joint Person Preparation

To prepare a joint person entity, the partner must:

1. Create the first natural person using `POST /entities/natural-persons`
2. Send identification data for the first person using `POST /entities/natural-persons/{naturalPersonId}/identifications`
3. Create the second natural person using `POST /entities/natural-persons`
4. Send identification data for the second person using `POST /entities/natural-persons/{naturalPersonId}/identifications`
5. Create a joint person using `POST /entities/joint-persons` with the natural person IDs (np1Id, np2Id)
6. Upload verification documents for both persons using `POST /v2/documents` with `resourceType` set to NATURAL\_PERSON
7. Sign required documents for both natural persons using `POST /v2/documents/sign`

### Beneficial Owner Preparation

To prepare a beneficial owner entity for an existing legal entity, the partner must:

1. Create a beneficial owner using `POST /entities/{legalEntityId}/beneficial-owners`
2. Provide all required beneficial owner data in the request

## Role Assignment

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

### 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:

* Onboarding of the customer role
* Onboarding of all proxies associated with the customer
* Onboarding of all beneficial owners associated with the customer (for legal entity customers)

To start the customer onboarding process, use:

```
POST /roles/onboardings
```

The customer onboarding process is the primary method for onboarding new customers to the system and will handle all related entities in a single process.

#### Natural Person Customer Onboarding

For natural person customers, the onboarding process will:

1. Verify and activate the customer role
2. Verify and activate the underlying natural person entity
3. Verify and activate all associated proxies roles (e.g., guardians for child customers)
4. Verify and approve all required documents

#### Legal Entity Customer Onboarding

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 approve all required documents

#### Joint Person Customer Onboarding

For joint person customers, the onboarding process will:

1. Verify and activate the customer role
2. Verify and activate the underlying joint person entity
3. Verify and activate both natural persons comprising the joint person
4. Verify and activate any proxies roles associated with the customer
5. Verify and approve all required documents

### Proxy Onboarding

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

* Only handles the proxy role, not the entire customer profile
* Requires an already active customer
* 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.

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

## Document Management

The document management system has been restructured to align with the entity-role architecture separation, providing more precise document categorization based on the associated entity or role type.

### Document Endpoints

The document management API uses the following key endpoints:

* **Upload Document**: `POST /v2/documents/` - Used to upload documents for entities and roles with appropriate `resourceType` and `resourceId`
* **Sign Document**: `POST /v2/documents/sign` - Used to sign documents by natural persons
* **Get Document**: `GET /v2/documents/{documentId}` - Used to retrieve document metadata
* **Get Document File**: `GET /v2/documents/{documentId}/file` - Used to download document file content

When uploading or managing documents, always specify the correct resource type that matches the entity or role the document belongs to.

### Document Types

Each resource type supports specific document types:

1. **Natural Person Documents**:
   * General documents: `GENERAL`, `COMMUNICATION`, `MARKETING`, `TRAINING`, etc.
   * Identity verification: `IDENTIFICATION_CERTIFICATE`
   * Residence proof: `PROOF_OF_RESIDENCE`
   * Special cases: `BIRTH_CERTIFICATE`, `KYC`
2. **Legal Entity Documents**:
   * Registry information: `CURRENT_REGISTRY_EXTRACT`, `CHRONOLOGICAL_REGISTRY_EXTRACT`
   * Ownership documents: `SHAREHOLDER_LIST`, `TRANSPARENCY_REGISTER_EXTRACT`
   * Organizational documents: `PARTNERSHIP_AGREEMENT`, `STATUTE`, `BUSINESS_REGISTRATION`
   * Tax documents: `NON_ASSESSMENT_CERTIFICATE`
3. **Customer Documents**:
   * All customer types: `GENERAL`, `CONTRACTS`, `ONBOARDING`, `COMMUNICATION`, etc.
   * Natural person customers: additional `KYC` document types
4. **Proxy Documents**:
   * General documents: `GENERAL`, `CONTRACTS`, `ONBOARDING`, `KYC`, `COMMUNICATION`, etc.
   * Guardian-specific: `PROOF_OF_SINGLE_CUSTODY`, `PROOF_OF_CUSTODY`
   * Liquidator-specific: `INSOLVENCY_ORDER`
   * General proxy with death validity: `INHERITANCE_LEGITIMATION`
5. **Partner User Documents**:
   * `IDENTIFICATION_CERTIFICATE`

## Onboarding Scenarios and Sequence Diagrams

### Natural Person Customer Onboarding Sequence

{% @mermaid/diagram content="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

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

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

{% @mermaid/diagram content="sequenceDiagram
participant PW as Partner's webhook
participant P as Partner's API Client
participant T as Our API
autonumber

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

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

loop Legal Entity Documents
  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

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

    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
  
  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: Proxy Notification - PENDING
  T->>PW: Natural Person Notification - PENDING
  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 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.
2. **Customer Verification Failed**: If data provided during customer role creation is invalid, the Customer status is set to REJECTED and the partner is notified.
3. **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
   * Legal Entity
   * Customer role
   * All Beneficial Owners related to the Legal Entity
   * All Proxies related to the Legal Entity
   * All Proxies related to the Legal Entity Documents
4. **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 Proxies related to the Legal Entity 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:

   * 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.

### Joint Person Customer Onboarding Sequence

{% @mermaid/diagram content="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

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

P->>+T: POST /entities/natural-persons (Person 2)
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 /entities/joint-persons
T-->>-P: OK
T->>PW: Joint Person Notification - CREATED

loop Both Natural Persons Documents
  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/diagram content="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

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

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/diagram content="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.wawex.ai/documentation/4_entity_role_management_after_refactor/3_onboarding_after_refactor.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.