Go back to the summary

User onboarding

This guide walks you through all aspects of onboarding a user in the Investment API, including user creation, regulatory checks and regulatory identifiers.

How user onboarding works

Onboarding is the starting point of the user's interaction with your product. We designed this process to be as simple as possible to cover all legal, regulatory and compliance aspects in a reasonable way.

Prerequisites

You can start onboarding users as soon as you have completed the steps listed in the Getting started guide.

Onboarding a user

Step 1: Creating a user

To onboard a user, follow these steps:

1. First, collect the user data, such as name, birthdate, email address, address and other data (see full list of required and optional data in the API reference), which have to satisfy the following conditions:

• It must not be a P.O. box (Post Office box) or c/o (in care of) address.

• It must be verified that the address actually exists and that it matches the address indicated either in the identification documents or in a separate proof of residency at a later stage of the onboarding process.

• A user must have at least one nationality. If a user has multiple nationalities, all nationalities need to be submitted.

• Terms and conditions and data privacy acknowledgements are transferred digitally via the Investment API. We rely on you to submit the timestamp of the user's acknowledgement event during your onboarding process and a version ID of the documents, which is linked to the PDF documents.

1. Send the user's personal information with POST /users.

Example request

{
  "first_name": "Karl",
  "last_name": "Schmidt",
  "email": "karl.schmidt@example.com",
  "salutation": "SALUTATION_MALE",
  "title": "DR",
  "birth_date": "1972-09-30",
  "birth_city": "Berlin",
  "birth_country": "DE",
  "birth_name": "Schmidt",
  "nationalities": [
    "DE",
    "AU"
  ],
  "phone_number": "4930901820",
  "postal_address": {
    "address_line1": "Rosenweg 221",
    "address_line2": "apt. 33",
    "postcode": "45678",
    "city": "Berlin",
    "state": "BE",
    "country": "DE"
  },
  "address": {
    "address_line1": "Rosenweg 221",
    "address_line2": "apt. 33",
    "postcode": "45678",
    "city": "Berlin",
    "state": "BE",
    "country": "DE"
  },
  "fatca": {
    "status": false,
    "confirmed_at": "2020-08-24T14:15:22Z"
  },
  "terms_and_conditions": {
    "consent_document_id": "a8a87268-4f3c-4de2-abb9-a553a3bb7608",
    "confirmed_at": "2020-08-24T14:14:22Z"
  },
  "data_privacy_and_sharing_agreement": {
    "consent_document_id": "fb1827c3-2b29-47e1-84da-996d09517edc",
    "confirmed_at": "2020-08-24T14:16:22Z"
  }
}

In response to the successful creation of a user, you will receive a user ID, which you will need for regulatory checks and all further operations. You will also receive a webhook with the respective user created event.

Status of a user

The following status apply to a user:

Step 2: Conducting regulatory checks

Once the user has been created, it's time to verify that the user's information is correct and submit the user's instrument fit check. We designed the regulatory checks as flexible as possible, so that the onboarding process only takes a few seconds instead of days.

Check types

The following table lists all check types that need to be passed to finalise the user onboarding process. Checks do not have to be carried out in the given order.

The following statuses for a user check can be returned:

1. Verifying the user's identity

As a regulated investment firm, we must verify the user information. Therefore, we can rely on the identity verification that you perform during the user's onboarding process. To verify the user's identity, you will need to upload the identity verification documents in to a document bucket. We will take the documents from there and securely store them.

We currently accept video identification, in person identification (e.g., in the post office) as well as electronic identification (e.g., German eID standard) as approved identification methods. For users residing outside of Germany we also accept photo-based identification methods in combination with a liveness check. We can only accept identity verification that meets the following requirements:

• The confirmation date of the identity verification was no longer than 24 months ago.
• The documents used for identification have not expired.
• .zip archive containing all the following files uploaded to the document bucket (example for video identification method):
  • Photo of the person
  • Front of the ID document
  • Back of the ID document
  • Any additional photos of identity documents showing security features
  • Any video file or a series of photos.

To provide us with the documents, proceed as follows:

