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})

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 section for instructions on how to create, update, and delete webhook subscriptions, and to the Partner 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.

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": "[phone]",
    "email": "[email protected]"
  },
  "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.

Notes for Beneficial Owners & Legal Representatives:

The table below shows which parameters are required for each endpoint. The sum of all fields is needed for a legal representative that shall be a Proxy.

Tradevest API parameter	Legal Representative	Natural Person as Proxy
gender	n/a	required
firstName	required	required
lastname	required	required
birthDay	required	required
birthPlace	required	required
birthCountry	required	required
isUsNationality	required	required
nationalities	required	required
function	required	n/a
soleSignatureAuthorized	required	n/a
factaControllingPerson	required	n/a
taxDetails.taxId	required, if fatcaControllingPerson: true	required if taxResidency not DE
taxDetails.taxResidency	required, if fatcaControllingPerson: true	required
mainAddress{}	not required	required
contact.phone	n/a	required
contact.email	n/a	required

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:

legalForm	documentType
LIMITED_LIABILITY_COMPANY	CURRENT_REGISTRY_EXTRACT, SHAREHOLDER_LIST
PUBLIC_LIMITED_COMPANY	CURRENT_REGISTRY_EXTRACT, TRANSPARENCY_REGISTER_EXTRACT
FOUNDATION	CURRENT_REGISTRY_EXTRACT, STATUTE
ASSOCIATION	STATUTE
REGISTERED_BUSINESSMAN	CURRENT_REGISTRY_EXTRACT
LIMITED_PARTNERSHIP	CURRENT_REGISTRY_EXTRACT, TRANSPARENCY_REGISTER_EXTRACT
GENERAL_PARTNERSHIP	CURRENT_REGISTRY_EXTRACT, SHAREHOLDER_LIST, TRANSPARENCY_REGISTER_EXTRACT
LIMITED_LIABILITY_COMPANY_AND_LIMITED_PARTNERSHIP	CURRENT_REGISTRY_EXTRACT, SHAREHOLDER_LIST, TRANSPARENCY_REGISTER_EXTRACT
PARTNERSHIP	PARTNERSHIP_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": "[email protected]"
    }
}

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 or deactivated 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"
}