API status

User onboarding

This guide walks you through onboarding a user in the Investment API. It includes user creation, regulatory checks and regulatory identifiers.

Our flexible regulatory checks ensure that the onboarding process only takes a few seconds instead of days.

Prerequisites

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

  • Onboarding for businesses is not supported, but will follow soon. Currently, we only support onboarding and opening securities accounts for individuals.

  • Support for information on the user’s tax residency and the Common Reporting Standard (CRS) is currently under development and will follow soon. Currently, we only onboard users that are non-US persons.

Onboarding a user

 1    Create a user

1.1   Collect the user's data

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.2   POST the user data

Send the user's personal information with a POST /users 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.

Webhooks notify you of events in business processes, not the success or failure of the initialisation of those processes.

Please be sure to check the HTTP status of the response to your requests and handle failure cases appropriately.

Upvest has introduced branches to allow our clients to easily customise the services and user experience they offer to their users. Therefore, users can be assigned to a branch, for example, depending on their geographical market. The branch_id is an optional field and is only available after consultation with Upvest. Learn more about branches here.

 2    Conducting regulatory checks

There are four types of checks that need to be carried out before we can activate the user:

  • A "Know Your Customer" (KYC) check.
  • A "Proof of Residency" (POR) check, if this was not covered by the KYC check.
  • An "Instrument Fit" check.
  • An internal compliance check.

There is no specific order in which these checks must be completed.

In this section we'll run through how to submit evidence for these checks, and how you can see their status via the Upvest Investment API.

2.1   Know your customer

As a regulated investment firm, we must verify the user information. We 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 into a document bucket. We will take the documents from there and securely store them.

We 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. You must indicate the method of identification in your API requests.

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 KYC Document Requirements.

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.

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

2.2   Proof of residency

Usually, the document used for the "Know Your Customer" identity verification contains the user’s address and this is sufficient to verify the address in the same call. In some cases, the address does not match or is simply not present. When this occurs, we require additional proof of the user's address.

When this occurs we require an additional "Proof of Residency" check using, for example, a recent utility bill or residence permit. See POR Document Requirements for details.

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.

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

2.3   Submitting the user's instrument fit

To offer investment products to your users, you are required to assess their investment experience and knowledge by an appropriateness or suitability check during your user onboarding process. You need to submit the result of that check to us before we can activate the user.

To send the results, use the check type INSTRUMENT_FIT in a POST /users/{user_id}/checks.

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

2.4   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.

2.5   Listing regulatory checks

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.

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

The following statuses for a user check can be returned:

2.6   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.

 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.

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

Status of a user

The following status apply to a user:

StatusDescription
INACTIVEThe user's approval is pending - the user is visible via our API but cannot be processed.
ACTIVEUser is active - the full functionality of the Investment API is accessible.
OFFBOARDINGThe offboarding of the user is initiated - the prerequisites are being checked continuously.
OFFBOARDEDUser is offboarded - the user's record can be kept for the regulatory period.

 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, by sending a POST /users/{user_id}/identifiers request.

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

 ✔    User onboarding complete

Congratulations, you now know how to onboard a user in the Upvest Investment API!

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?