# Natural Person - Partner Ident Services This guide describes the **happy path onboarding** of a **natural person customer** in which our partner identifies the natural person through their own channels and forwards necessary information to Tradevest. The onboarding process consists of a sequence of API calls that create the natural person entity, upload identification data and documents, assign the customer role, collect required legal acceptances, and then trigger onboarding. ### 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 must be followed: 1. Create a Natural Person (`natural-persons`) 2. Create Natural Person Identification Verification (`identifications`) 3. Upload Identification certificate (`/v2/documents`) 4. Create a Customer (`customers`) 5. Sign Terms & Conditions and Data Privacy Policy (`documents`) 6. 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 set up 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` * `DOCUMENT_NOTIFICATION` * `ONBOARDING_NOTIFICATION` **Important:** If you do not configure webhooks, you will not receive detailed error reasons for failed onboardings. The `GET` endpoints will only reflect high-level status. 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/partner-apis/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 the person has no taxId `noTinConfirmation: true` must be set, and a corresponding document be uploaded. * If `mainAddress.country = CA`, the mainAddress.state field is mandatory. **Request** ```json 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** ```json 200 OK { "naturalPersonId": "2ef8762d-5128-44f3-86ef-10fc2312b7e9" } ``` #### Retrieve Natural Person In order to retrieve a natural person, send the following request. **Request** ```json GET /entities/natural-persons/{naturalPersonId} ``` **Response** The response below includes additional fields generated by the Tradevest system (besides the timestamps): * `globalId`: unique ID linked to this natural person. The Tradevest system may detect that multiple natural person records represent the same individual and merge them into a single profile, represented by the GlobalId. * `naturalPersonStatus`: Upon creation, the `naturalPersonStatus` is set to `CREATED`. ```json 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 The identification step consists of uploading raw identification data as well as the identification certificate. It will be validated together with other data provided during the onboarding process after starting the onboarding process. #### Create Identification In the request below, you send via API the core information about the identification performed between you (or the identification provider of your choice) and the customer. **Request** ```json POST /entities/natural-persons/{naturalPersonId}/identifications Requestor-ID: fb2fab01-48cc-408b-8fec-56522cd75c91 { "externalVerifier": "ID_NOW", "identificationType": "VIDEO_IDENT", "identificationDate": "2025-01-20", "identificationDocumentType": "ID", "documentNumber": "2394813190", "documentCountry": "DE", "documentIssuer": "DE", "documentIssueDate": "2022-08-24", "documentExpiryDate": "2032-08-23" } ``` **Response** The response returns a simple 202 Accepted. ```json null ``` #### Upload Identification Certificate To complete the identification requirements, upload the identification certificate received from the identification provider via the documents endpoint. Set `type: IDENTIFICATION_CERTIFICATE` and by providing `resourceType` and `resourceId`, link the document to the person created earlier. The externalId is optional. **Request** ```json POST /v2/documents Requestor-ID: fb2fab01-48cc-408b-8fec-56522cd75c91 { "document": { "name": "Identification Certificate IDNow", "type": "IDENTIFICATION_CERTIFICATE", "resourceType": "NATURAL_PERSON", "resourceId": "fb2fab01-48cc-408b-8fec-56522cd75c91", "externalId": "6c0c0882-c768-44cd-b071-2052ee5bb6be" }, "file": "binary" } ``` **Response** ```json { "documentId": "2f3ea2be-cc96-451f-87d6-7f0057ec289b" } ``` ### Customer #### Customer Create Next, a customer profile can be created. In this step, a reference bank account must be provided. The IBAN of this account is used to validate incoming payments and as the destination for outgoing payments. Creating the customer role does **not** initiate onboarding. It prepares the natural person for the onboarding process. **Request** ```json 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** ```json 200 OK { "customerId": "5b5c7296-4782-4669-83c9-125b98b9ed4a" } ``` #### Retrieve Customer **Request** ```json GET /roles/customers/5b5c7296-4782-4669-83c9-125b98b9ed4a ``` **Response** The `customerStatus` will initially be `CREATED`, indicating that onboarding can now be initiated. ```json 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 In addition to the terms agreed between you and your customers, we also require customers to sign the Tradevest Terms and Conditions as well as the Tradevest 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`. These files are uploaded by the Tradevest team and they 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 contain both the `naturalPersonId` (to identify the signatory) and the `customerId` for which the terms are signed. ```json POST /v2/documents/sign { "partnerDocumentId": "{documentId_TERMS_AND_CONDITIONS}", "naturalPersonId": "{naturalPersonId}", "customerId": "{customerId}" } ``` **Response** ```json 202 Accepted null ``` #### Sign Data Privacy Policy **Request** ```json POST /v2/documents/sign { "partnerDocumentId": "{documentId_DATA_PRIVACY_POLICY}", "naturalPersonId": "{naturalPersonId}" } ``` **Response** ```json 202 Accepted null ``` ### Onboarding Once all the above steps have been completed, 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 to the Webhook `eventType: ONBOARDING_NOTIFICATION` in order to receive updates about the onboarding status and the reasons why an onboarding has failed. This is important to understand which actions are required before triggering another onboarding attempt. #### 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** ```json POST /roles/onboardings { "roleType": "CUSTOMER", "roleId": "5b5c7296-4782-4669-83c9-125b98b9ed4a" } ``` **Response** ```json 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 possible: | **Status** | **Meaning** | | ---------- | ------------------------------------------------------------------------------------------ | | `CREATED` | Onboarding initiated. No action needed. | | `PENDING` | Background checks in progress. No action needed. | | `APPROVED` | Customer activated. The customer can now be offered products. | | `REJECTED` | Fixable validation issues. Please review all received webhook errors for detailed reasons. | | `INVALID` | Blocking data issues. Please review all received webhook errors for detailed reasons. | **Request** ```json GET /roles/onboardings/{onboardingId} ``` **Response** ```json 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.