Natural Person - Tradevest Ident Services

Natural Person Onboarding - Tradevest Ident Services

This guide describes the happy-path onboarding of a natural person customer using the Tradevest API and the integrated Tradevest Ident Services. The onboarding process consists of a sequence of API calls that create the natural person entity, initiate identification, assign the customer role, collect required legal acceptances, and finally trigger onboarding. The Tradevest API is asynchronous by design. Resource states can be retrieved via the corresponding GET endpoints or monitored via webhooks.

Overview of Required Steps

In order to onboard a natural person as a customer using the Tradevest API with the integrated WebID identification service the following main steps have to be followed:

1. Create a Natural Person (natural-persons)

2. Create Natural Person Identification Verification (identification-verifications)

3. Create a Customer (customers)

4. Sign Terms & Conditions and Data Privacy Policy (documents)

5. Start Onboarding (onboardings)

The steps (Happy Path) are described in more detail below with respective request-response pairs. Each example includes the minimum data to be provided for a successful onboarding process.

It is important to note that our API is setup to be asynchronous, meaning each immediate response includes a uuid or simply a successful HTTP response code. With the uuids returned, respective GET API requests can be sent to retrieve the current status of the resource.

0. Webhook Setup

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:

• NATURAL_PERSON_NOTIFICATION

• CUSTOMER_NOTIFICATION

• IDENTIFICATION_VERIFICATION_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. Please note that detailed 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. Natural Person

Create Natural Person

After requesting the required information from the person to be onboarded, send a request to create a Natural Person record.

The following business rules are to be considered for the implementation:

• If taxDetails.taxResidency = DE, the taxId is not required. Tradevest retrieves the tax ID from the local authority.

• For all other taxResidency values, taxId must be provided.

• If mainAddress.country = CA, the mainAddress.state field is mandatory.

Request

POST /entities/natural-persons

{
    "gender": "MALE",
    "title": "PROFESSOR",
    "firstName": "John",
    "lastName": "Doe",
    "birthDay": "2005-11-19",
    "birthPlace": "Berlin",
    "birthCountry": "DE",
    "nationalities": [
        {
            "countryCode": "DE"
        }
    ],
    "taxDetails": [
        {
            "taxResidency": "DE"
        }
    ],
    "isUsNationality": false,
    "profession": "text",
    "professionGroup": "EMPLOYED",
    "mainAddress": {
        "street": "Doe Street",
        "streetNumber": "24",
        "city": "Berlin",
        "zip": "12345",
        "country": "DE"
    },
    "contact": {
        "phone": "123456789",
        "email": "[email protected]"
    },
    "externalId": "0e03cbb8-91ea-484f-ae3c-bc665e05b5b6"
}

Response

200 OK

{
    "naturalPersonId": "2ef8762d-5128-44f3-86ef-10fc2312b7e9"
}

Retrieve Natural Person

In order to retrieve a Natural Person send the following request.

Request

GET /entities/natural-persons/{naturalPersonId}

Response

The response below includes some variables that have been generated by the Tradevest System besides the timestamps:

• globalId: the globalId is the unique Id which is linked to that Natural Person. The Tradevest system validates Natural Persons for matching data and might join them into the same Natural Person profile.

• naturalPersonStatus: Upon creation, the naturalPersonStatus is set to CREATED.

200 OK 

{
    "naturalPersonId": "fb2fab01-48cc-408b-8fec-56522cd75c91",
    "globalId": "509782378852",
    "createdOn": "2025-11-19T13:47:53.418576Z",
    "modifiedOn": "2025-11-19T13:47:53.418576Z",
    "naturalPersonStatus": "CREATED",
    "gender": "MALE",
    "title": "PROFESSOR",
    "firstName": "John",
    "lastName": "Doe",
    "birthDay": "2005-11-19",
    "birthPlace": "Berlin",
    "birthCountry": "DE",
    "nationalities": [
        {
            "countryCode": "DE"
        }
    ],
    "taxDetails": [
        {
            "taxResidency": "DE",
            "noTinConfirmation": false
        }
    ],
    "isUsNationality": false,
    "profession": "text",
    "professionGroup": "EMPLOYED",
    "mainAddress": {
        "street": "Doe Street",
        "streetNumber": "24",
        "city": "Berlin",
        "zip": "12345",
        "country": "DE"
    },
    "contact": {
        "phone": "123456789",
        "email": "[email protected]"
    },
    "externalId": "0e03cbb8-91ea-484f-ae3c-bc665e05b5b6"
}

