FOfonoa
Lookup V1

Request a validation

Changed on

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

  • Base URL
    https://api-demo.fonoa.com
  • URL
    https://api-demo.fonoa.com/lookup/v1/validations
  • Auth
    API key in header Ocp-Apim-Subscription-Key

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' | 'im' | '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' | 'nc' | 'ng' | 'nl' | 'no' | 'np' | 'nz' | 'om' | 'pa' | 'pe' | 'ph' | 'pk' | 'pl' | 'pt' | 'py' | 'ro' | 'rs' | 're' | '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."
    }
  }
}

Changes

  • 893d624efa51Revision changes
    • breaking

      removed the enum value lv - ma - mc - md of the request property

    • warning

      added the new Aquis. Intracom. por Opção enum value to the // response property for the response status

    • warning

      added the new Aquis. Intracom. por Opção enum value to the // response property for the response status

    • info

      added the new im enum value to the request property

    • info

      added the new lv enum value to the request property

    • info

      added the new ma enum value to the request property

    • info

      added the new mc enum value to the request property

    • info

      added the new md enum value to the request property

    • info

      added the new nc enum value to the request property

    • info

      added the new re enum value to the request property