v1

latestOpenAPI 3.0.02026-07-2436163302.7 KB

Lookup V1

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.

post/lookup/v1/validations

Request body

country_iso'ae' | 'af' | 'al' | 'am' | 'ao' | 'ar' | 'at' | 'au' | 'az' | 'ba' | 'bd' | 'be' | 'bf' | 'bg' | 'bh' | 'bi' | 'bj' | 'bo' | 'br' | 'by' | 'ca' | 'cg' | 'ch' | 'ci' | 'cl' | 'cm' | 'cn' | 'co' | 'cr' | 'cv' | 'cy' | 'cz' | 'de' | 'dk' | 'do' | 'ec' | 'ee' | 'eg' | 'el' | 'es' | 'fi' | 'fr' | 'gb' | 'ge' | 'gh' | 'gr' | 'gt' | 'hk' | 'hn' | 'hr' | 'hu' | 'id' | 'ie' | 'il' | 'in' | 'is' | 'it' | 'jm' | 'jo' | 'jp' | 'ke' | 'kg' | 'kh' | 'kr' | 'kz' | 'li' | 'lt' | 'lu' | 'lv - ma - mc - md' | 'me' | 'mk' | 'mm' | 'mt' | 'mv' | 'mx' | 'my' | 'ng' | 'nl' | 'no' | 'np' | 'nz' | 'om' | 'pa' | 'pe' | 'ph' | 'pk' | 'pl' | 'pt' | 'py' | 'ro' | 'rs' | 'ru' | 'sa' | 'sc' | 'se' | 'sg' | 'si' | 'sk' | 'sn' | 'sr' | 'tg' | 'th' | 'tr' | 'tw' | 'tz' | 'ua' | 'ug' | 'us' | 'uy' | 've' | 'vn' | 'xi' | 'xk' | 'za' | 'zm' | 'zw' 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)

tinstring required

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

tin_type'individual' | 'business'

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.

check_tin_onlineboolean

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.

cache_age_secondsinteger

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.

validation_source'vies' | 'local'

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 the TIN cannot be identified in VIES. If VIES is temporarily unavailable and unable to provide a result, Fonoa will also fall back to the local database.

external_idstring

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.

Example request

{
  "country_iso": "ee",
  "tin": "100070008",
  "check_tin_online": true,
  "fuzzy_matching": {
    "taxpayer": {
      "name": "expected taxpayer name",
      "address": "expected taxpayer address"
    }
  }
}

Response

The validation results were fetched from cache and you can read them immediately. This response will also be returned if you provide a TIN number that has invalid format or checksum digit(s), the response will provide details whether the format or/and checksum digit(s) were invalid.

status'completed' required

Example response

{
  "validation": {
    "tin": "100070008",
    "country_iso": "cl",
    "error_code": 1,
    "company_name": "ACME",
    "taxpayer": {
      "registration_date": "2017-07-20",
      "deregistration_date": "2017-07-20",
      "address": "Tower A DLF Tower, 4th Floor, DLF INFINTY TOWER, Sector 25A, Gurugram, Haryana, 122002"
    },
    "extra_fields": {
      "brazil_fantasy_name": "BAR E LANCHES 111",
      "canada_federal_state": "Federal",
      "colombia_check_digit": "9",
      "colombia_large_taxpayer": "yes",
      "colombia_tin_without_check_digit": "123456789",
      "egypt_uin_expiry_date": "2010-10-10",
      "germany_federal_state": "Berlin",
      "hungary_full_tax_identification_number": "13353298-2-44",
      "india_pan_aadhaar_linked": "not_applicable",
      "india_pan_specified_person": "no",
      "india_trade_name": "ACME TRADE",
      "japan_qualified_invoice_issuer": "yes",
      "mexico_zip_code_used_for_validation": "12345",
      "usa_irs_response": "TIN and Name combination does not match IRS records."
    }
  }
}