TIN_VALID¶

Info

New in Atfinity 17.

Description¶

TIN_VALID checks whether a string is a valid TIN (Tax Identification Number) for a given country. It verifies the country-specific format and checksum using the python-stdnum library. It does not verify that the number is actually registered with a tax authority, only that it is structurally valid.

The country is given as an ISO 3166-1 alpha-2 code and is matched case-insensitively (de, De, dE, and DE all select Germany). Spaces, dashes, and dots in the number are tolerated.

Syntax¶

TIN_VALID(tin, country)

Returns:

true: the number is a valid TIN for a supported country.
false: the country is supported, but the number is not a valid TIN for it.
unknown: the country is not supported (see the list below), or either argument is not a string. This lets rules distinguish "we checked and it is wrong" from "we cannot check this country". Guard for it explicitly where it matters, e.g. TIN_VALID(p.tin, p.country) = false.

Supported countries¶

For each country the underlying national scheme is listed. Where python-stdnum has no personal tax-number scheme, the country's VAT / business number is used as the closest available identifier, these show VAT in the Scheme column and will not accept a purely personal number.

Country	Code	Scheme
Andorra	`AD`	NRT
Argentina	`AR`	CUIT
Australia	`AU`	TFN (Tax File Number)
Austria	`AT`	Steuernummer
Belgium	`BE`	National Number (Rijksregisternummer)
Brazil	`BR`	CPF
Bulgaria	`BG`	EGN
Canada	`CA`	SIN
Chile	`CL`	RUT
China	`CN`	Resident Identity Card
Colombia	`CO`	NIT
Croatia	`HR`	OIB
Cyprus	`CY`	VAT
Czechia	`CZ`	Rodné číslo
Denmark	`DK`	CPR
Estonia	`EE`	Isikukood
Finland	`FI`	HETU
France	`FR`	Numéro fiscal (NIF)
Germany	`DE`	Steuer-Identifikationsnummer (IdNr)
Greece	`GR`	AFM (VAT)
Hungary	`HU`	VAT
Ireland	`IE`	PPS Number
Israel	`IL`	ID Number
Italy	`IT`	Codice Fiscale
Latvia	`LV`	VAT
Liechtenstein	`LI`	PEID
Lithuania	`LT`	Asmens kodas
Luxembourg	`LU`	VAT
Malaysia	`MY`	NRIC
Malta	`MT`	VAT
Mexico	`MX`	RFC
Monaco	`MC`	VAT
Netherlands	`NL`	BSN
New Zealand	`NZ`	IRD
Norway	`NO`	Fødselsnummer
Poland	`PL`	PESEL
Portugal	`PT`	NIF
Romania	`RO`	CNP
Russia	`RU`	INN
Serbia	`RS`	PIB
Slovakia	`SK`	Rodné číslo
Slovenia	`SI`	EMŠO
South Africa	`ZA`	TIN
South Korea	`KR`	RRN
Spain	`ES`	NIF / NIE
Sweden	`SE`	Personnummer
Switzerland	`CH`	AHV/AVS number
Thailand	`TH`	TIN
Turkey	`TR`	T.C. Kimlik No
Ukraine	`UA`	RNTRC
United Kingdom	`GB`	UTR (Unique Taxpayer Reference)
United States	`US`	TIN (SSN / ITIN / EIN)

What is not supported¶

Any country not in the table above returns unknown: the number is neither accepted nor rejected.
Countries showing VAT in the table (CY, GR, HU, LU, LV, MC, MT): no personal tax-number scheme is available, so a business VAT number is validated instead. A purely personal identifier for these countries will not be accepted.

Example¶

TIN_VALID('81872495633', 'DE')

Returns true, valid German IdNr.

TIN_VALID('11111111111', 'DE')

Returns false, fails the German check digit.

TIN_VALID('12345678Z', 'es')

Returns true, valid Spanish NIF (country code is case-insensitive).

TIN_VALID('12345678Z', 'JP')

Returns unknown, Japan is not in the supported list.

Example in context¶

p is Person
TIN_VALID(p.tax_number, p.country_of_residence) = false

Returns true only when the country is supported and the number is invalid, a safe condition for flagging a bad TIN without firing on countries that cannot be checked. Handle the unknown case separately if you want to warn that a country is unsupported.