Operating Model:
Operating Model:

User onboarding

This guide walks you through all aspects of onboarding a user in the Upvest 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.

Onboarding a user

Prerequisites

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

1 Creating a user

To onboard a user, send the user's personal information with POST /users. For this call, you need to collect name, birthdate, email address, address and other data, which have to satisfy the following conditions:

  • 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 primary 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.
INFO

For our Sandbox environment you can use the following document IDs:

  • Terms and conditions: d0b83880-3809-4eee-b0df-ca50db84c15a
  • Data privacy and sharing agreement: 7ab0fc5c-8157-4acd-b02d-6ccda0e81dec
COMING SOON
  • Onboarding for businesses will follow soon. Currently, we only support onboarding and opening securities accounts for individuals.
  • Information on the user’s tax residency as well as on the Common Reporting Standard (CRS) is currently under development and will follow soon. Currently, we only onboard users that are non-US persons.

In the response of the successful user creation, you will receive a user ID that will be needed to proceed with the regulatory checks and all further operations. Furthermore, you will receive a webhook with the respective user created event.

The following status apply to a user:

Status Description
INACTIVE The user's approval is pending - the user is visible via our API but cannot be processed.
ACTIVE User is active - the full functionality of the Investment API is accessible.
OFFBOARDING The offboarding of the user is initiated - the prerequisites are being checked continuously.
OFFBOARDED User is offboarded - the user's record can be kept for the regulatory period.

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"
  }
}

Listing users

A single user can be retrieved by the user ID you received after creating the user by calling GET /users/{user_id}.

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"
}

All users can be listed with GET /users.

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.

The following status apply to a user checks:

Status Description
IN_PROGRESS Check is in progress.
PASSED Check has passed.
FAILED Check has failed.

Types of regulatory checks

Below checks do not need to follow the outlined order.

Check type Description
KYC Know Your Customer: Verifying the user's identity and address (if possible).
POR Proof Of Residency: Verifying the user's address (if not covered by the documents used for verifying the user's identity; check type KYC).
INSTRUMENT_FIT Result of the assessment of the user's instrument appropriateness or suitability.
COMPLIANCE Internal compliance check that will run in the background once the identity verification is sucessfully passed (check type KYC).

Verifying the user's identity

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

Currently, we accept video identification, in person identifications (e.g., in the post office) as well as electronic identifications (e.g., German eID standard). We can only accept identity verification that meets the following requirements:

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

You package all required documents from your identity verification provider in a download archive and include the link to the documents in the call POST /users/{user_ID}/checks with the KYC type in the payload.

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, verifying the user's address.

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"
  }
}

Verifying the user's address

INFO

Address verification is only needed, if the user's address could not be verified by the document used for verifying the user's identity (check type KYC). The address may not be present on the document or may not match the user's address.

In some cases, an additional verification of the user's address is required. You need to collect a proof of residency document from the user and send it to the same /users/{user_ID}/checks endpoint with the type POR in the payload.

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

  • Maximum age of the document is twelve months (stated on the document)
    • Utility bills (water, gas, electricity)
    • Telephone bills
    • Internet bills
    • Bank account statements
  • Maximum age of the document is five years or older (documents must still be valid)
    • Registration certificates issued within the past five years
    • Residence permit (e.g., Blue Card) as long as valid
    • ID card that contains the registered address (e.g., in case of a identity verification with a passport) as long as valid

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"
  }
}

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., do a so-called 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 POST /users/{user_ID}/checks with type INSTRUMENT_FIT in the payload.

Example request (suitability check)

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

Conducting internal compliance checks

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

Webhooks for regulatory checks

Due to the asynchronous nature of the user checks, we offer webhooks for the creation of the respective checks as well as 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.

Listing regulatory checks of a user

After you have posted all the checks, you can see the checks together with their status by listing them with GET/user/{user_ID}/checks. Next to the checks you posted, you will find the additional internal compliance check.

The following check types need to be passed to finalise the user onboarding process:

  • KYC
  • POR
  • INSTRUMENT_FIT
  • COMPLIANCE

Example response

{
  "data": [
    {
      "id": "008a82d0-c5a4-4410-9318-d34786429c5a",
      "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",
      "type": "INSTRUMENT_FIT",
      "check_confirmed_at": "2020-08-24T14:15:22Z",
      "status": "PASSED",
      "instrument_suitability": {
        "suitability": true
      }
    },
    {
      "id": "b633a915-ed3c-43d7-afb5-a550f26ccb0d",
      "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",
      "type": "COMPLIANCE",
      "check_confirmed_at": "2020-08-24T14:15:22Z",
      "status": "PASSED"
    }
  ]
}

User identifiers

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

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

Any other user nationalities require an additional identifier. Therefore, Upvest provides an endpoint to capture relevant identifiers POST /users/{user_ID}/identifiers with 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.

Was this page helpful?