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 for all except US taxpayers).
• The waiver exempting Treezor from liability in case of a missing TIN.

The specific case of US taxpayers

Every US taxpayer must declare the United States as a tax residence along with the Tax Identification Number (TIN).

This applies to all users as soon as one of the following elements value is US:

• Nationality – Corresponds to the nationality or the otherNationality field for the physical users
• Birth country – Corresponds to the birthCountry field for physical users
• Address – Corresponds to the country or secondaryCountry field for both physical users and legal entities

In addition, when at least one of these values is US, the user specificiedUSPerson attribute must be set to 1.

Is considered a US citizen or resident…

A person is presumed to be a citizen of the United States:

• From the moment they have an American passport or
• If they are born on the territory of the United States, even when such a place of birth appears on a passport of another country, or the person also holds another nationality or has their residence in another country.

A person is a resident of the United States if:

• They are holding a green card for permanent residence in the United States.
• They are residing permanently in the United States or have spent a sufficient period of time in the United States over the last three years.

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), which is optional except for US taxpayers.
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.

Request

You can create a tax residence using the dedicated endpoint:

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 – Swagger documentation available

Check the Tax Residence section of the Swagger.

Endpoints

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