Ctrlk

Onboarding

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:

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:

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:

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

spinner

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

spinner

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

spinner

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

spinner

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

spinner

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.

Last updated