As a regulated investment firm, we are required that the investors' identities are verified in a compliant manner. We rely on you to perform the identity verification during your user onboarding flow, typically via an online KYC provider.
Additionally, your customers must explicitly agree to our service agreements covering data processing and investment registry.
We recommend that you send us only approved customers, meaning that you ideally send them to us only after they have received final approval for investing.
Once these steps are complete in your system, submit the verified customer's KYC data using the following request:
Post Customer KYC /api/external/v1/customers/{customerId}/kyc
Request Example:
# UAT BASE_URL: https://uat.api.nyala.de
# Production BASE_URL: https://api.nyala.de
# The {customerId} is 42557ea2-8a55-4599-85b2-2a91f343a08b
curl -X POST {{BASE_URL}}/api/external/v1/customers/42557ea2-8a55-4599-85b2-2a91f343a08b/kyc \
-H "Content-Type: application/json" \
-H "Authorization: HMAC YOUR_API_KEY:GENERATED_SIGNATURE" \
-H "Content-Length: CALCULATED_CONTENT_LENGTH" \
-d '{
"salutation": "Mr",
"firstname": "{{customer_random_firstname}}",
"lastname": "{{customer_random_lastname}}",
"dateOfBirth": "1985-03-20T00:00:00Z",
"placeOfBirth": "Germany",
"phoneNumber": "+493012345678",
"type": "Person",
"countryIso": "DE",
"nationalityIso": "DE",
"gender": "Male",
"email": "{{customer_random_email}}",
"nonPepPerson": true,
"highCorruptionIndex": false,
"nonSanctionedCountry": true,
"nonUsTaxPerson": true,
"identVerified": true,
"identVerifiedType": "Normal",
"eulaAgreed": true,
"address": {
"street": "Uhlandstrasse",
"streetNo": "32",
"postalCode": "10719",
"town": "Berlin",
"countryCodeIso2": "DE"
},
"custodyProvider": "Tangany",
"tanganyIdentVerifiedType": "Qes_bankident",
"document": {
"country": "GB",
"nationality": "GB",
"number": "GB123456789",
"issuedBy": "Home Office Identify & Passport Service",
"issueDate": "2010-04-11",
"validUntil": "2025-04-11",
"type": "id_card",
"iban": "DE41500105177679228624",
"reference": "Ref1"
}
}'The following parameters apply to KYC data for both natural person and legal entity investors. For legal entities, all KYC data pertains to the company representative performing the KYC verification.
| Parameter | Description | Expected Values |
|---|---|---|
| placeOfBirth | Place of birth denoted in the used identification document of the investor. | "Berlin" |
| nonPepPerson | Relates to the political exposure of the person. Indicates whether the person is NOT a Politically Exposed Person (PEP). | true |
| highCorruptionIndex | Relates to the country of residence. You can always send "false" if your KYC provider performs these checks automatically. | false |
| nonSanctionedCountry | Indicates the investor is NOT residing in a sanctioned country. You can always send "true" if your KYC provider performs these checks automatically. | true |
| nonUsTaxPerson | We do not accept persons subjected to US tax. Always set to "true" (if the person is not subject to taxes in the USA). | true |
| identVerified | Only send KYC data of customers that have been verified already. Hence, always set this field to "true". | true |
| identVerifiedType | Only relevant when custodian is set to HADC. Describes which level of KYC checks the investor has passed. "Plain" means that investment amount is below EUR 1000. | "NotSet", "Normal", "Plain" |
| tanganyIdentVerifiedType | Only relevant when custodian is set to Tangany. Type of KYC process depends on your active markets and your own provider. See detailed verification type description in the table Tangany Identity Verification Type Description. | "Video_ident", "Id_copy", "Auto_ident", "In_person", "Eid", "Post_ident", "Qes_bankident" |
| eulaAgreed | Refers to the Smart Registry terms of use. Ensure that your end users always have to agree to the terms as part of their onboarding process, then always set to "true". | true |
The table below describes document parameters used for KYC verification. A document is required for all verification methods except in_person when Tangany is the chosen custodian.
| Parameter | Description | Expected Values |
|---|---|---|
| document.nationality | Stated nationality. Must be a ISO 3166-1 Alpha-2 country code. Additionally "XX" is allowed for unknown states. | "DE" |
| document.country | Document issuing country. Must be a ISO 3166-1 Alpha-2 country code. Additionally "XX" is allowed for unknown states. | "DE" |
| document.number | ID number of the document. | "C01X00T47" |
| document.issuedBy | Name of the document issuer. | "Stadt Berlin" |
| document.issueDate | Date of issuance in the format YYYY-MM-DD. Must be >= 1900-01-01. If not provided, can be set to n/a. | "2020-01-15" |
| document.validUntil | Stated expiration date of the document in the YYYY-MM-DD format. Must be >= 1900-01-01. | "2030-01-15" |
| document.type | Type of the document. | "Id_card", "Passport", "Other" |
| document.iban | International Bank Account Number comprised of maximum 34 characters, letters and numbers. | "DE89370400440532013000" |
| document.reference | Reference or purpose of a transfer containing any characters. Nullable for all methods except QES_bankident (tanganyIdentVerifiedType). | "Reference text" |
The table below describes address parameters (nested under address) for the legal entity's representative.
| Parameter | Description | Expected Values |
|---|---|---|
| address.street | Street name of the representative's address. | "Uhlandstraße" |
| address.streetNo | Street number of the representative's address. | "32" |
| address.postalCode | Postal code of the representative's address. | "10719" |
| address.town | Town of the representative's address. | "Berlin" |
| address.countryCodeIso2 | ISO country code (e.g. "DE"). | "DE" |
Note: The following parameter groups are documented in the Create Customer chapter:
company tanganyLegalPerson (including legalAddress, postalAddress, kyc, and related nested objects)
For more information, see the Create Customer documentation.
Please send the method that applies to your process:
| Verification Type | Process Description |
|---|---|
| Video Ident | The Investor provides personal information, then participates in a live video call with a trained agent. A valid ID document and mobile phone number are required. The Investor confirms identity via SMS TAN to complete the process. |
| Id_copy / Remote Identification | The Investor photographs their ID document and face, then uploads images to the platform. Verification is completed without third-party KYC provider involvement. |
| Auto_ident | The Investor provides personal information and photographs of the front and back of their ID document. An automated video captures the investor's face, which is then compared to the ID document through AI-based verification. The process is fully automated without real-time agent interaction, though automated quality checks may be applied. |
| eID | The Investor installs a KYC provider app on their NFC-enabled smartphone. The app reads electronic data from a German identity card or residence permit using NFC technology. A 6-digit PIN is required for the Online ID feature to complete the process. |
| Post_ident | The Investor visits a Deutsche Post branch location for in-person identity verification. A postal employee scans the ID document, verifies it against the person present, and confirms the identity data. The investor signs electronically to complete the process. Verification data is transmitted digitally to the requesting company. |
| Qes_bankident | This is also called the qualified signature process. The KYC provider identifies the investor via VideoID or AccountID (using online banking credentials). Investor confirms via TAN, reviews the contract, and signs it with a final TAN signature to complete identification. |
| In_person | The Investor visits the client's branch or office location for face-to-face identity verification. A trained employee of the obliged entity (bank, financial institution, or platform) examines the original ID document, compares the photo with the person present, and verifies identity data. The employee documents the verification process according to regulatory requirements. |
Response Example:
{
"errorMessageCodes": null,
"errors": null,
"data": true
}