Natural Person Identification

Create Identification Verification

Creating an identification verification via the Tradevest API initiates a video identification process with the selected provider (externalVerifier).

The Tradevest API currently supports

• externalVerifier: WEB_ID and

• identificationType: VIDEO_IDENT

You should provide a redirectUrl to which the Natural Person will be redirected after the identification process (independent of whether or not it was successful or failed/aborted). This can be a unique url in your application/platform.

Please note that for the identification to be successfully created the Natural Person must be at least 18 years old.

Request

POST /entities/identification-verifications

Requestor-ID: 123e4567-e89b-12d3-a456-426614174000

{
  "naturalPersonId": "fb2fab01-48cc-408b-8fec-56522cd75c91",
  "externalVerifier": "WEB_ID",
  "identificationType": "VIDEO_IDENT",
  "redirectUrl": "https://www.tradevest.ai"
}

Response

200 OK 

{
    "identificationVerificationId": "b4414702-1a12-4554-b2b9-3e53a7e95f9d"
}

Retrieve Identification Verification

In order to retrieve the details - most importantly the identificationUrl of the identification verification send a request with the idenficiationVerificationId.

Request

GET /entities/identification-verifications/{identificationVerificationId}

Response

The response includes the the identificationUrl. You shall redirect the customer to the given Url in order for the person to be identified to complete the verification.

Note: On sandbox there is the possibility to click through this identification in the WebID flow manually.

200 OK 

{
    "naturalPersonId": "9b29cd58-3105-4e18-ab4d-f4970ea29d4a",
    "identificationVerificationId": "4d18fa87-b233-4990-88cc-5a288828b8e8",
    "externalVerifier": "WEB_ID",
    "identificationType": "VIDEO_IDENT",
    "identificationUrl": "https://test.webid-solutions.de/service/index/cn/000792/aid/145588703",
    "createdOn": "2025-11-19T14:06:35.008247Z",
    "modifiedOn": "2025-11-19T14:06:35.008247Z",
    "status": "PENDING"
}

Wait for Webhook Notification

By subscribing to the webhook eventType: IDENTIFICATION_VERIFICATION_NOTIFICATION you will be notified about status changes.

Once the identification-verification status is changed a webhook notification will be sent to the URL configured in the webhook subscription.

POST http://client-api-address/identification-verification-notification

{
    "identificationVerificationId": "4d18fa87-b233-4990-88cc-5a288828b8e8",
    "naturalPersonId": "9b29cd58-3105-4e18-ab4d-f4970ea29d4a",
    "modifiedOn": "2025-11-19T14:06:35.008247Z",
    "status": "APPROVED",
    "notificationType": "UPDATED"
}

Requesting Identification Verification

Another request with the identification-verifications endpoint returns the complete identificationVerification record with status: APPROVED.

Response

200 OK 

{
    "naturalPersonId": "9b29cd58-3105-4e18-ab4d-f4970ea29d4a",
    "identificationVerificationId": "4d18fa87-b233-4990-88cc-5a288828b8e8",
    "externalVerifier": "WEB_ID",
    "identificationType": "VIDEO_IDENT",
    "identificationUrl": "https://test.webid-solutions.de/service/index/cn/000792/aid/145588703",
    "documentId": "5395550f-9856-4d9f-8607-6cc2434fc4fe",
    "naturalPersonIdentificationId": "1ac56561-6aa4-4ad9-84cb-d25f238ce6bf",
    "createdOn": "2025-11-19T14:06:35.008247Z",
    "modifiedOn": "2025-11-19T14:06:35.008247Z",
    "status": "APPROVED"
}

Customer

Customer Create

Once the naturalPerson has been successfully verified by our KYC provider a customer profile can be created.

In this step, a reference bank account must be provided. The IBAN of this bank account will be used to validate incoming payments and be the bank account to which outgoing payments can be triggered.

Creating the customer role does not initiate onboarding. It prepares the natural person for the onboarding process.

Request

POST /roles/customers

