API status

User tax onboarding

Upvest requires additional tax-related information from users prior to account opening. This guide describes which information has to be provided to Upvest and how to interact with the Investment API endpoints to achieve that.

Why does Upvest require this information?

Upvest is obliged to collect tax-specific information from users in order to determine their appropriate tax status, and to comply with regulatory reporting requirements under Common Reporting Standards.

If a user has a tax residence in Germany, Upvest automatically deducts German withholding tax, solidarity charge and church tax (depending on confession) prior to paying out sell order proceeds or dividend distributions.

Currently, users with non-German tax residence are considered tax-aliens by Upvest. No automatic tax deduction is supported for these users.

Determining the user's tax residency

The Investment API supports single and multiple tax residencies per user. For example, a user might have multiple tax residencies because they own foreign real estate.

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

  • If a user certifies a German tax residency amongst others, the German tax residency will be used as the primary tax residence.
  • Using an address to determine a user’s tax residency might lead to incorrect results. Upvest therefore asks you to have your users explicitly state their tax residency. Furthermore, Upvest needs to record the respective tax identifiers of the users.

Generally, you can declare a user’s tax residency (consisting of tax residency country code and identifier) as follows:

POST /users/{user_id}/tax_residencies

A list of TINs (Tax Identification Number) including the corresponding regex can be found here.

Use cases specific to Germany

The following examples illustrate valid use cases specific to Germany.

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

{
    "country": "DE",
    "missing_tin_reason": "OTHER_REASONS"
}

For users with a German tax residency, the Investment API can enrich the provided data by retrieving a German tax identification number (TIN) and other taxation attributes (e.g., church tax status) through an overnight backend process. For non-German tax residencies the respective identifiers have to be stated explicitly.

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.

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": "ABCDEF12G34H567I"
        },
        {
            "country": "FR",
            "missing_tin_reason": "TIN_NOT_YET_ASSIGNED"
        },
        {
            "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, including TIN retrieval, has been completed. Either an automatic query of the TIN will take place in the background or the TIN will be specified separately before the tax exemptions are configured.

Although the user has declared two additional tax residencies, for Italy and France, Germany will be used as the primary tax residency. This user will be subject to German withholding taxes. For non-German tax residencies either TIN information for a given country, or a valid reason for the omitting the TIN information are required.

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. Upvest requires the Client to follow up with the user to provide a TIN at a later point in time.

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

Example

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

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

Each request to this API endpoint is treated as "self-contained". 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

Next steps

You now have all the information you need to onboard users for taxation purposes.

Was this page helpful?