Organization VAT IDs

Overview

A VAT ID (Value Added Tax Identification Number) is an identification number used for tax purposes, specifically for value-added tax. It is assigned to organizations and helps authorities track and manage tax-related transactions. VAT ID names and formats vary from country to country. For example, in the European Union, it is referred to as “VAT identification number” or VATIN. Common names in other countries include Business Number (BN), Good and Services Tax number, and sales tax numbers.

Roles and permissions

To use the /entities/{entity_id}/vat-ids* endpoints with an organization user token, this organization user must have a role with the entity_vat_ids permission. If using a partner-level token, no special permissions are needed.

Check if VAT ID is required for organization

See Organization tax ID and VAT IDs.

Supported VAT ID types

Currently, Tesouro supports the following VAT ID types:

Country	Type	Description	Example
Australia	`au_abn`	Australian Business Number (AU ABN)	51824753556
Australia	`au_arn`	Australian Taxation Office Reference Number	518247535567
Austria	`eu_vat`	European VAT number	ATU12345678
Belgium	`eu_vat`	European VAT number	BE0123456789
Brazil	`br_cnpj`	Brazilian CNPJ number	28.271.211/0001-88
Brazil	`br_cpf`	Brazilian CPF number	137.609.391-04
Bulgaria	`bg_uic`	Bulgaria Unified Identification Code	123456789
Bulgaria	`eu_vat`	European VAT number	BG0123456789
Canada	`ca_bn`	Canadian BN	123456789
Canada	`ca_gst_hst`	Canadian GST/HST number	123456789RT0002
Canada	`ca_pst_bc`	Canadian PST number (British Columbia)	PST-1234-5678
Canada	`ca_pst_mb`	Canadian PST number (Manitoba)	123456-7
Canada	`ca_pst_sk`	Canadian PST number (Saskatchewan)	1234567
Canada	`ca_qst`	Canadian QST number (Québec)	1234567890TQ1234
Chile	`cl_tin`	Chilean TIN	12.345.678-K
Croatia	`eu_vat`	European VAT number	HR12345678912
Cyprus	`eu_vat`	European VAT number	CY12345678Z
Czech Republic	`eu_vat`	European VAT number	CZ1234567890
Denmark	`eu_vat`	European VAT number	DK12345678
Estonia	`eu_vat`	European VAT number	EE123456789
European Union	`eu_oss_vat`	European One Stop Shop VAT number for non-Union scheme	EU123456789
Finland	`eu_vat`	European VAT number	FI12345678
France	`eu_vat`	European VAT number	FRAB123456789
Georgia	`ge_vat`	Georgian VAT	123456789
Germany	`eu_vat`	European VAT number	DE123456789
Greece	`eu_vat`	European VAT number	EL123456789
Hong Kong	`hk_br`	Hong Kong BR number	12345678
Hungary	`hu_tin`	Hungary tax number (adószám)	12345678-1-23
Hungary	`eu_vat`	European VAT number	HU12345678912
Iceland	`is_vat`	Icelandic VAT	123456
India	`in_gst`	Indian GST number	12ABCDE3456FGZH
Indonesia	`id_npwp`	Indonesian NPWP number	12.345.678.9-012.345
Ireland	`eu_vat`	European VAT number	IE1234567AB
Israel	`il_vat`	Israel VAT	12345
Italy	`eu_vat`	European VAT number	IT12345678912
Japan	`jp_cn`	Japanese Corporate Number (Hōjin Bangō)	1234567891234
Japan	`jp_rn`	Japanese Registered Foreign Businesses’ Registration Number (Tōroku Kokugai Jigyōsha no Tōroku Bangō)	12345
Kenya	`unknown`	Kenya Revenue Authority Personal Identification Number (PIN)	P123456789X
Latvia	`eu_vat`	European VAT number	LV12345678912
Liechtenstein	`li_uid`	Liechtensteinian UID number	CHE123456789
Lithuania	`eu_vat`	European VAT number	LT123456789123
Luxembourg	`eu_vat`	European VAT number	LU12345678
Malaysia	`my_frp`	Malaysian FRP number	12345678
Malaysia	`my_itn`	Malaysian ITN	C 1234567890
Malaysia	`my_sst`	Malaysian SST number	A12-3456-78912345
Malta	`eu_vat`	European VAT number	MT12345678
Mexico	`mx_rfc`	Mexican RFC number	ABC010203AB9
Netherlands	`eu_vat`	European VAT number	NL123456789B12
New Zealand	`nz_gst`	New Zealand GST number	123456789
Norway	`no_vat`	Norwegian VAT number	123456789MVA
Pakistan	`unknown`	Pakistan National Tax Number (NTN) or Registration Number. Same value as the organization’s `tax_id`.	4174941-3
Philippines	`unknown`	Philippines Taxpayer Identification Number (TIN), if it’s registered for VAT.	000123456001
Poland	`eu_vat`	European VAT number	PL1234567890
Portugal	`eu_vat`	European VAT number	PT123456789
Romania	`eu_vat`	European VAT number	RO1234567891
Russia	`ru_inn`	Russian INN	1234567891
Russia	`ru_kpp`	Russian KPP	123456789
Saudi Arabia	`sa_vat`	Saudi Arabia VAT	123456789012345
Singapore	`sg_gst`	Singaporean GST	M12345678X
Singapore	`sg_uen`	Singaporean UEN	123456789F
Slovakia	`eu_vat`	European VAT number	SK1234567891
Slovenia	`si_tin`	Slovenia tax number (davčna številka)	12345678
Slovenia	`eu_vat`	European VAT number	SI12345678
South Africa	`za_vat`	South African VAT number	4123456789
South Korea	`kr_brn`	Korean BRN	123-45-67890
Spain	`es_cif`	Spanish NIF number (previously Spanish CIF number)	A12345678
Spain	`eu_vat`	European VAT number	ESA1234567Z
Sweden	`eu_vat`	European VAT number	SE123456789123
Switzerland	`ch_vat`	Switzerland VAT number	CHE-123.456.789 MWST
Taiwan	`tw_vat`	Taiwanese VAT	12345678
Thailand	`th_vat`	Thai VAT	1234567891234
Ukraine	`ua_vat`	Ukrainian VAT	123456789
United Arab Emirates	`ae_trn`	United Arab Emirates TRN	123456789012345
United Kingdom	`gb_vat`	United Kingdom VAT number	GB123456789
United Kingdom	`eu_vat`	Northern Ireland VAT number. Used for transactions that fall under the Northern Ireland Protocol. See below for details.	XI123456789
United States	`us_ein`	Federal Tax Identification Number or EIN. Same value as the organization’s `tax_id`.	12-3456789
Other countries	`unknown`

