Onboarding

• Onboarding

  • Onboarding Process Overview

  • Entity Preparation

  • Role Assignment

    • Customer Role Assignment

    • Proxy Role Assignment

  • Onboarding Types

    • Customer Onboarding

      • How Customer Onboarding Works

      • Validation Types

      • Customer Type Specific Validations

        • Natural Person Customer Validations

        • Legal Entity Customer Validations

        • Joint Person Customer Validations

      • Proxy Specific Validations

      • Validation Process Flow

        • Validation Outcomes

      • KYC and Compliance Integration

      • Error Handling and Notifications

    • Proxy Onboarding

      • Proxy Onboarding Validation Types

    • Beneficial Owner Onboarding

  • Document Management

  • Onboarding Scenarios and Sequence Diagrams

    • Natural Person Customer Onboarding Sequence

    • Legal Entity Customer Onboarding Sequence

    • Joint Person Customer Onboarding Sequence

    • Proxy 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

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

• Legal Entity Preparation: For detailed information on preparing legal entities, including beneficial owners and legal representatives, see Legal Entity Management.

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.

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.

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.

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.

• Customer status must be CREATED (same as for all customer onboarding)

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

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.

Onboarding Scenarios and Sequence Diagrams

Natural Person Customer Onboarding Sequence

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

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

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

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

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.