We support both natural and legal persons (business).
To create a user, follow the steps described below:
First, collect the basic information on the customer via your website or platform. The following basic data must be collected at a minimum and forwarded to us:
- First name
- Last name
- Type (natural vs legal entity)
- Street
- Street number
- Postal code
- City
- Country (ISO)
- Email address
Before the beginning of the onboarding phase, we will ask your organization to choose which crypto custodian you will use for your customers' blockchain wallets. These wallets will be the ones holding the tokenized securities. This will determine which datapoints you will send us in key API calls (Create Customer, Save KYC Data, etc.) The custodian options are three-fold:
- Tangany, a specialized and regulated crypto custodian.
- Hauck Aufhäuser Lampe, a German private bank belonging to the ABN AMRO group.
- None of the above: you can choose to bring us non-custodial wallets (e.g. Web3Auth), or wallets provided by a custodian you already have an integration with.
ℹ️ Important information about our custodian partner Tangany: If you select Tangany as the custodian, please note that they only accept residents of the European Union, Iceland, Norway, Switzerland, the United Kingdom and Japan
HADC, a German bank part of the ABN AMRO Group, accepts all residents except countries under international sanctions lists.
Send the user's personal information with the following request:
POST customer /api/external/v1/customers
You must specify whether the investor is a natural or a legal person in the type field. For legal persons, you must provide the relevant corporate details. The required legal person data points may vary depending on your configured custody provider.
Request Example:
# UAT BASE_URL: https://uat.api.nyala.de
# Production BASE_URL: https://api.nyala.de
curl -X POST {{BASE_URL}}/api/external/v1/customers \
-H "Content-Type: application/json" \
-H "Authorization: HMAC YOUR_API_KEY:GENERATED_SIGNATURE" \
-H "Content-Length: CALCULATED_CONTENT_LENGTH" \
-d '{
"firstname": "John",
"lastname": "Doe",
"email": "john.doe@example.com",
"type": "Person",
"salutation": "Mr",
"phoneNumber": "+493012345678",
"birthDate": "1985-03-20T00:00:00Z",
"street": "Uhlandstrasse",
"streetNo": "32",
"postalCode": "10719",
"town": "Berlin",
"countryIso": "DE",
"nationalityIso": "DE",
"custodyProvider": 1
}'The table below describes some of the parameters for a natural person investor.
| Parameter | Description | Expected Values |
|---|---|---|
| firstName | First name of the investor. When sending values with accents (e.g. É, ç, ñ), send the values in UTF-8 charset. | "John" |
| type | Whether the investor is a natural person or a legal entity. Always send "Person" for natural persons. | "Person" |
| street | The street name where the investor resides. When sending values with accents (e.g. É, ç, ñ), send the values in UTF-8 charset. | "Uhlandstrasse" |
| town | The town in which the investor resides. When sending values with accents (e.g. É, ç, ñ), send the values in UTF-8 charset. | "Berlin" |
| countryIso | The country ISO code in which the investor resides. Use ISO 3166-1 alpha-2 country codes. | "DE" |
| nationalityIso | The nationality of the investor. Use ISO 3166-1 alpha-2 country codes. | "DE" |
| The email which the investor used to register. This must be unique and cannot be reused by other investors. | "john.doe@example.com" | |
| custodyProvider | Set at which custodian the customer's private keys will be held. Choosing Tangany requires sending more data fields in the KYC endpoint. You can either send a number or the name of the custodian as a string. Set '1' for Tangany, '3' for HADC, leave blank or send '0' for external wallets only. | "1" |
The table below describes some of the parameters regarding the basic information for a legal entity representative.
| Parameter | Description | Expected Values |
|---|---|---|
| firstName | First name of the company representative. Legal requirement: collect at least the beneficial owner's first name and surname. | "John" |
| lastName | Last name of representative. | "Doe" |
| birthDate | Birth date of representative. | "1985-03-20" |
| phoneNumber | Phone number of representative. | "+49 30 12345678" |
| type | Always send "LegalEntity" for legal persons. | "LegalEntity" |
| street | Refers to the address of the representative. | "Uhlandstrasse" |
| postalCode | Refers to the address of the representative. | "10719" |
| town | Refers to the address of the representative. | "Berlin" |
| countryIso | Refers to the address of the representative. Expects ISO country code. | "DE" |
| nationalityIso | Refers to the nationality of the representative. | "DE" |
| gender | The gender of the representative. | "Male", "Female", "Other", "NotSet" |
The table below contains basic company information parameters. These are required for all legal entity investors, regardless of custodian choice.
| Parameter | Description | Expected Values |
|---|---|---|
| company.name | Name of the company. | "ACME Corporation GmbH" |
| company.registerNumber | Register number of the company. | "HRB 12345" |
| company.fullAddress | Full address of the company as a string. | "Hauptstrasse 10, 10115 Berlin, Germany" |
| company.email | The email of the company's representative performing the onboarding. You may re-use the same input as for the representative email. | "john.doe@company.com" |
The parameters in the following tables are relevant only if Tangany is selected as the custodian.
The table below describes some parameters regarding Tangany legal entity (nested under tanganyLegalPerson).
| Parameter | Description | Expected Values |
|---|---|---|
| tanganyLegalPerson.id | A UUID for the company. | UUID value |
| tanganyLegalPerson.name | The name of the company. You can re-use the value from company.name. | "ACME Corporation GmbH" |
| tanganyLegalPerson.legalForm | Legal form of company. E.g. "AG", "GmbH". | "GmbH", "AG" |
| tanganyLegalPerson.commercialRegister | You may leave it blank. Legally speaking, only the register number is required. | "Amtsgericht Berlin" |
| tanganyLegalPerson.leiCode | LEI code of the company. | "549300ABCDEFGHIJK123" |
| tanganyLegalPerson.taxId | Tax ID of the company. | "12/345/67890" |
| tanganyLegalPerson.vatId | Vat ID of the company. | "DE123456789" |
| tanganyLegalPerson.isincode | ISIN code of the company. | "DE0005140008" |
| tanganyLegalPerson.legalJurisdiction | ISO country code (e.g. "DE") where the legal entity is registered. Not mandatory, as this data is captured within the legalAddress object. | "DE" |
The table below describes some parameters regarding Tangany legal entity (nested under 'tanganyLegalPerson.legalAddress).
| Parameter | Description | Expected Values |
|---|---|---|
| legalAddress.country | ISO country code (e.g. "DE") where the company is registered. | "DE" |
| legalAddress.city | City where company is registered. | "Berlin" |
| legalAddress.postcode | Post code where company is registered. | "10115" |
| legalAddress.streetName | Street name where company is registered. | "Hauptstrasse" |
| legalAddress.streetNumber | Street number where company is registered. | "10" |
The table below describes some parameters regarding Tangany legal entity (nested under 'tanganyLegalPerson.postalAddress).
| Parameter | Description | Expected Values |
|---|---|---|
| postalAddress.country | You may re-use the same data as for the legal address. | "DE" |
| postalAddress.city | You may re-use the same data as for the legal address. | "Berlin" |
| postalAddress.postcode | You may re-use the same data as for the legal address. | "10115" |
| postalAddress.streetName | You may re-use the same data as for the legal address. | "Hauptstrasse" |
| postalAddress.streetNumber | You may re-use the same data as for the legal address. | "10" |
The table below describes some parameters regarding Tangany legal entity (nested under 'tanganyLegalPerson.kyc).
| Parameter | Description | Expected Values |
|---|---|---|
| kyc.businessDescription | You can always send the following value: "Investor". | "Investor" |
| kyc.isCreAvailable | You can always set this field to "false". | false |
The table below describes some parameters regarding Tangany legal entity (nested under 'tanganyLegalPerson.related).
| Parameter | Description | Expected Values |
|---|---|---|
| related.entityId | The legal requirement is to create one per beneficial owner of the company (even if they do not have to go through the KYC process). | UUID of beneficial owner |
| related.position | Position of the beneficial owner in the company. | "CEO", "Director" |
| related.isFictitiousBeneficialOwner | Indicates if this is a fictitious beneficial owner. | false |
| related.isUltimateBeneficialOwner | Indicates if this is the ultimate beneficial owner. | true |
| related.sharePercentage | Share percentage of ownership. | "25.5", "100" |
Response Example: In response to the successful user creation, you will receive a user ID, which you will need to proceed with the saving of the KYC data, the wallet creation request, and more.
{
"errorMessageCodes": null,
"errors": null,
"data": "42557ea2-8a55-4599-85b2-2a91f343a08b"
}You can query the customer data via endpoints:
GET customer /api/external/v1/customers/{customerId}
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 GET {{BASE_URL}}/api/external/v1/customers/42557ea2-8a55-4599-85b2-2a91f343a08b \
-H "Authorization: HMAC YOUR_API_KEY:GENERATED_SIGNATURE" \
-H "Content-Length: 0"Response Example:
{
"errorMessageCodes": null,
"errors": null,
"data":
{
"id": "42557ea2-8a55-4599-85b2-2a91f343a08b",
"firstname": "John",
"lastname": "Doe",
"institutionId": "290e614f-4e79-4ba8-8ba3-60a0f7608256",
"institutionName": "My Institution",
"salutation": "Mr",
"type": "Person",
"birthDate": "1985-03-20T00:00:00Z",
"title": "",
"email": "john.doe@example.com",
"phoneNumber": "+493012345678",
"walletAccess": "Full",
"address": {
"id": "5e062896-9054-470e-b640-5b75380dc49c",
"street": "Uhlandstrasse",
"streetNo": "32",
"postalCode": "10719",
"town": "Berlin",
"country": {
"id": "38913c1d-dd38-494a-80d1-13922dd61d0e",
"iso": "DE",
"isoCode3": "DEU",
"name": "Deutschland"
}
},
"nationalityId": "38913c1d-dd38-494a-80d1-13922dd61d0e",
"nationalityIso": "DE",
"gender": "Male",
"kycData": {
"title": "",
"salutation": "Mr",
"firstname": "John",
"lastname": "Doe",
"placeOfBirth": "Germany",
"dateOfBirth": "1985-03-20T00:00:00Z",
"email": "john.doe@example.com",
"phoneNumber": "+493012345678",
"nonPepPerson": true,
"highCorruptionIndex": false,
"nonSanctionedCountry": true,
"nonUsTaxPerson": true,
"identVerified": true,
"identVerifiedType": "Normal",
"tanganyIdentVerifiedType": "Qes_bankident",
"eulaAgreed": true,
"address": {
"street": "Uhlandstrasse",
"streetNo": "32",
"postalCode": "10719",
"town": "Berlin",
"countryCodeIso2": "DE"
},
"company": null,
"nationalityIso": "DE",
"gender": "Male",
"bic": "",
"tanganyLegalPerson": null
},
"company": null,
"approvedForMonerium": false,
"moneriumIban": null,
"tanganyCustomerId": "12ac5cc7-71b6-46ee-84a7-be70a5afe915",
"tanganyAuthorizedId": "42557ea2-8a55-4599-85b2-2a91f343a08b",
"tanganyOwnerId": "42557ea2-8a55-4599-85b2-2a91f343a08b",
"hadcCustomerId": null
}
}GET customer /api/external/v1/search
Request Example:
# UAT BASE_URL: https://uat.api.nyala.de
# Production BASE_URL: https://api.nyala.de
# Example with:
# searchText = "John"
# take = 50
# skip = 0
curl -X GET "{{BASE_URL}}/api/external/v1/customers?searchText=John&take=50&skip=0" \
-H "Authorization: HMAC YOUR_API_KEY:GENERATED_SIGNATURE" \
-H "Content-Length: 0"Response Example:
{
"errorMessageCodes": null,
"errors": null,
"data": [
{
"id": "42557ea2-8a55-4599-85b2-2a91f343a08b",
"firstname": "John",
"lastname": "Doe",
"institutionId": "290e614f-4e79-4ba8-8ba3-60a0f7608256",
"institutionName": "My Institution",
"salutation": "Mr",
"type": "Person",
"birthDate": "1985-03-20T00:00:00Z",
"title": "",
"email": "john.doe@example.com",
"phoneNumber": "+493012345678",
"walletAccess": "Full",
"address": {
"id": "5e062896-9054-470e-b640-5b75380dc49c",
"street": "Uhlandstrasse",
"streetNo": "32",
"postalCode": "10719",
"town": "Berlin",
"country": {
"id": "38913c1d-dd38-494a-80d1-13922dd61d0e",
"iso": "DE",
"isoCode3": "DEU",
"name": "Deutschland"
}
},
"nationalityId": "38913c1d-dd38-494a-80d1-13922dd61d0e",
"nationalityIso": "DE",
"gender": "Male",
"kycData": {
"title": "",
"salutation": "Mr",
"firstname": "John",
"lastname": "Doe",
"placeOfBirth": "Germany",
"dateOfBirth": "1985-03-20T00:00:00Z",
"email": "john.doe@example.com",
"phoneNumber": "+493012345678",
"nonPepPerson": true,
"highCorruptionIndex": false,
"nonSanctionedCountry": true,
"nonUsTaxPerson": true,
"identVerified": true,
"identVerifiedType": "Normal",
"tanganyIdentVerifiedType": "Qes_bankident",
"eulaAgreed": true,
"address": {
"street": "Uhlandstrasse",
"streetNo": "32",
"postalCode": "10719",
"town": "Berlin",
"countryCodeIso2": "DE"
},
"company": null,
"nationalityIso": "DE",
"gender": "Male",
"bic": "",
"tanganyLegalPerson": null
},
"company": null,
"approvedForMonerium": false,
"moneriumIban": null,
"tanganyCustomerId": "12ac5cc7-71b6-46ee-84a7-be70a5afe915",
"tanganyAuthorizedId": "42557ea2-8a55-4599-85b2-2a91f343a08b",
"tanganyOwnerId": "42557ea2-8a55-4599-85b2-2a91f343a08b",
"hadcCustomerId": null
}
]
}