Sign in

v1

latestOpenAPI 3.0.02026-07-2436163302.7 KB
Lookup V2

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.

Set prefer_cached_result to true to attempt returning a result from the Instant Lookup cache before running a new online validation. This requires the Instant Lookup product entitlement on your account.

post/lookup/v2/single-validations

Request body

country_iso_code'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)

tax_identification_numberstring required

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

tax_identification_number_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.

validation_database_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.

prefer_cached_resultboolean

When set to true, Fonoa will first attempt to return a cached validation result from the Instant Lookup database instead of running an online validation.

This feature requires your account to have the Instant Lookup product entitlement. If your account has country restrictions for Instant Lookup, the requested country_iso_code must be within your allowed countries.

The TIN must pass format and checksum validation before a cache lookup is attempted. When a cached result is found, the validation completes immediately with validation_database_source set to fonoa_cache and includes the cached taxpayer data. If no cached result is available, the request proceeds with the standard validation flow.

When omitted or set to false, the standard online validation flow is used and no cache lookup is performed.

Example request

{
  "country_iso_code": "ee",
  "tax_identification_number": "100070008",
  "additional_parameters": {
    "egypt_uin": "10000010066d9770abe966h4vk7H9oj0cd7c8a8",
    "malaysia_id_type": "brn",
    "malaysia_id_value": "X19510100011",
    "nigeria_brn": "1234567"
  },
  "fuzzy_matching": {
    "name": "expected taxpayer name",
    "address": "expected taxpayer address"
  },
  "prefer_cached_result": true
}

Response

An immediate response is returned in the following cases:

  • Format or checksum invalid: the TIN did not pass offline format/checksum validation, so no online lookup is performed. The response contains error_details.
  • Format valid but no online check supported: the TIN passed offline format/checksum validation, but no online lookup is performed.
  • Instant Lookup cache hit: when prefer_cached_result is true and a cached result is found, the validation completes immediately with validation_database_source set to fonoa_cache and includes enriched taxpayer data.
status'completed' required
validation_result_urlstring uri required

Example response

{
  "validation": {
    "validation_id": "b470a195-8e83-4d89-b4a7-4d389ac358a4",
    "tax_identification_number": "100070008",
    "country_iso_code": "cl",
    "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.",
      "italy_codice_fiscale_status": "Codice Fiscale valid",
      "italy_vat_split_payment": "no",
      "brazil_status_detail": "Active",
      "brazil_cnae_code": "6201500",
      "brazil_cnae_description": "Desenvolvimento de programas de computador sob encomenda",
      "brazil_secondary_cnaes": [
        {
          "code": "6202300",
          "description": "Desenvolvimento e licenciamento de programas de computador customizaveis"
        }
      ],
      "brazil_municipality": "SAO PAULO",
      "brazil_federal_state": "SP",
      "brazil_neighborhood": "VILA OLIMPIA",
      "brazil_company_size": "Demais",
      "brazil_special_status": "Recuperacao Judicial",
      "brazil_special_status_date": "2023-01-15",
      "brazil_date_of_birth": "1985-03-20",
      "brazil_year_of_death": "2020",
      "brazil_suframa": {
        "number": "123456789",
        "status": "ACTIVE",
        "registration_date": "2020-01-15"
      },
      "brazil_state_registrations": [
        {
          "number": "123456789",
          "federal_state": "SP",
          "enabled": true,
          "registration_date": "2019-05-10",
          "status": "NO_RESTRICTION",
          "type": "IE_NORMAL"
        }
      ],
      "brazil_simples": {
        "optant": "yes"
      },
      "company_representative_name": "John Doe",
      "brazil_status_reason": "Sem motivo",
      "brazil_status_date": "2019-01-01",
      "brazil_address": {
        "street": "RUA EXEMPLO",
        "number": "123",
        "additional_info": "SALA 456",
        "neighborhood": "VILA OLIMPIA",
        "city": "SAO PAULO",
        "state": "SP",
        "postal_code": "04551065",
        "country": "BRASIL",
        "country_code": "076",
        "city_code": "7107"
      },
      "brazil_legal_nature_code": "206-2",
      "brazil_entity_social_capital": "100000000",
      "brazil_email": "contato@empresa.com.br",
      "business_activities": [
        {
          "activity": "ACTIVIDADES DE CONSULTORIA DE INFORMATICA Y DE GESTION DE INSTALACIONE",
          "code": "620200",
          "category": "Primera",
          "subject_to_vat": "yes",
          "registration_date": "05-10-2015"
        }
      ]
    },
    "additional_parameters": {
      "egypt_uin": "10000010066d9770abe966h4vk7H9oj0cd7c8a8",
      "malaysia_id_type": "brn",
      "malaysia_id_value": "X19510100011",
      "nigeria_brn": "1234567"
    },
    "name": "ACME CO.",
    "address": "Tower A DLF Tower, 4th Floor, DLF INFINTY TOWER, Sector 25A, Gurugram, Haryana, 122002",
    "registration_type": "Regular",
    "registration_date": "2017-07-20",
    "de_registration_date": "2017-07-20",
    "tax_identification_number_name": "Système d’Identification du Répertoire des Entreprises (SIREN)",
    "last_updated": "2026-03-05T08:00:00.000Z",
    "country_specific": {
      "fantasy_name": "Example Corp"
    }
  },
  "validation_result_url": "https://api-demo.fonoa.com/lookup/v2/single-validations/b470a195-8e83-4d89-b4a7-4d389ac358a4"
}