1. Package all the required documents from your identity verification provider into a download archive.
2. Include the link to the documents ("data_download_link") for checks of the type the KYC when sending POST /users/{user_id}/checks.

Example request

{
  "type": "KYC",
  "check_confirmed_at": "2019-08-24T14:15:22Z",
  "data_download_link": "https://bucket.customer.com/ident/user3.zip",
  "document_type": "ID_CARD",
  "document_expiration_date": "2030-01-01",
  "nationality": "DE",
  "provider": "KYC provider",
  "method": "VIDEO_ID",
  "confirmed_address": {
    "address_line1": "Rosenweg 221",
    "address_line2": "apt. 33",
    "postcode": "45678",
    "city": "Berlin",
    "state": "BE",
    "country": "DE"
  }
}

In most cases, the information on the document used for identity verification containing the user’s address is sufficient for us to verify the address in the same call. In some cases, the address does not match or is simply not present on the documents, for which we require an additional proof of the user's address. See the next section 'Verifying the user's address'.

2. Verifying the user's address

In some cases, an additional verification of the user's address is required.

For proof of residency, we accept the following documents under the specified conditions:

• The maximum age of the document is twelve months (stated on the document).
  • Utility bills (water, gas, electricity)
  • Telephone bills (landline or post-paid)
  • Internet bills
  • Bank account statements
• The maximum age of the document is five years or more (documents must still be valid).
  • Registration certificates issued within the past five years
  • Residence permit (e.g., Blue Card) as long as it is valid
  • ID card on which the registration address is noted (e.g., in the case of an identity check with the passport) as long as it is valid.

To submit the address verification, proceed as follows:

1. Collect and validate a proof of residency document from the user.
2. Include the link to the documents ("data_download_link") for checks of the type POR when sending POST /users/{user_id}/checks.

Example request

{
  "type": "POR",
  "check_confirmed_at": "2020-08-24T14:15:22Z",
  "issuance_date": "2020-01-01",
  "data_download_link": "https://bucket.customer.com/por/user3.zip",
  "document_type": "UTILITY_BILL",
  "confirmed_address": {
    "address_line1": "Rosenweg 221",
    "address_line2": "apt. 33",
    "postcode": "45678",
    "city": "Berlin",
    "state": "BE",
    "country": "DE"
  }
}

3. Submitting the user's instrument fit

To offer investment products to your users, you are required to assess their investment experience and knowledge (i.e., carry out what is called an appropriateness or suitability check). Once you have collected the information, you need to submit the result of the instrument appropriateness or suitability check that you collect in your onboarding process.

To send the results of your user’s instrument appropriateness or suitability execute a check of type INSTRUMENT_FIT by sending

POST /users/{user_id}/checks.

Example request (suitability check)

{
  "type": "INSTRUMENT_FIT",
  "check_confirmed_at": "2020-08-24T14:15:22Z",
  "instrument_suitability": {
    "suitability": true
  }
}

4. Conducting internal compliance checks

In addition to the checks you perform, we run an internal compliance check on the user in the background. The results of this COMPLIANCE check are displayed when listing the checks after you have verified the identity of the user. You will also receive webhooks for this type of check.

5. Listing regulatory checks of a user

After you have posted all the checks, you can see the checks along with their status. Next to the checks you posted, you will find the additional internal compliance check. List the checks as follows:

GET/user/{user_id}/checks.

Example response

