Diff for /documentation/guides/users/user_tax_onboarding.md
On this page, you can preview the modified document with the changes.
Note that the links within this diff are most likely broken because they are
relative to the original document or
point to another document that is not part of the changeset.
User tax onboarding
This article is released as preview only. The function mentioned here is not yet usable and not supported, but it may change in future versions.
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.
- If a user certifies a German tax residency amongst others, the German tax residency needs to be submitted as primary in any case.
- Using postal addresses 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.
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
{
<del>"residencies_declared_at": "2021-09-24T12:56:22Z",
"tax_residency":</del>
<ins>"tax_residencies": [</ins>
{
"country": "DE",
"tax_identifier_number": "12345678901"
}
<ins>]</ins>
}For users with a German tax residency, the Investment API can enrich the provided user data by retrieving a German tax identification number (TIN) and other taxation attributes (e.g., church tax status) through an overnight backend process.
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
{
<del>"tax_residency": {
"country": "DE",
"tax_identifier_number": "12345678901"
},
"residencies_declared_at": "2021-09-24T12:56:22Z",
"additional_tax_residencies":</del>
<ins>"tax_residencies":</ins> [
{
"country": "IT",
"tax_identifier_number": "40021158793"
},
{
"country": "FR",
<del>"reason_missing_tin":</del>
<ins>"missing_tin_reason":</ins> "COUNTRY_HAS_NO_TIN"
<ins>},
{
"country": "DE",
"tax_identifier_number": "12345678901"</ins>
}
]
}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",
<del>"reason_missing_tin":</del>
<ins>"missing_tin_reason":</ins> "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, because a timestamp for full record of residencies must be provided.residency_declared_at for the
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: