Tax residence

Introduction

All users (both physical users and legal entities) going through the KYC verification process must declare at least one country of tax residency. This is an obligation enforced by the CRS and FATCA.

Tip – Not requested for Legal representatives

The legal representative of a legal entity isn’t required to declare a tax residency.

When declaring the tax residence, besides the country, you can also provide:

• The Tax Identification Number (TIN) of the user (optional except for US taxpayers and users whose distributionCountry is IT).
• The waiver exempting Treezor from liability in case of a missing TIN.

Reading – US taxpayers must declare a US tax residence along with the TIN

This applies for users whose nationality, birth country, or address is US.

Learn more in the Declare tax residence article of the Support Center.

Creation

Parameters

Parameters	Type	Description
userId	integer	The unique identifier of the user whose tax residence country is to be declared.
country	string	The country code for the country of tax residence. Must be US if the corresponding user specificiedUSPerson attribute is set to 1.
taxPayerId	string	The Tax Identification Number (TIN) or Tax Code, which is optional except for US taxpayers and users whose distributionCountry is IT.
liabilityWaiver	boolean	The waiver exempting Treezor from liability in case of a missing TIN. Must be set to true if the taxPayerId field is null or empty.

API – API Reference available

For a complete list of Tax Residence attributes, check the Tax Residences section of the API Reference.

Request

Endpoint: /v1/taxResidences

CURL

curl -X POST '{baseUrl}/v1/taxResidences' \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here is an example of {payload}:

JSON

{
	"userId":100642533,
	"country":"FR",
	"taxPayerId":"12345",
	"liabilityWaiver":false
}

Returns the Tax Residence object:

JSON

{
  "taxResidences": [
      {
        "id": 199519,
        "userId": 100642533,
        "country": "FR",
        "taxPayerId": "12345",
        "liabilityWaiver": false,
        "createdDate": "2024-07-22 10:38:37",
        "lastUpdate": "",
        "deletedDate": "",
        "isDeleted": false
      }
  ]
}

Retrieval

You may use the dedicated endpoints to search for tax residences.

Here is an example with the /v1/taxResidences request and the userId query parameter to filter the search for a specific user.

CURL

curl -X GET '{baseUrl}/v1/taxResidences?userId=100642533' \
	--header 'Authorization: Bearer {accessToken}'

Returns the list of tax residences filtered for the selected user.

JSON

{
    "taxResidences": [
        {
            "id": 199519,
            "userId": 100642533,
            "country": "FR",
            "taxPayerId": "12345",
            "liabilityWaiver": false,
            "createdDate": "2024-07-22 10:38:37",
            "lastUpdate": "",
            "deletedDate": "",
            "isDeleted": false
        }
    ],
    "meta": {
        "maxPerPage": 10,
        "pageNumber": 1,
        "totalPages": 1,
        "totalResults": 1
    }
}

Tax Residence object

JSON

{
  "id": 0,
  "userId": 0,
  "country": "string",
  "taxPayerId": "string",
  "liabilityWaiver": true,
  "createdDate": "string",
  "lastUpdate": "string",
  "deletedDate": "string",
  "isDeleted": false
}

API – API Reference available

For a complete list of Tax Residence attributes, check the Tax Residences section of the API Reference.

Endpoints

Endpoint	Scope
/v1/taxResidences Create a Tax Residence	read_write
/v1/taxResidences Search for Tax Residences	read_only
/v1/taxResidences/{taxResidenceId} Retrieve a Tax Residence based on its id	read_only
/v1/taxResidences/{taxResidenceId} Update a Tax Residence	read_write
/v1/taxResidences/{taxResidenceId} Delete a Tax Residence	read_write