API Documentation

TIN Validation Request

A standard TIN validation request consists of four things:

  • Your API key
  • The tax ID number (TIN) to validate
  • An IRS country code or ISO country code (but not both)
  • A TIN type ("individual", "entity", or "vat")

Here's an example API request. Spaces are included in the following examples for readability, but you would make this request with no spaces.

  ? key = YOUR_API_KEY
  & tin = 123456782
  & irs_code = AS
  & tin_type = individual

The key should be kept secret like a password. Anyone with the API key can submit requests to the API, which will count towards your request limit for the period. If you suspect that your key has been compromised, you can easily reset it by visiting your API settings.

The tin may contain numbers and letters (uppercase or lowercase) dashes, underscores, and other special characters. Any character that is not a number or letter will be automatically removed during the validation process. Note that certain characters are not URL safe, and may cause http errors, so with the exception of dashes and underscores, we recommend cleaning your TIN prior to sending the request.

The irs_code or iso_code parameter should specify a two-letter country code in respective IRS or ISO country code format. Note that only one of the two formats should be used. See a complete listing of IRS country codes or ISO country codes for reference.

The tin_type should specify "individual", "entity", or "vat". If not set, this will default to "individual".

TIN Validation Response

The response is an easily parseable JSON object consisting of the following objects and properties:

"success": true,
"results": {
  "valid": true,
  "country": "Australia",
  "irs_code": "AS",
  "iso_code": "AU",
  "tin_type": "individual",
  "tin_name": "Tax File Number (TFN)"
  "test_type": "advanced",
  "tin": "123456782"

The success property indicates whether or not the query itself was successful.

The results object contains the results of the validation test, along with some other useful information:

  • valid: Indicates whether or not the TIN is valid for the country specified.
  • country: The full name of the country specified.
  • irs_code: The IRS code is included whether or not it was provided.
  • iso_code: The ISO code is included whether or not it was provided.
  • tin_type: The TIN type specified with the request.
  • test_type: The test difficulty (see below).
  • clean: A clean version of the TIN, with special characters removed.

Test Difficulty

The basic test matches the TIN to a known pattern. Patterns can be very forgiving in some cases, and very strict in others. Pattern rules depend on the issuing country.

The advanced test is available for certain countries who incorporate check digits into their TINs. The advanced test uses an algorithm to confirm check digits, which provides additional assurance that the TIN is valid. If the advanced test is available for a given country, it is automatically applied. You do not need to specify whether or not you would like to use the advanced test. The test type is returned along with your results.