Investors

Investors objects in the API represent accounts created for natural or legal persons that hold crypto securities. Those investor accounts can be managed using the /investors/ endpoints.

Custodian bank setup

In a collective entry the custodian bank is the investor. The end customers are onboarded by the custodian bank. Cashlink doesn't need the data of those investors and thus they don't need to onboarded via the Distributor API.

If you're using the Distributor API in the scope of a custodian bank, you can create a single investor account using the bank's data. If you need to, you can also create separate accounts using the same data.

Natural person investors

Natural person investors can be created via the investor endpoints. The information stored with an investor includes the following mandatory data:

• Personal data, residence address and PEP status of the investor (natural_person)

• Flag to confirm that the investor acts on their own behalf (is_beneficiary)

• Tax information (tax_information)

• Bank account information (bank_account_information)

• Communication (communication)

Please not that we're currently not onboarding persons that are subject to US taxation. Make sure that you set the value of the is_subject_to_us_tax field to False accordingly. Otherwise creation of investors will fail.

Example:

r = requests.post(
    f'{URL}/distributor/v2/investors/',
    json={
        'natural_person': {
            'salutation': 'MR',
            'forename': 'Peter',
            'surname': 'Parker',
            'birth_date': '2000-08-10',
            'birth_place': 'New York',
            'citizenship': 'DEU',
            'street': 'Hauptstr. 37',
            'city': 'Frankfurt',
            'zip': '60316',
            'country': 'DEU',
            'phone': '[phone]',
            'is_pep': False,
            'is_subject_to_us_tax': False
        },
        'bank_account': {
            'account_holder': 'Peter Parker',
            'iban': 'DE53500105173569146251',
            'bic': 'GENODEF1ERG',
            'bank': 'Commerzbank Frankfurt',
            'country': 'DEU',
            'currency': 'EUR'
        },
        'tax_information': {
            'tax_identification_number': '12345678',
            'non_assessment_certificate': False,
            'is_subject_to_german_tax': True
        },
        'communication': {
            'email': '[email protected]',
            'email_confirmed': True
        },
        'is_beneficiary': True,
    },
    headers={**headers, 'X-Idempotency-Key': make_key()}
)
assert r.status_code < 300, r.content
investor_id = r.json()['id']
print(investor_id)

Legal person investors

Legal person investors can be created via the investor endpoints. The following data is needed to create an account for a legal person:

• Company data such as name and commercial register data (legal_person)

• Personal data, residence address and PEP status of the CEO (natural_person)

• Flag to confirm that the investor acts on their own behalf (is_beneficiary)

• Tax information used to manage capital gains tax in Germany, if applicable (tax_information)

• Bank account information used by issuers for payouts (bank_account_information)

• Communication (communication)

Example:

# Upload documents
r = requests.post(
    f'{URL}/distributor/v2/documents/',
    files={'file': ('identity_proof.pdf', b'ASD', 'application/pdf')},
    headers={**headers, 'X-Idempotency-Key': make_key()}
)
assert r.status_code < 300, r.content
identity_proof_id = r.json()['id']

r = requests.post(
    f'{URL}/distributor/v2/documents/',
    files={'file': ('structure_proof.pdf', b'ASD', 'application/pdf')},
    headers={**headers, 'X-Idempotency-Key': make_key()}
)
assert r.status_code < 300, r.content
structure_proof_id = r.json()['id']

# Create investor
r = requests.post(
    f'{URL}/distributor/v2/investors/',
    json={
          'legal_person': {
            'city': 'string',
            'commercial_register': 'Amtsgericht München',
            'commercial_register_number': 'HRB 12344',
            'company_identity_proof_id': identity_proof_id,
            'company_name': 'Test GmbH',
            'company_structure_proof_id': structure_proof_id,
            'country': 'DEU',
            'phone': '0173 2093790',
            'street': 'string',
            'zip': 'string',
            'is_subject_to_us_tax': False
        },
        'natural_person': {
            'salutation': 'MR',
            'forename': 'Peter',
            'surname': 'Parker',
            'birth_date': '2000-08-10',
            'birth_place': 'New York',
            'citizenship': 'DEU',
            'street': 'Hauptstr. 37',
            'city': 'Frankfurt',
            'zip': '60316',
            'country': 'DEU',
            'phone': '[phone]',
            'is_pep': False,
            'is_subject_to_us_tax': False
        },
        'bank_account': {
            'account_holder': 'Peter Parker',
            'iban': 'DE53500105173569146251',
            'bic': 'GENODEF1ERG',
            'bank': 'Commerzbank Frankfurt',
            'country': 'DEU',
            'currency': 'EUR'
        },
        'tax_information': {
            'tax_identification_number': '12345678',
            'non_assessment_certificate': False,
            'is_subject_to_german_tax': True
        },
        'communication': {
            'email': '[email protected]',
            'email_confirmed': True
        },
        'is_beneficiary': True,
    },
    headers={**headers, 'X-Idempotency-Key': make_key()}
)
assert r.status_code < 300, r.content
investor_id = r.json()['id']
print(investor_id)

