The OpenTIN API is available through three different interfaces. Select the one that matches the product you subscribed to.
Not sure which interface to choose? See the interface comparison table.
boto3 / Amazon.DataExchange) via send_api_asset{region}.opentin-api.open-automation.ioazure.opentin-api.open-automation.ioResponse samples
{
"tin_valid": 0,
"message": "string",
"ctry_spec_ver": "string",
"ctry_spec_chk_dt": "string"
}
Download OpenAPI specification: Download
This API allows to validate a TIN number against OECD specifications
Germany issues no TIN to entities. The tax number (Steuernummer) is used instead, and that is what /tin_validate/DE/E/{tin} validates. The request and the response format are the same as for any other country; there is no extra parameter.
Land-named (recommended): put the issuing Land in front of the number, separated by a hyphen. This is the same convention the Global Biz Verify API uses for US states (NY-{number}).
/tin_validate/DE/E/BW-6681508156
Bare: the number alone, as printed on a tax office letter (10 or 11 digits) or in the 13-digit ELSTER format.
/tin_validate/DE/E/6681508156 /tin_validate/DE/E/19881508152 /tin_validate/DE/E/2866081508156
A tax number as printed does not say which Land issued it. With the Land named, the number is checked against that Land only. Without it, the number is accepted if it is valid for any Land.
The difference is measurable. Share of 20,000 random digit strings that the API accepts, per input form:
So "tin_valid": 1 on a bare 10-digit number means "some German Land could have issued this number", not "this number exists". Naming the Land is the one thing a client can do to make the answer stronger. It also catches a number attributed to the wrong Land: BW-19881508152 is a Bayern number claimed as Baden-Württemberg, and is rejected.
BW BY BE BB HB HH HE MV NI NW RP SL SN ST SH TH. NRW is accepted as well as NW.bw-6681508156 works.66815/08156, BW-66815/08156 and 198/815/08152 are all accepted.DE123456789: a VAT number (USt-IdNr) or the new business identification number (W-IdNr), not a tax number. Response: "Error: the TIN has invalid lenght for the specified country"HRB123456: a commercial register (Handelsregister) number, not a tax number. Response: "Error: the TIN has invalid lenght for the specified country"286608150815: 12 digits is not a valid length for a tax number. Response: "Error: the TIN's format is invalid for the specified country"XX-6681508156: not a German Land code. Response: "Error: the TIN's format is invalid for the specified country"BW-19881508152: a valid Bayern number, but not for the Land named. There is no separate wrong-Land message; the response is the same as for a wrong check digit: "Error: the TIN's checksum is invalid for the specified country"The spelling lenght is the exact text the API returns, for every country. If you compare message strings, compare against it as shown.
-"Invalid request syntax, please check the documentation" # The API didn't understand your request at all - "The country code must be a valid ISO 3166-1 Alpha-2 OR Alpha-3 code" # The country code must be 2 or 3 characters long and from the ISO 3166-1 standard - "Error: the parameter 'entity_type' must be either I for individuals or E for entities" - "The type of the TIN number must be either E for entities or I for individuals" # The entity type can be only "I" for Individuals (physical persons) or "E" for Entities (Companies) - "Internal TIN validation error" # The API unexpedly crashed - "Error: Unsupported ISO3 country code" - "Error: Unsupported ISO2 country code" # The TIN validation for this country is not yet implemented (contact our support if you encounter this rare case) - "Error: Invalid ISO2 country code" # The country you specified using a ISO2 code is not part of the 3166-1 standard - "Error: the parameter 'tin' is mandatory" # The TIN parameter was not found in the request - "Error: the parameter 'entity_type' is mandatory" # The "entity_type" parameter was not found in the request - "Error: The TIN length is invalid" # The number you provided doesn't seem to be long enough to be a valid TIN - "This country is not a member of OECD" # The provided country isn't participating in the OECD CRS initiative - "This country does not use TINs" # This country doesn't have any equivalent of Tax Identification Numbers - "No validation available for this type of entity for this country" # All implemented countries there is a validation available for Individuals # For certain countries a validation for Entities is also available - "Error: the TIN has invalid length for the specified country" # The length of the TIN number is not valid for the specified country - "Error: the TIN's format is invalid for the specified country" # The format of the TIN doesn't follow the official specification for this country - "Error: the TIN's checksum is invalid for the specified country" # The vast majority of countries use complex checksum algorithms to ensure the TIN number is valid. This test failed for the provided TIN/country pair - "Error: the TIN's structure is invalid for the specified country" # The rules for the structure of the TIN failed for the provided TIN/country pair - "Error: Unsupported checksum type" # Internal error that should never be seen by the API users - "The TIN is valid" # The message that we want to see the most! The TIN passed all the available structure checks