{
    "entityId": "9b29cd58-3105-4e18-ab4d-f4970ea29d4a",
    "entityType": "NATURAL_PERSON",
    "refAccounts": [
        {
            "bankName": "Test Bank",
            "iban": "DE75512108001245126199",
            "bic": "SOGEDEFFXXX",
            "type": "PRIMARY",
            "ownerName": "Test TesterqRwXkkwAs"
        }
    ],
    "labels": []
}

Response

200 OK 

{
    "customerId": "5b5c7296-4782-4669-83c9-125b98b9ed4a"
}

Retrieve Customer

Request

GET /roles/customers/5b5c7296-4782-4669-83c9-125b98b9ed4a

Response

The customerStatus will initially be CREATED, indicating that onboarding can now be initiated.

200 OK 

{
    "customerId": "5b5c7296-4782-4669-83c9-125b98b9ed4a",
    "customerStatus": "CREATED",
    "createdOn": "2025-11-19T14:20:35.623181Z",
    "modifiedOn": "2025-11-19T14:20:35.623181Z",
    "entityId": "9b29cd58-3105-4e18-ab4d-f4970ea29d4a",
    "entityType": "NATURAL_PERSON",
    "refAccounts": [
        {
            "bankName": "Test Bank",
            "iban": "DE75512108001245126199",
            "bic": "SOGEDEFFXXX",
            "type": "PRIMARY",
            "ownerName": "Test TesterqRwXkkwAs"
        }
    ],
    "labels": []
}

Terms & Conditions

Besides terms that you and the customers agree on, we also require the customers to sign Tradevest Terms and Conditions as well as Data Privacy Policy.

Note: The Terms & Conditions signature must be linked to a specific customer. The Data Privacy Policy signature is recorded at the Natural Person level and therefore does not require a customerId.

The files are uploaded by the Tradevest team and can be retrieved using the GET /partner-documents endpoint.

These files need to be downloaded and shown to the customer and upon accepting them, this information is forwarded through our API.

Sign Terms and Conditions

Request

The request must not only contain the naturalPersonId to identify the signatory but also the customerId for which customer the terms are signed.

POST /v2/documents/sign

{
  "partnerDocumentId": "{{documentId_TERMS_AND_CONDITIONS}}",
  "naturalPersonId": "{{naturalPersonId}}",
  "customerId": "{{customerId}}"
}

Response

202 Accepted 

null

Sign Data Privacy Policy

Request

POST /v2/documents/sign

{
  "partnerDocumentId": "{{documentId_DATA_PRIVACY_POLICY}}",
  "naturalPersonId": "{{naturalPersonId}}"
}

Response

202 Accepted 

null

Onboarding

Once all the above steps have been conducted the official onboarding with our platform can be initiated.

The onboarding process is asynchronous and typically completes within a few seconds. During this phase, background checks are performed and the integrity of the provided data and document signatures is validated.

We highly recommend subscribing the Webhook eventType: ONBOARDING_NOTIFICATION in order to receive updates about the onboarding status and also reasons for why an onboarding has failed. The latter is important in order to understand the actions to be taken before another onboarding attempt is triggered.

Start Onboarding

In this scenario the roleType of the customer to be onboarded is set to CUSTOMER. Natural Persons could theoretically also be onboarded in other roles (e.g. proxies for legal entities or minority accounts).

Request

POST /roles/onboardings

{
    "roleType": "CUSTOMER",
    "roleId": "5b5c7296-4782-4669-83c9-125b98b9ed4a"
}

Response

200 OK

{
    "onboardingId": "9473f691-de72-486a-ae6b-8e46c3771c19"
}

Monitor Onboarding

Besides listening to webhook notifications the GET /roles/onboardings/{{onboardingId}} endpoint will return the current STATUS of the onboarding.

The following statuses are valid possible:

Status	Meaning
CREATED	Onboarding initiated. No action needed.
PENDING	Background checks in progress. No action needed.
APPROVED	Customer activated. Customer can be offered to create products.
REJECTED	Fixable validation issues. Please review all webhook errors received for error reasons.
INVALID	Blocking data issues. Please review all webhook errors received for error reasons.

Request

GET /roles/onboardings/{onboardingId}

Response

200 OK 

{
    "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"
}

After successful onboarding (status: APPROVED), the customer is fully activated and may request the creation of balance or depository accounts and wallets.