User tax onboarding

This guide provides you with the knowledge you need to understand why Upvest requires additional tax-related information from users prior to account opening, what information has to be provided to Upvest and how to interact with the Investment API endpoints to achieve it.

How user tax onboarding works

Upvest is obliged to collect tax-specific information from users in order to determine their appropriate tax status as well as for other applications (e.g., to comply with regulatory reporting requirements under Common Reporting Standards).

If a user is a German tax resident (i.e., has the primary tax residence in Germany), Upvest automatically deducts German withholding tax, solidarity charge and church tax (depending on confession) prior to a payout.

Currently, users with non-German primary tax residence are considered tax-aliens by Upvest, which is why no automatic tax deduction is supported.

Step 1: Determining the tax residency

During the user onboarding, users need to explicitly declare their individual tax residencies.

The Investment API supports single and multiple tax residencies per user. For example, multiple tax residencies might exist because of a user's foreign real estate ownership.

Regardless of the total number of tax residencies, every user is required to determine a single primary tax residency (see tax_residency object in the request body below). When a given user certifies that all tax residencies are declared properly, Upvest activates this specific user and the associated accounts within the Investment API.

Step 2: User tax onboarding

Generally, you can declare a user’s tax residency (incl. tax identification and residency) as follows:

POST /users/{user_id}/tax_residencies

The following examples illustrate valid use cases.

1. Declaring a single German tax residency

This declaration is made without providing the user’s tax identification number:

POST /users/{user_id}/tax_residencies

Example request

{
   "tax_residencies": [
      {
         "country": "DE",
         "tax_identifier_number": "12345678901"
      }
   ]
}

As in this case, the TIN has not been provided by the user, the Investment API queries it via the respective backend process, which allows for a smoother and more convenient user onboarding experience.

2. Declaring multiple tax residencies

You can declare multiple tax residencies for a user with

POST /users/{user_id}/tax_residencies

Example request

{
    "tax_residencies": [
        {
            "country": "IT",
            "tax_identifier_number": "40021158793"
        },
        {
            "country": "FR",
            "missing_tin_reason": "COUNTRY_HAS_NO_TIN"
        },
        {
            "country": "DE",
            "tax_identifier_number": "12345678901"
        }
    ]
}

In this example, the user's individual German TIN is provided. This would allow the user to claim a tax exemption directly during onboarding.

If a user does not provide the TIN during onboarding, a tax exemption can be declared after the onboarding process has been fully completed. Either during the declaration of the tax exemption, an automatic query of the TIN will take place in the background or the TIN will be specified separately with the resource tax_exemptions.

Although the user has declared two additional tax residencies (for Italy and France), Germany was indicated to be the primary tax residency, which is why the user is subject to German withholding taxes. Generally, for non-German tax residencies the TIN information of a given country is a required field (see the Italian tax residency).

Reason for a missing TIN

In some cases a user has a legitimate reason why a TIN cannot be provided. For example, certain countries do not issue official TINs or a TIN has not yet been issued by the authorities.

In this case, the reason why a user has not provided the required (foreign) TIN must be provided as follows:

Example

{
    "country": "FR",
    "missing_tin_reason": "COUNTRY_HAS_NO_TIN"
}

3. Updating tax residencies

The API endpoint /users/{user_id}/tax_residencies always requires the complete set of a user’s tax residencies at a given time, a full record of residencies must be provided.

Thus, updates on tax residencies always contain the full set of tax residencies. Each request to this API endpoint is treated as "self-contained", which is also the reason why Upvest does not provide a separate PATCH resource.

If you want to update a user’s tax residencies, proceed as follows:

POST /users/{user_id}/tax_residencies