# Legal Entity - Partner Ident Service ## Legal Entity Onboarding - Partner Ident Service This guide describes the **happy-path onboarding** of a **legal entity customer** using the Tradevest API, where the partner performs the identification of natural persons externally. The onboarding process consists of a defined sequence of API calls that create and link the required entities, roles, documents, and authorizations before the final onboarding is triggered. The Tradevest API is **asynchronous by design**. Most create or update operations return either a UUID or an HTTP success status immediately. The current state of a resource can be retrieved at any time via the corresponding GET endpoints. In addition, Tradevest emits webhook notifications for relevant lifecycle events. ### Overview of Required Steps To onboard a legal entity as a customer, the following steps must be completed in the order listed below: 1. Prerequisites (Subscribe to Webhooks) 2. Create legal entity (`POST /entities/legal-entities`) 3. Create legal representatives (`POST /entities/{legalEntityId}/legal-representatives`) 4. Create beneficial owners (`POST /entities/{legalEntityId}/beneficial-owners`) 5. Create customer role for legal entity (`POST /roles/customers`) 6. Upload legal entity documents (`POST /v2/documents`) 7. Create natural persons (proxies) (`POST /entities/natural-persons`) 8. Create natural person identification (`POST /entities/natural-persons/{naturalPersonId}/identification`) 9. Upload identification certificate for natural persons (`POST /v2/documents`) 10. Create proxies (`POST /roles/proxies`) 11. Sign Tradevest legal documents (`POST /v2/documents/sign`) 12. Onboard legal entity as customer (`POST /roles/onboardings`) 13. Monitor onboarding status (`GET /roles/onboardings/{onboardingId}`) ## Before you get stared ### Legal Representatives, Beneficial Owners and Proxies {% hint style="info" %} This section explains the core differences and technical dependencies between these three resources. **Please read carefully**. {% endhint %} In the context of onboarding legal entities, it is essential to distinguish between **Legal Representatives**, **Beneficial Owners**, and **Proxies**. Although all three roles relate to natural persons connected to a legal entity, they serve fundamentally different purposes — both legally and technically within the Tradevest API. This section explains the legal meaning of each role and clarifies how they are represented and linked in the Tradevest system. Under corporate and financial regulation (e.g. AML/KYC frameworks): * A **Legal Representative** is a person who is legally authorized to represent the company. * A **Beneficial Owner (UBO)** is a natural person who ultimately owns or controls the company. * A **Proxy** is a person authorized by the company to act on its behalf within a defined scope. #### Legal Representatives **Legal Definition** A **legal representative** is a natural person who is authorized by law, corporate statutes, or commercial register entry to represent the legal entity externally. Typical examples: * Managing Director (GmbH) * Board Member (AG) * General Partner (KG) Legal representatives are defined by corporate law and registered in official registers (e.g. commercial register). They are responsible for: * Binding the company legally * Representing the company toward third parties * Acting within the powers defined in corporate documentation They do **not necessarily own the company**. **In the Tradevest API** * Legal representatives are created under: ``` POST /entities/{legalEntityId}/legal-representatives ``` Important clarifications: * At least one legal representative is required. * Legal representatives are not proxies. * Legal representatives cannot directly become proxies. If a legal representative should also act operationally on the platform, a separate `naturalPerson` must be created and later assigned as a `proxy`. * `legalRepresentatives` are entity-bound sub-resources. A `proxy` requires a standalone `naturalPerson` resource. * If no beneficial owner ≥ 25% exists, legal representatives may automatically be used to generate fictive beneficial owners for regulatory compliance. #### Beneficial Owners **Legal Definition** A **beneficial owner (Ultimate Beneficial Owner – UBO)** is a natural person who ultimately owns or controls a legal entity. Under AML regulations, this usually means: * A person who owns directly or indirectly **25% or more** of the shares or voting rights. * If no such person exists, a fictive UBO must be identified. Beneficial ownership reflects **economic control**, not operational authority. A beneficial owner: * May not be involved in daily operations * May not be authorized to represent the company * May not be a platform user **In the Tradevest API** * Beneficial owners are created under: ``` POST /entities/{legalEntityId}/beneficial-owners ``` * Classified as: * `REAL_UBO_25` * `FICTIVE_UBO` * Used exclusively for regulatory validation. * Do **not automatically gain operational permissions**. {% hint style="info" %} Beneficial owners are mandatory for the onboarding process. If there is no beneficial owner created, each `legalRepresentative` is automatically converted into a fictive beneficial owner with: * `boType: FICTIVE_UBO` * 0% share allocation * 0% voting rights allocation * PENDING status * All personal data is copied from the legal representative record {% endhint %} #### Proxy **Legal Definition** A **Proxy** is a natural person authorized by the company to act on its behalf within a defined scope. This authorization is typically granted internally by the company (e.g. via power of attorney). Unlike legal representatives: * A proxy may not be registered in official registers. * Will be able to initiate actions (e.g. transfers, orders, etc.) through the Tradevest API. Unlike beneficial owners: * A proxy does not need to own any shares. * Authority is functional, not ownership-based. **In the Tradevest API** * Proxies are created under: ``` POST /roles/proxies ``` * A proxy must reference: * `naturalPersonId` * `entityId` * Proxies define: * `proxyType` (e.g. SIGNATORY) * `scopeType` (e.g. INDIVIDUAL) * Only proxies with `proxyType = SIGNATORY` may sign legal documents. * The naturalPersons for each proxy must undergo the identification process (e.g. video ident) {% hint style="info" %} Although a `legalRepresentative` may have similar authority to a `proxy` in practice, the Tradevest API treats these roles as distinct resources. If identical personal data is provided when creating the `naturalPerson`, the system will internally match it with the existing `legalRepresentative` record. This matching is required to ensure regulatory consistency, but both resources remain technically separate. {% endhint %} #### How to handle Beneficial Owners, Legal Representatives and Proxies in your UI The complexity and overlap between these three resources must be considered in your UI design. In a nutshell the following requirements must be considered: * If there are **no beneficial owners** created for the legal Entity, the legal representatives will be created as beneficial owners. In order for this to be processed successfully you must also provide the following information about the legal representatives: * `taxResidency` * `taxId` (if `taxResidency ≠ DE`) * `mainAddress{...}` * If a legal representative should also act as a **proxy**, you must also provide the additional information about the legal representative: * `contact.phone` * `contact.email` ## 0. Prerequisites ### Webhook Event Before starting the onboarding process, ensure that webhook subscriptions are configured for the following event types, which are required to monitor the lifecycle of the onboarding process: * `LEGAL_ENTITY_NOTIFICATION` * `LEGAL_REPRESENTATIVE_NOTIFICATION` * `BENEFICIAL_OWNER_NOTIFICATION` * `PROXY_NOTIFICATION` * `CUSTOMER_NOTIFICATION` * `NATURAL_PERSON_NOTIFICATION` * `DOCUMENT_NOTIFICATION` * `ONBOARDING_NOTIFICATION` Webhook notifications are strongly recommended. If webhooks are not configured, partners must actively poll the corresponding `GET` endpoints to retrieve status updates. It is important to note though, that error reasons are only returned via webhook notifications. Refer to the [**API Reference – Webhooks**](https://docs.tradevest.ai/api-reference/webhooks) section for instructions on how to create, update, and delete webhook subscriptions, and to the [**Partner Webhooks**](https://docs.tradevest.ai/api-reference/webhooks) section for details on webhook payloads. ## 1. Create Legal Entity After collecting all required information from the legal entity to be onboarded, create the legal entity using the following request. Additional **required** parameters include: * `legalEntityIdentifier`: if you create a product with `productCode: DEPOSITORY_ACCOUNT` for the customer. To retrieve valid `naceSectors` values, refer to the corresponding section in the [API Reference](https://docs.tradevest.ai/api-reference/entities/search-nace-sectors#get-entities-legal-entities-search-nace-sectors). **Request** ``` POST /entities/legal-entities { "legalName": "TechNova Solutions GmbH", "legalForm": "LIMITED_LIABILITY_COMPANY", "naceSectors": [ { "section": "C", "code": "26.40", "description": "Manufacture of consumer electronics" } ], "registerCountry": "DE", "registerNumber": "HRB123456", "registerCourt": "Amtsgericht München", "foundedOn": "2015-03-15", "mainAddress": { "street": "Maximilianstraße", "streetNumber": "12", "city": "Munich", "zip": "80333", "state": "Bavaria", "country": "DE" }, "contact": { "phone": "+49 89 12345678", "email": "info@technovasolutions.de" }, "taxNumber": "DE123456789", "fatcaCrsDeclaration": { "isForeignTaxResidency": false, "isSanctionedCountries": false, "fatcaClassification": "ACTIVE_NFE", "activeNfeType": "LE_BY_INCOME_ASSETS" } } ``` **Response** ``` { "legalEntityId": "90d741f0-f8ba-4f9b-9b87-18d4bff1a941" } ``` A subsequent `GET /entities/legal-entities/{legalEntityId}` request returns the full legal entity resource, including the following system-generated fields: * `globalId` – A Tradevest-wide unique identifier used to match legal entities across partners * `createdOn` * `modifiedOn` * `legalEntityStatus` The legal entity remains in `status: CREATED` until the onboarding process is explicitly triggered. ## 2. Create Legal Representatives Legal representatives are natural persons who are authorized to act on behalf of the legal entity (for example, to execute trades). At least **one legal representative is mandatory** for each legal entity. **Notes for Proxies:** Legal representatives may later be assigned proxy roles in order to act for the company as a signatory. As part of the onboarding at least one proxy must be created, which must be one of the legal representatives. In the Tradevest API these are considered two different resources though. Therefore we advise, that you collect the data for the natural Person once and if the customer selects one of the legal representatives to be the proxy, that you then reuse the data that was collected previously. What shall be considered, is that the dataset of a legal-representative and a proxy do not match 100%. Therefore when asking the customer for input, both input requirements have to be requested. {% hint style="info" %} The table below shows which parameters are required for each entity. {% endhint %} | **Tradevest API parameter** | **Legal Representative** | **Beneficial Owner** | **Natural Person as Proxy** | | --------------------------- | ----------------------------------------- | ------------------------------- | ------------------------------- | | `gender` | n/a | n/a | required | | `firstName` | required | required | required | | `lastname` | required | required | required | | `birthDay` | required | required | required | | `birthPlace` | required | required | required | | `birthCountry` | required | required | required | | `isUsNationality` | required | required | required | | `nationalities` | required | required | required | | `function` | required | n/a | n/a | | `soleSignatureAuthorized` | required | n/a | n/a | | `factaControllingPerson` | required | n/a | n/a | | `taxDetails.taxId` | required, if fatcaControllingPerson: true | required if taxResidency not DE | required if taxResidency not DE | | `taxDetails.taxResidency` | required, if fatcaControllingPerson: true | required | required | | `mainAddress{}` | not required | required | required | | `contact.phone` | n/a | n/a | required | | `contact.email` | n/a | n/a | required | | `uboRelationship` | n/a | required | n/a | | `share` | n/a | required | n/a | | `votingRigths` | n/a | required | n/a | **Request** ``` POST /entities/{legalEntityId}/legal-representatives { "firstName": "Alexandra", "lastName": "Mueller", "birthDay": "1985-07-14", "birthPlace": "Munich", "birthCountry": "DE", "isUsNationality": false, "nationalities": [ "DE" ], "function": "MANAGING_DIRECTOR", "soleSignatureAuthorized": true, "fatcaControllingPerson": false } ``` **Response** ``` { "legalRepresentativeId": "515e5964-b245-431b-9537-a56cf9bce899" } ``` For each legal representative, the Tradevest system automatically generates the following fields: * `globalId` * `createdOn` * `modifiedOn` * `status` Once all legal representatives have been created, proceed to the next step. ## 3. Create Beneficial Owners Beneficial owners must be created for each natural person who owns 25% or more directly or indirectly either of * the **legal entity** or * the **voting rights** Each such beneficial owner is assigned the type `REAL_UBO_25`. If no beneficial owner meeting this threshold exists, the system automatically creates **fictive beneficial owners** (`FICTIVE_UBO`) based on the legal representatives associated with the legal entity. This ensures regulatory compliance with beneficial ownership requirements. **Request** ``` { "firstName": "Elena", "lastName": "Schneider", "birthDay": "1979-11-02", "birthPlace": "Hamburg", "birthCountry": "DE", "taxDetails": [ { "taxId": "DE987654321", "taxResidency": "DE", "noTinConfirmation": false } ], "isUsNationality": false, "nationalities": [ "DE" ], "uboRelationship": "DIRECTLY_HOLDING_25", "share": 35, "votingRights": 35 } ``` **Response** ``` { "beneficialOwnerId": "b2e7cfa9-a912-472a-bee2-9ca7cd971b97" } ``` The corresponding `GET /entities/beneficial-owners/{beneficialOwnerId}` endpoint returns the full beneficial owner resource, including: * `globalId` * `status` * `boType` * `createdOn` * `modifiedOn` All required beneficial owners must be created before onboarding can be triggered. ## 4. Create Customer Role For Legal Entity To explicitly mark the legal entity as a customer, a customer role must be created. This step also defines the reference accounts used for incoming and outgoing funds. Creating a customer **does not** onboard the entity. It only assigns the `CUSTOMER` role and prepares the entity for onboarding. **Request** ``` POST /roles/customers { "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "entityType": "LEGAL_ENTITY", "refAccounts": [ { "bankName": "Deutsche Bank AG", "iban": "DE89370400440532013000", "bic": "DEUTDEFF", "type": "PRIMARY", "ownerName": "TechNova Solutions GmbH" } ] } ``` **Response** ``` { "customerId": "18320faf-b998-4fab-9912-a14eda099a26" } ``` The customer resource can be retrieved via `GET /roles/customers/{customerId}`. Parameters created by the Tradevest system include: * `customerId` * `customerStatus` * `createdOn` * `modifiedOn` ## 5. Upload Legal Entity Documents Tradevest relies on partners to perform KYC/KYB checks. To ensure regulatory compliance, specific legal entity documents must be uploaded. Documents are uploaded using `POST /v2/documents`. Each document must include metadata and be linked to the relevant entity. All document upload requests must include the `Requestor-Id` header set to the `naturalPersonId` which is uploading the file. The required document types depend on the legal form of the entity:
legalFormdocumentType
LIMITED_LIABILITY_COMPANYCURRENT_REGISTRY_EXTRACT, SHAREHOLDER_LIST
PUBLIC_LIMITED_COMPANYCURRENT_REGISTRY_EXTRACT, TRANSPARENCY_REGISTER_EXTRACT
FOUNDATIONCURRENT_REGISTRY_EXTRACT, STATUTE
ASSOCIATIONSTATUTE
REGISTERED_BUSINESSMANCURRENT_REGISTRY_EXTRACT
LIMITED_PARTNERSHIPCURRENT_REGISTRY_EXTRACT, TRANSPARENCY_REGISTER_EXTRACT
GENERAL_PARTNERSHIPCURRENT_REGISTRY_EXTRACT, SHAREHOLDER_LIST, TRANSPARENCY_REGISTER_EXTRACT
LIMITED_LIABILITY_COMPANY_AND_LIMITED_PARTNERSHIPCURRENT_REGISTRY_EXTRACT, SHAREHOLDER_LIST, TRANSPARENCY_REGISTER_EXTRACT
PARTNERSHIPPARTNERSHIP_AGREEMENT
Furthermore the following must be considered: * Allowed File MIME types: PDF only * Maximum File Size: 6 MB Onboarding will fail if not all mandatory legal entity documents have been uploaded. **Request** ``` POST /v2/documents { "document": { "name": "Registry Extract", "resourceType": "LEGAL_ENTITY", "type": "CURRENT_REGISTRY_EXTRACT", "resourceId": "90d741f0-f8ba-4f9b-9b87-18d4bff1a941" }, "file": "binary" } ``` **Response** ``` { "documentId": "1a1e3a46-2b99-48b8-a8c8-15b747af2095" } ``` Once this step is successfully completed all information about the legal entity has been provided and the proxies for signatories have to be created in order to allow these people to act for the company. ## 6. Create Natural Person for Proxy Natural persons who will later be authorized to act on behalf of the legal entity (signatories) must be created. These persons may be legal representatives or other individuals designated by the entity. **Request** ``` POST /entities/natural-persons { "gender": "MALE", "firstName": "Lukas", "lastName": "Weber", "birthDay": "1997-10-20", "birthPlace": "Berlin", "birthCountry": "DE", "nationalities": [ { "countryCode": "DE" } ], "taxDetails": [ { "taxId": "4243882385647", "taxResidency": "DE" } ], "isUsNationality": false, "mainAddress": { "street": "Bakalarska", "streetNumber": "34", "city": "Berlin", "zip": "22-333", "country": "DE" }, "contact": { "phone": "123456789", "email": "tvdtester90+707845139@gmail.com" } } ``` **Response** ``` { "naturalPersonId": "cc2a0ccd-734c-4ad9-bbbe-c27eab2fdd7a" } ``` ## 7. Create Natural Person Identification Since partners perform identification externally, the identification results must be transferred to Tradevest. **Request** ``` POST /entities/natural-persons/{naturalPersonId}/identification { "externalVerifier": "ID_NOW", "identificationType": "VIDEO_IDENT", "identificationDate": "2026-01-22", "identificationDocumentType": "ID", "documentNumber": "3859937928234", "documentCountry": "DE", "documentIssuer": "DE", "documentIssueDate": "2019-08-24", "documentExpiryDate": "2050-08-24" } ``` **Response** This request returns HTTP Code `202 Accepted`. ## 8. Upload Identification Certificate For each natural person acting as a proxy, an identification certificate summarizing the identification process must be uploaded. **Request** ``` POST /v2/documents { "name": "Identification Certificate", "type": "IDENTIFICATION_CERTIFICATE", "resourceType": "NATURAL_PERSON", "resourceId": "cc2a0ccd-734c-4ad9-bbbe-c27eab2fdd7a" } ``` **Response** ``` { "documentId": "c4ea16d1-322c-444d-9f72-f32b543ad7ed" } ``` ## 9. Create Proxies To authorize a natural person to act on behalf of the legal entity, create a proxy with `proxyType = SIGNATORY`. Only individual representation `scopeType: INDIVIDUAL` is currently supported. Multiple proxies may be created and can also be [added](https://docs.tradevest.ai/api-reference/roles/onboardings) or [deactivated](https://docs.tradevest.ai/api-reference/roles/offboarding) at a later stage. **Request** ``` { "proxyType": "SIGNATORY", "naturalPersonId": "cc2a0ccd-734c-4ad9-bbbe-c27eab2fdd7a", "entityId": "90d741f0-f8ba-4f9b-9b87-18d4bff1a941", "entityType": "LEGAL_ENTITY", "validityType": "UNLIMITED", "scopeType": "INDIVIDUAL" } ``` **Response** ``` { "proxyId": "16195271-d3da-4507-acc2-797b0236b37b" } ``` ## 10. Sign Tradevest Legal Documents Before onboarding, Tradevest legal documents (e.g. Terms and Conditions, Data Privacy Policy) must be presented to the customer and accepted. Only proxies with `proxyType = SIGNATORY` are authorized to sign these documents. The signing process consists of: 1. Retrieving valid documents 2. Downloading document files 3. Displaying documents to the user 4. User acceptance 5. Submitting the signature confirmation ### **Request valid documents to be signed** For each partner Tradevest uploads the valid legal documents and they will be accessible through the partner documents endpoint. In order to ensure that you are always referring to the valid document to show to the customer, the following request can be sent: **Requests** * `GET /partner-documents?isValid=true&documentType=DATA_PRIVACY_POLICY` * `GET /partner-documents?isValid=true&documentType=TERMS_AND_CONDITIONS` **Response (example for DATA\_PRIVACY\_POLICY)** ``` { "data": [ { "documentId": "09f7e302-be3b-4d4a-a654-95a872356dc7", "size": 136948, "version": 6, "validFrom": "2025-12-17", "name": "DPP", "type": "DATA_PRIVACY_POLICY", "createdOn": "2025-12-17T08:38:31.104169414Z", "modifiedOn": "2025-12-17T08:38:31.104169538Z" } ], "pagination": { "cursor": "", "limit": 20 } } ``` ### **Download document and show to customer** In order to download the most recent document send the following **Request** `POST /partner-documents/{documentId}/file` **Response** The response is a base64 decoded file, which must be encoded by the partners application. In the example above the response is heavily shortened through the dots in the center… ``` JVBERi0xLjMKJcTl8uXrp/O.....CiUlRU9GCg== ``` ### **Send Signature confirmation** After the customer has received the chance to read the document and acknowledge them by activating a checkbox a Sign request is sent. The naturalPersonId in the requests should be the one from the person that is signing the documents. **Request** (here only shown for one document) ``` POST /v2/documents/sign { "partnerDocumentId": "a23097ae-214b-4083-8f85-f74aaa9993ef", "naturalPersonId": "8696b558-d043-4cc1-a872-8b27ea3272f4", "customerId": "18320faf-b998-4fab-9912-a14eda099a26" } ``` **Response** This request only returns HTTP Code `202 Accepted`. ## 11. Onboard Legal Entity as Customer As the final step of the onboarding of a legal entity customer, the actual onboarding process has to be triggered for the legal entity. Make sure that all of the above steps have been executed correctly (entities statuses are valid, documents have been uploaded, required fields are provided). After triggering this process, some asynchronous processes are started, which will take a few seconds to minutes depending on the data load and complexity of the legal entity structure. Possible outcomes in this process are: 1. **Fixable Validation Issues**: If the validation failure is related to issues that can be fixed (e.g. 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. 2. **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. The partner is notified about the validation outcome in both cases. ### Trigger Onboarding Process **Request** ``` POST /roles/onboardings { "roleType": "CUSTOMER", "roleId": "{{customerId}}" } ``` **Response** ``` { "onboardingId": "c1e98eed-c7db-4453-8964-51819a8be6cd" } ``` ## 12. Monitor Onboarding Status By querying the onboardings endpoint and subscribing to `ONBOARDING_NOTIFICATION` webhooks you will monitor the onboarding process. After the initial `CREATED` status, the following statuses can be a result: * `INVALID`: In case of incorrect statuses on any of the entities that were created earlier. * `PENDING`: In case of successful validations of the entity statuses the onboarding status will change to `PENDING` while all background checks are conducted. * `APPROVED`: Once all background checks have been conducted successfully. * `REVIEW`: For companies not registered in Germany the background checks are not fully automated, thus the status will always be `REVIEW`. Also for some German companies a manual Review by the Tradevest Ops team will have to be conducted. * `REJECTED`: In case our compliance and risk rules do not approve of the customer. **Request** ``` GET /roles/onboardings/{onboardingId} ``` **Response** ``` { "onboardingId": "905050b4-e19c-4d0b-9d47-94611d1728d2", "status": "APPROVED", "roleType": "CUSTOMER", "roleId": "65f4dca7-b03e-423c-a32f-c04a7a7323d0", "createdOn": "2026-01-23T09:42:39.593204Z", "modifiedOn": "2026-01-23T10:00:08.256311Z" } ```