Need another VAT ID type?To request additional VAT ID types, send us an email to developers@tesouro.com.

Add a VAT ID to an organization

Note for Spanish organizationsOrganizations registered in the Canary Islands must use the country code IC instead of ES for their VAT ID.Organizations registered in Ceuta and Melilla must use EA as the country code.This is required for Tesouro to apply the regulatory compliance checks specific to those regions of Spain.

To add a VAT ID to an organization, call POST /entities/{entity_id}/vat-ids and specify the VAT ID type, value, and the country where this VAT ID is registered:

curl -X POST 'https://api.sandbox.tesouro.com/v1/entities/{entity_id}/vat-ids' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "country": "DE",
       "type": "eu_vat",
       "value": "123456789"
     }'

The successful response contains a unique id assigned to this VAT ID object, along with other information:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "country": "DE",
  "type": "eu_vat",
  "value": "123456789",
  "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Note down the id of this VAT ID object - you will need to specify it later in the entity_vat_id_id field when creating invoices:

Invoice payload example

{
  "type": "invoice",
  "line_items": [
    ...
  ],
  ...
  "entity_vat_id_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Multiple VAT IDs

An organization that sells globally may be registered for VAT in multiple jurisdictions. In this case, make sure to add all VAT IDs that this organization has.

Example: UK organizations that trade under the Northern Ireland Protocol

UK organizations that ship goods from Northern Ireland to the European Union fall under the Northern Ireland (NI) Protocol. Among other things, the NI Protocol requires that invoices for such sales display the seller VAT ID with the “XI” prefix instead of “GB”. To account for this, UK organizations need to add two VAT IDs:

one with type="eu_vat" - to be used for sales invoices that fall under the NI Protocol;
another one with type="gb_vat" - to be used for all other sales invoices.

Below are the payload examples to be used with POST /organizations/{organization_id}/vat-ids. Note that the VAT ID country (“GB”) and value (VAT number) are the same in both examples. The only difference is the type, which determines the VAT ID prefix that will appear on PDF invoices.

VAT ID payload for NI Protocol	VAT ID payload for all other sales
`{ "country": "GB", "type": "eu_vat", "value": "123456789" }`	`{ "country": "GB", "type": "gb_vat", "value": "123456789" }`

Do not include the “XI” or “GB” prefix in the value. Tesouro will add these prefixes to VAT IDs automatically when generating PDF invoices.

Make sure to specify the correct VAT ID (of type gb_vat or eu_vat) for each invoice or other document created by the organization:

Invoice payload example

{
  "type": "invoice",
  ...
  "entity_vat_id_id": "<UUID of the 'gb_vat' or 'eu_vat' VAT ID object>"
}

List all VAT IDs

To get a list of all VAT IDs associated with an organization, call GET /entities/{entity_id}/vat-ids.

Retrieve a VAT ID

To get the details of a specific VAT ID associated with an organization, call GET /entities/{entity_id}/vat-ids/{vat_id}.

Edit a VAT ID

To update an existing VAT ID of an organization, call PATCH /entities/{entity_id}/vat-ids/{vat_id}.

Delete a VAT ID

To delete an existing VAT ID from the list of VAT IDs associated with the specified organization, call DELETE /entities/{entity_id}/vat-ids/{vat_id}.

Getting started

Embedded components

Authentication

Roles & permissions

Manage organizations

Common objects

Accounts payable

Accounts receivable

Expense management

Payments

Advanced

Accounting integrations

Organization VAT IDs

Overview

Roles and permissions

Check if VAT ID is required for organization

Supported VAT ID types

Add a VAT ID to an organization

Multiple VAT IDs

Example: UK organizations that trade under the Northern Ireland Protocol

List all VAT IDs

Retrieve a VAT ID

Edit a VAT ID

Delete a VAT ID

​Overview

​Roles and permissions

​Check if VAT ID is required for organization

​Supported VAT ID types

​Add a VAT ID to an organization

​Multiple VAT IDs

​Example: UK organizations that trade under the Northern Ireland Protocol

​List all VAT IDs

​Retrieve a VAT ID

​Edit a VAT ID

​Delete a VAT ID

Overview

Roles and permissions

Check if VAT ID is required for organization

Supported VAT ID types

Add a VAT ID to an organization

Multiple VAT IDs

Example: UK organizations that trade under the Northern Ireland Protocol

List all VAT IDs

Retrieve a VAT ID

Edit a VAT ID

Delete a VAT ID