# 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**](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. 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": "tvdtester90+209461494@gmail.com" }, "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": "tvdtester90+209461494@gmail.com" }, "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:
StatusMeaning
StatusMeaning
CREATEDOnboarding initiated. No action needed.
PENDINGBackground checks in progress. No action needed.
APPROVEDCustomer activated. Customer can be offered to create products.
REJECTEDFixable validation issues. Please review all webhook errors received for error reasons.
INVALIDBlocking 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.