Request a validation

This endpoint allows you to request a validation of the Tax Identification Number. In order to do so, our system needs a country of the client (ISO code) and a tax identification number of the client.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
enum
required

Country code in ISO 3166-1 alpha-2 format of the company whose TIN is being validated (e.g., au for Australia, hr for Croatia)

string
required

Tax Identification Number (VAT ID, GST ID, etc.) expressed as a string

string
enum

This field allows you to state whether the tax identification number provided belongs to an individual or a business so we can run the appropriate validation.

This field is not yet supported for all countries.

Allowed:
boolean
Defaults to true

Whether TIN should be checked in real-time against a local government database that stores TINs. If you put this to false, then only the validation of the format and the number structure will be performed.

additional_parameters
array of objects

A list of additional parameters that can or need to be provided in particular countries.

Each item is an object consisting of two properties: name - which is the name of the parameters, and value - which holds a value of additional parameters.

Current supported usage per country:

Canada (CA): taxpayer_name optional, date optional, canada_bc_pst optional - In case you are validating PST numbers in CA-British Columbia, you need to provide both the taxpayer's Business Number as tin (9 digits), and PST number (8 digits);

China (CN): taxpayer_name required to check an individual tin_type - full personal name in Chinese is required for national ID validation

Croatia (HR): date optional;

Egypt (EG): egypt_uin optional - The UIN is a 39-character mixed format identifier which is required for Egyptian tax ID validation;

India (IN): india_state_name optional - Used for validating whether the GSTIN corresponds to the relevant state where the taxpayer is based. Allowed values: "Jammu & Kashmir", "Himachal Pradesh", "Punjab", "Chandigarh", "Uttarakhand", "Haryana", "Delhi", "Rajasthan", "Uttar Pradesh", "Bihar", "Sikkim", "Arunachal Pradesh", "Nagaland", "Manipur", "Mizoram", "Tripura", "Meghalaya", "Assam", "West Bengal", "Jharkhand", "Odisha", "Chhattisgarh", "Madhya Pradesh", "Gujarat", "Dadra and Nagar Haveli and Daman and Diu", "Maharashtra", "Karnataka", "Goa", "Lakshadweep", "Kerala", "Tamil Nadu", "Puducherry", "Andaman and Nicobar", "Telangana", "Andhra Pradesh", "Ladakh", name optional - Taxpayer's name can be provided in PAN validations to check 100% matching of the name with official database. The result will contain india_pan_name_match field in extra_fields, date optional - Date of birth can be provided in PAN validations to check matching with official database. The result will contain india_pan_date_match field in extra_fields;

Lithuania (LT): taxpayer_name optional;

Mexico (MX); taxpayer_name optional, zip_code optional;

Poland (PL): date optional;

Spain (ES): taxpayer_name optional;

Turkey (TR): tax_office optional, province optional for validation in government database with the full list, these fields are required, however, the request will proceed and be tried without them to see if tax id can be found in alternative government databases without the full list..

United States of America (US): taxpayer_name required to check Employer Identification Number (EIN) or first_name, last_name required to check an individual tin_type (Social Security Number)

additional_parameters
integer
0 to 15552000
Defaults to 0

If the TIN number has been validated by Fonoa before, we store the latest result in cache (up to 180 days). The optional parameter accepts the number of seconds indicating for how long we should look backwards for the cached result. For example, if you are comfortable with the cache results up to 1 week old from now, then specify 604800 as the value. If set to 0 (default), no cache is checked for previous results.

string
enum

When you are validating EU TINs, you can specify the validation source in the request. This will allow you to decide whether you would like Fonoa to validate TIN in VIES or in the local government database in a given EU country. If no source was requested, then Fonoa will by default first check VIES, and then the local database in case if TIN is not identified in VIES. Note that the following countries do not have local implementation available:

cy, de, fr, ie, lu, mt, nl, se.

Allowed:
fuzzy_matching
object

Fuzzy matching compares expected data with actual values to provide you with a similarity score in the form of a percentage. You can input either or both the expected taxpayer name and address. Examples:

  • expected name "Fonoa Technologies" and actual "FONOA TECHNOLOGIES LIMITED" will produce "similarity_percentage": 100
  • expected address "12 Wildflower way Belfast" and actual "UNIT 5, 12 WILDFLOWER WAY, BELFAST, BT12 6TA" will produce "similarity_percentage": 76

Fuzzy matching uses transliteration to the Latin alphabet before running the algorithm, for example:

  • expected name "Lukoil" and actual "ПУБЛИЧНОЕ АКЦИОНЕРНОЕ ОБЩЕСТВО \"НЕФТЯНАЯ КОМПАНИЯ \"ЛУКОЙЛ\"" will produce "similarity_percentage": 83 based on the transliteration of the actual name into the Latin alphabet
string
length ≥ 1

An additional reference identifier you can provide - typically, the identifier used in your own system. You can use this to match results back to your own data.

Responses

401

Unauthorized

Language
Credentials
Header
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json