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:
Entity Preparation - Creating and preparing the entity with all required data and documents
Role Assignment - Assigning appropriate roles to entities (customer, proxy)
Onboarding Initiation - Starting the appropriate onboarding process based on the entity type and business need
The platform offers three distinct onboarding processes:
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.Proxy Onboarding (Role) - A specialized process for adding a new proxy to an already active customer using
POST /roles/onboardingswith the appropriate type parameter.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 NotificationCustomer NotificationNatural Person NotificationJoint Person NotificationLegal Entity NotificationBeneficial Owner NotificationProxy NotificationDocument 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:
Send natural person data using the
POST /entities/natural-personsendpointSend natural person identification data using
POST /entities/natural-persons/{naturalPersonId}/identificationsUpload verification document using
POST /v2/documentsendpoint with the appropriateresourceType(NATURAL_PERSON) andresourceId(naturalPersonId)Sign required documents using the
POST /v2/documents/signendpoint, providing thepartnerDocumentId,naturalPersonId, and optionallycustomerIdfor terms and conditions
Child Natural Person
Preparing a child natural person entity (under 18 years old) requires:
Create the child's natural person record using
POST /entities/natural-personsSend identification data using
POST /entities/natural-persons/{naturalPersonId}/identificationsIn the child's contact information, provide the contact details of one of the guardians
Upload required documents for the child entity using
POST /v2/documentswith document typeBIRTH_CERTIFICATEFor the guardian of the child, execute
POST /v2/documents/signwhich 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:
Document Upload Method: Partners can upload a certificate of identification through the
POST /v2/documentsendpoint (with document typeIDENTIFICATION_CERTIFICATE) and create an identity record throughPOST /entities/natural-persons/{naturalPersonId}/identifications.External Verifier Method: Partners can use the
POST /entities/identification-verificationsendpoint 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:
Create a verification request using
POST /entities/identification-verificationswith the natural person ID, external verifier type, and identification typeRetrieve the verification link from the response's
identificationUrlfield or by usingGET /entities/identification-verifications/{identificationVerificationId}Upon successful completion of the verification process, the system will automatically:
Create a document of type
IDENTIFICATION_CERTIFICATEattached to the natural personCreate 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:
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.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.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.Add Beneficial Owners: Create beneficial owners for the legal entity using
POST /entities/{legalEntityId}/beneficial-owners.Add Legal Representatives: Add legal representatives using
POST /entities/{legalEntityId}/legal-representatives.Upload Documents: Upload required legal entity documents using
POST /v2/documentswithresourceTypeset to LEGAL_ENTITY. Required document types may include:CURRENT_REGISTRY_EXTRACTSHAREHOLDER_LISTPARTNERSHIP_AGREEMENTTRANSPARENCY_REGISTER_EXTRACTBUSINESS_REGISTRATIONSTATUTE
If a search ID was specified during creation, some documents may be automatically added.
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:
Create the first natural person using
POST /entities/natural-personsSend identification data for the first person using
POST /entities/natural-persons/{naturalPersonId}/identificationsCreate the second natural person using
POST /entities/natural-personsSend identification data for the second person using
POST /entities/natural-persons/{naturalPersonId}/identificationsCreate a joint person using
POST /entities/joint-personswith the natural person IDs (np1Id, np2Id)Upload verification documents for both persons using
POST /v2/documentswithresourceTypeset to NATURAL_PERSONSign 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:
Create a beneficial owner using
POST /entities/{legalEntityId}/beneficial-ownersProvide 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:
Assign the customer role to the entity using
POST /roles/customerswith theentityIdandentityTypeUpload required documents related to the customer role using
POST /v2/documents/withresourceTypeset to CUSTOMER
Proxy Role Assignment
To assign a proxy role, the partner must:
Ensure both the representing natural person and the entity to be represented are already created
Assign the proxy role using
POST /roles/proxieswith the natural person's ID and theentityIdandentityTypeof the entity to be representedUpload required proxy-specific documents using
POST /v2/documents/withresourceTypeset to PROXY:For Guardian proxies:
PROOF_OF_SINGLE_CUSTODY,PROOF_OF_CUSTODYFor Liquidator proxies:
INSOLVENCY_ORDERFor General Power of Attorney with death validity:
INHERITANCE_LEGITIMATIONFor 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:
Verify and activate the customer role
Verify and activate the underlying natural person entity
Verify and activate all associated proxies roles (e.g., guardians for child customers)
Verify and approve all required documents
Legal Entity Customer Onboarding
For legal entity customers, the onboarding process will:
Verify and activate the customer role
Verify and activate the underlying legal entity
Verify and activate all beneficial owners associated with the legal entity
Verify and activate all proxies roles (e.g., signatories) associated with the customer
Verify and approve all required documents
Joint Person Customer Onboarding
For joint person customers, the onboarding process will:
Verify and activate the customer role
Verify and activate the underlying joint person entity
Verify and activate both natural persons comprising the joint person
Verify and activate any proxies roles associated with the customer
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 appropriateresourceTypeandresourceIdSign Document:
POST /v2/documents/sign- Used to sign documents by natural personsGet Document:
GET /v2/documents/{documentId}- Used to retrieve document metadataGet 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:
Natural Person Documents:
General documents:
GENERAL,COMMUNICATION,MARKETING,TRAINING, etc.Identity verification:
IDENTIFICATION_CERTIFICATEResidence proof:
PROOF_OF_RESIDENCESpecial cases:
BIRTH_CERTIFICATE,KYC
Legal Entity Documents:
Registry information:
CURRENT_REGISTRY_EXTRACT,CHRONOLOGICAL_REGISTRY_EXTRACTOwnership documents:
SHAREHOLDER_LIST,TRANSPARENCY_REGISTER_EXTRACTOrganizational documents:
PARTNERSHIP_AGREEMENT,STATUTE,BUSINESS_REGISTRATIONTax documents:
NON_ASSESSMENT_CERTIFICATE
Customer Documents:
All customer types:
GENERAL,CONTRACTS,ONBOARDING,COMMUNICATION, etc.Natural person customers: additional
KYCdocument types
Proxy Documents:
General documents:
GENERAL,CONTRACTS,ONBOARDING,KYC,COMMUNICATION, etc.Guardian-specific:
PROOF_OF_SINGLE_CUSTODY,PROOF_OF_CUSTODYLiquidator-specific:
INSOLVENCY_ORDERGeneral proxy with death validity:
INHERITANCE_LEGITIMATION
Partner User Documents:
IDENTIFICATION_CERTIFICATE
Onboarding Scenarios and Sequence Diagrams
Natural Person Customer Onboarding Sequence
The natural person onboarding process may encounter several different scenarios:
Manual Review Required: If data provided in
POST /entities/natural-personsrequires manual review, the Natural Person status is set to REVIEW and the partner is notified.Natural Person Verification Failed: If data provided in
POST /entities/natural-personsis deemed invalid, the Natural Person status is set to REJECTED and the partner is notified.Customer Verification Failed: If data provided during customer role creation is invalid, the Customer status is set to REJECTED and the partner is notified.
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.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
The legal entity onboarding process may encounter several different scenarios:
Manual Review Required: If data provided in
POST /entities/legal-entitiesrequires manual review, the Legal Entity status is set to REVIEW and the partner is notified.Customer Verification Failed: If data provided during customer role creation is invalid, the Customer status is set to REJECTED and the partner is notified.
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
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
The joint person onboarding process may encounter several different scenarios:
Manual Review Required: If data provided in
POST /entities/natural-personsfor either person requires manual review, the Natural Person status is set to REVIEW and the partner is notified.Natural Person Verification Failed: If data provided in
POST /entities/natural-personsfor either person is deemed invalid, the Natural Person status is set to REJECTED and the partner is notified.Customer Verification Failed: If data provided during customer role creation is invalid, the Customer status is set to REJECTED and the partner is notified.
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
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:
Natural Person Verification Failed: If data provided in
POST /entities/natural-personsis deemed invalid, the Natural Person status is set to REJECTED and the partner is notified.Proxy Creation Failed: If data provided in
POST /roles/proxiesis deemed invalid, the Proxy status is set to REJECTED and the partner is notified.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.
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:
Beneficial Owner Creation Failed: If data provided in
POST /entities/{legalEntityId}/beneficial-ownersis deemed invalid, the Beneficial Owner status is set to REJECTED and the partner is notified.Onboarding Validation Failed: If data validation fails during
POST /entities/onboardingsor 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.
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
