Authentication scopes —
taxes:adminFor more information, refer to Authentication scopes.
In order to create a new tax exemption, Upvest must have the user’s Tax Identification Number (TIN).
Webhook handler ready — Set up a webhook endpoint to listen for tax exemption status updates.
- Subscribe to
TAX_EXEMPTION.*events.
For more information, refer to Implementing webhooks.
- Subscribe to
The tax exemption status transitions from NEW to ACTIVE when you receive the corresponding webhook event. Monitor these events to track activation progress.
For more information, refer to Tax exemption webhook events
To submit a tax exemption request, execute the following request:
POST /tax_exemptions
Example
{
"user_ids": [
"70fd317b-81e1-4f21-9f7e-3b5cb4dfe686"
],
"tax_exemption_details": {
"tax_exemption_type": "SINGLE",
"tax_exemption_amount": {
"currency": "EUR",
"amount": "1000"
}
},
"country": "DE",
"valid_to_date": "2024-12-31"
}The request body contains the following:
| Parameter | Description | Example value |
|---|---|---|
user_ids | Required: One or more user IDs in an array. The tax exemptions apply to all account groups belonging to the respective user or pair. There can only ever be one user ID for a single tax exemption type. The main use case for submitting an array of user_ids is to create a joint tax exemption for a married couple. | 70821d79-366f-4873-804b-14857d690496 |
tax_exemption_amount.amount | Required: The amount of tax exemption applied for. From tax year 2023, the maximum amount of tax exemption for a single tax exemption is EUR 1,000. Valid parameter range: ["0.01", "1000.00"] The value is a number in the form of a character string. | 1000.00 |
tax_exemption_amount.currency | Required: The currency of the requested tax exemption amount. NOTE: Only euros are currently supported. Valid parameter: EUR. | EUR |
country | Required: The tax country code encapsulates the respective tax country. NOTE: Only German tax exemptions are currently supported. Valid parameter: DE | DE |
tax_exemption_type | Required: The type of tax exemption determines the maximum tax exemption amount. NOTE: Currently, only tax exemptions for individuals are supported. Valid parameter: SINGLE | SINGLE |
valid_to_date | Required: The date (RFC 3339, section 5.6) until which the tax exemption is valid. If the validity is unlimited, the date is omitted. | 2024-12-31 |
The ID in the response is the ID of the tax exemption created.
Note that the tax exemption is only active when a response indicating its activation is received via a webhook. At this current stage of the process, it still has the status NEW.
The API can discard a request before it is accepted for downstream processing.
This happens if it does not pass the validation of the input data and additional internal consistency checks. Reasons for such behaviour can be, for example, missing parameters or if the requested tax exemption amount exceeds the maximum amount.
Read also the webhooks section of this guide.