Legal persons can be marked as "custodian banks" if they want to hold crypto securities in cumulative entry.

Benefiting persons

If you have created an investor that is a legal person, information about its benefiting persons must be provided via the benefiting persons endpoint.

Example:

# Add benefiting persons for the investor account
r = requests.post(
    f'{URL}/distributor/v2/investors/{investor_id}/benefiting-persons/',
    json=
        [
            {
            'salutation': 'MS',
            'forename': 'Donna',
            'surname': 'Duck',
            'street': 'Teststr. 1',
            'zip': '77777',
            'city': 'Test',
            'country': 'DEU',
            'birth_date': '2005-09-18',
            'birth_place': 'Test',
            'citizenship': 'DEU',
            'is_pep': False
            }
        ],
    headers={**headers, 'X-Idempotency-Key': make_key()}
)
assert r.status_code < 300, r.content
person_id = r.json()[0]['person_id']
print(f'Person: {person_id}')

Please make sure that you're only onboarding investors where the benefiting persons are not "politically exposed persons" (PEP). During the KYC/AML process a background check is performed and PEPs may be rejected.

If the benefiting persons change, simply add the new persons via a new POST request. You do not need to delete existing benefiting persons if they're not a benefiting person any more.

Identifications

Investors need valid identification data from an identification process. For legal persons, the CEO (added via the natural_person field) needs to perform the identification.

Create new identifications

The process for creating a new identification is the following:

1. Via the identification endpoint, create a new identification with an empty JSON request. The API will return a URL of the identity provider and the ID of the identification process.

2. Redirect the investor to the provided URL. The investor can use the URL to complete the identification process.

3. You can use the identification endpoints and the identification ID to query the current status of the identification.

4. After the identification is completed, the final data can be retrieved via the identification endpoint.

Example:

# Create identification for investor
r = requests.post(
    f'{URL}/distributor/v2/investors/{investor_id}/identifications/',
    headers={**headers, 'X-Idempotency-Key': make_key()}
)
assert r.status_code < 300, r.content
identification_id = r.json()['id']
print(f'Identification: {identification_id}')

Import existing identifications

If you have already existing and valid identifications of the investor you can also provide all data via the API directly.

For the identity provider you can use "IDNOW", "LIONWARE" and "POSTIDENT". Other identity providers are currently not supported.

The legitimation protocol that resulted from the identification process needs to be uploaded as a PDF document.

You also have to add the document type that was used. You can use the values "IDCARD" or "PASSPORT".

Example:

# Upload the legitimation protocol document
r = requests.post(
    f'{URL}/distributor/v2/documents/',
    files={'file': ('protocol.pdf', b'ASD', 'application/pdf')},
    headers={**headers, 'X-Idempotency-Key': make_key()}
)
assert r.status_code < 300, r.content
protocol_doc_id = r.json()['id']

# Create identification for investor
r = requests.post(
    f'{URL}/distributor/v2/investors/{investor_id}/identifications/',
    json={
        'document_type': 'IDCARD',
        'document_id': 'ID123456',
        'document_issuer': 'Buergeramt Frankfurt',
        'document_valid_from': '2020-08-10',
        'document_valid_to': '2030-08-10',
        'identity_provider': 'POSTIDENT',
        'legitimation_process_id': 'string',
        'legitimation_protocol_id': protocol_doc_id,
        'verified_at': '2025-08-10T14:06:22.134Z'
    },
    headers={**headers, 'X-Idempotency-Key': make_key()}
)
assert r.status_code < 300, r.content
identification_id = r.json()['id']
print(f'Identification: {identification_id}')

Imported identifications must not be older than 2 years (based on the verified_at field). Also, the identification document must still be valid (based on the valid_to field).