{
  "data": [
    {
      "id": "008a82d0-c5a4-4410-9318-d34786429c5a",
      "user_id": "7b39529a-e68c-4688-8242-7549d10d6084",
      "type": "KYC",
      "check_confirmed_at": "2019-08-24T14:15:22Z",
      "data_download_link": "https://bucket.customer.com/ident/user3.zip",
      "document_type": "ID_CARD",
      "document_expiration_date": "2030-01-01",
      "nationality": "DE",
      "status": "PASSED",
      "provider": "KYC provider",
      "method": "VIDEO_ID",
      "confirmed_address": {
        "address_line1": "Rosenweg 221",
        "address_line2": "apt. 33",
        "postcode": "45678",
        "city": "Berlin",
        "state": "BE",
        "country": "DE"
      }
    },
    {
      "id": "a680ff52-3a96-4e82-a2ab-12563bbd1a2e",
      "user_id": "7b39529a-e68c-4688-8242-7549d10d6084",
      "type": "INSTRUMENT_FIT",
      "check_confirmed_at": "2020-08-24T14:15:22Z",
      "status": "PASSED",
      "instrument_suitability": {
        "suitability": true
      }
    },
    {
      "id": "b633a915-ed3c-43d7-afb5-a550f26ccb0d",
      "user_id": "7b39529a-e68c-4688-8242-7549d10d6084",
      "type": "POR",
      "check_confirmed_at": "2020-08-24T14:15:22Z",
      "issuance_date": "2020-01-01",
      "data_download_link": "https: //bucket.customer.com/por/user3.zip",
      "document_type": "UTILITY_BILL",
      "status": "PASSED",
      "confirmed_address": {
        "address_line1": "Rosenweg 221",
        "address_line2": "apt. 33",
        "postcode": "45678",
        "city": "Berlin",
        "state": "BE",
        "country": "DE"
      }
    },
    {
      "id": "76aa72aa-3738-4640-bad5-68c1196dc758",
      "user_id": "7b39529a-e68c-4688-8242-7549d10d6084",
      "type": "COMPLIANCE",
      "check_confirmed_at": "2020-08-24T14:15:22Z",
      "status": "PASSED"
    }
  ]
}

Webhooks for regulatory checks

Due to the asynchronous nature of the user checks, we provide webhooks for the creation of the respective checks as well as the notification of the final status of the check. For more information about the webhooks, please refer to the user check events.

After passing all relevant regulatory checks, the user is activated and you will receive a USER.ACTIVATED event.

Step 3: Listing users

You can list all users with GET /users.

To retrieve a single user call GET /users/{user_id} with the user ID you received after creation.

Example response

{
  "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202",
  "created_at": "2021-07-21T14:10:00.00Z",
  "updated_at": "2021-07-21T14:10:00.00Z",
  "first_name": "Karl",
  "last_name": "Schmidt",
  "email": "karl.schmidt@example.com",
  "salutation": "SALUTATION_MALE",
  "title": "DR",
  "birth_date": "1972-09-30",
  "birth_city": "Berlin",
  "birth_country": "DE",
  "birth_name": "Schmidt",
  "nationalities": [
    "DE",
    "AU"
  ],
  "phone_number": "4930901820",
  "postal_address": {
    "address_line1": "Rosenweg 221",
    "address_line2": "apt. 33",
    "postcode": "45678",
    "city": "Berlin",
    "state": "BE",
    "country": "DE"
  },
  "address": {
    "address_line1": "Rosenweg 221",
    "address_line2": "apt. 33",
    "postcode": "45678",
    "city": "Berlin",
    "state": "BE",
    "country": "DE"
  },
  "fatca": {
    "status": false,
    "confirmed_at": "2020-08-24T14:15:22Z"
  },
  "terms_and_conditions": {
    "consent_document_id": "a8a87268-4f3c-4de2-abb9-a553a3bb7608",
    "confirmed_at": "2020-08-24T14:14:22Z"
  },
  "data_privacy_and_sharing_agreement": {
    "consent_document_id": "fb1827c3-2b29-47e1-84da-996d09517edc",
    "confirmed_at": "2020-08-24T14:16:22Z"
  },
  "status": "ACTIVE"
}

Step 4: Creating user identifiers

In order to create regulatory required transaction reports, Upvest must maintain certain identifiers per user. By default, the Investment API supports the onboarding of users for the following nationalities (as a single nationality or, in the case of multiple nationalities, the first nationality if the nationalities array is in alphabetical order):

• AT - Austria
• DE - Germany
• FR - France
• HU - Hungary
• IE - Ireland
• LU - Luxembourg

Any other user nationalities require an additional identifier. You can add the relevant identifier as follows:

POST /users/{user_id}/identifiers

including the identifier type NATIONAL_ID in the payload.

More information on the accepted user identifiers can be found here.

Next steps

After successfully creating a user on the Investment API, you can proceed with opening an account group and an account for the respective user. The accounts will only become active once the user's onboarding has been successfully completed and all regulatory checks have been passed.