FOfonoa
Lookup V2

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.

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.

Set max_retry_duration (in hours) to enable smart retries: Fonoa keeps retrying the validation while the government database is unavailable, for up to the given number of hours, instead of completing it with an error after the standard retry window.

post/lookup/v2/single-validations

Request

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

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

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.

max_retry_durationinteger

Enables smart retries. The maximum number of hours, counted from requested_at, during which Fonoa keeps retrying a validation that fails because the government database is unavailable.

A validation is retried while its online check ends with NETWORK_ERROR, TEMPORARY_UNAVAILABLE or UNKNOWN_RESPONSE. During this time the validation status stays pending, and the validation webhook is sent only when the validation completes. If no successful response is received before max_retry_duration expires, the validation completes with the error from the last attempt.

Smart retries are available for selected countries. For other countries the parameter is accepted, but the standard retry behavior applies.

When omitted, the standard retry behavior applies.

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,
  "max_retry_duration": 24
}

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"
}

Changes

  • 893d624efa51Revision changes
    • breaking

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

    • warning

      added the new AUTHENTICATION_ERROR enum value to the // response property for the response status

    • warning

      added the new AUTHENTICATION_ERROR enum value to the // response property for the response status

    • warning

      added the new AUTHENTICATION_ERROR enum value to the // response property for the response status

    • warning

      added the new BATCH_REQUEST_CANNOT_BE_EMPTY enum value to the // response property for the response status

    • warning

      added the new BATCH_REQUEST_CANNOT_BE_EMPTY enum value to the // response property for the response status

    • warning

      added the new BATCH_REQUEST_CANNOT_BE_EMPTY enum value to the // response property for the response status

    • warning

      added the new CANNOT_HAVE_MORE_THAN_X_RESULTS enum value to the // response property for the response status

    • warning

      added the new CANNOT_HAVE_MORE_THAN_X_RESULTS enum value to the // response property for the response status

    • warning

      added the new CANNOT_HAVE_MORE_THAN_X_RESULTS enum value to the // response property for the response status

    • warning

      added the new CANNOT_HAVE_MORE_THAN_X_SEARCHES enum value to the // response property for the response status

    • warning

      added the new CANNOT_HAVE_MORE_THAN_X_SEARCHES enum value to the // response property for the response status

    • warning

      added the new CANNOT_HAVE_MORE_THAN_X_SEARCHES enum value to the // response property for the response status

    • warning

      added the new CANNOT_HAVE_MORE_THAN_X_TINS enum value to the // response property for the response status

    • warning

      added the new CANNOT_HAVE_MORE_THAN_X_TINS enum value to the // response property for the response status

    • warning

      added the new CANNOT_HAVE_MORE_THAN_X_TINS enum value to the // response property for the response status

    • warning

      added the new CANNOT_HAVE_ZERO_ENTRIES enum value to the // response property for the response status

    • warning

      added the new CANNOT_HAVE_ZERO_ENTRIES enum value to the // response property for the response status

    • warning

      added the new CANNOT_HAVE_ZERO_ENTRIES enum value to the // response property for the response status

    • warning

      added the new CANNOT_REQUEST_MORE_THAN_X_RESULTS enum value to the // response property for the response status

    • warning

      added the new CANNOT_REQUEST_MORE_THAN_X_RESULTS enum value to the // response property for the response status

    • warning

      added the new CANNOT_REQUEST_MORE_THAN_X_RESULTS enum value to the // response property for the response status

    • warning

      added the new COUNTRIES_NOT_ALLOWED enum value to the // response property for the response status

    • warning

      added the new COUNTRIES_NOT_ALLOWED enum value to the // response property for the response status

    • warning

      added the new COUNTRIES_NOT_ALLOWED enum value to the // response property for the response status

    • warning

      added the new COUNTRY_NOT_SUPPORTED enum value to the // response property for the response status

    • warning

      added the new COUNTRY_NOT_SUPPORTED enum value to the // response property for the response status

    • warning

      added the new COUNTRY_NOT_SUPPORTED enum value to the // response property for the response status

    • warning

      added the new CSV_COLUMN_MISMATCH_ERROR enum value to the // response property for the response status

    • warning

      added the new CSV_COLUMN_MISMATCH_ERROR enum value to the // response property for the response status

    • warning

      added the new CSV_COLUMN_MISMATCH_ERROR enum value to the // response property for the response status

    • warning

      added the new CSV_COUNTRY_CODE_FORMAT_ERROR enum value to the // response property for the response status

    • warning

      added the new CSV_COUNTRY_CODE_FORMAT_ERROR enum value to the // response property for the response status

    • warning

      added the new CSV_COUNTRY_CODE_FORMAT_ERROR enum value to the // response property for the response status

    • warning

      added the new CSV_FILE_NOT_PROVIDED enum value to the // response property for the response status

    • warning

      added the new CSV_FILE_NOT_PROVIDED enum value to the // response property for the response status

    • warning

      added the new CSV_FILE_NOT_PROVIDED enum value to the // response property for the response status

    • warning

      added the new CSV_GENERIC_PARSING_ERROR enum value to the // response property for the response status

    • warning

      added the new CSV_GENERIC_PARSING_ERROR enum value to the // response property for the response status

    • warning

      added the new CSV_GENERIC_PARSING_ERROR enum value to the // response property for the response status

    • warning

      added the new CURSOR_PARSING_ERROR enum value to the // response property for the response status

    • warning

      added the new CURSOR_PARSING_ERROR enum value to the // response property for the response status

    • warning

      added the new CURSOR_PARSING_ERROR enum value to the // response property for the response status

    • warning

      added the new DIRECT_TAX_ID_NOT_SUPPORTED enum value to the // response property for the response status

    • warning

      added the new DIRECT_TAX_ID_NOT_SUPPORTED enum value to the // response property for the response status

    • warning

      added the new DIRECT_TAX_ID_NOT_SUPPORTED enum value to the // response property for the response status

    • warning

      added the new INTERNAL_ERROR enum value to the // response property for the response status

    • warning

      added the new INTERNAL_ERROR enum value to the // response property for the response status

    • warning

      added the new INTERNAL_ERROR enum value to the // response property for the response status

    • warning

      added the new INVALID_FIELD_FORMAT enum value to the // response property for the response status

    • warning

      added the new INVALID_FIELD_FORMAT enum value to the // response property for the response status

    • warning

      added the new INVALID_FIELD_FORMAT enum value to the // response property for the response status

    • warning

      added the new INVALID_ID_ERROR enum value to the // response property for the response status

    • warning

      added the new INVALID_ID_ERROR enum value to the // response property for the response status

    • warning

      added the new INVALID_ID_ERROR enum value to the // response property for the response status

    • warning

      added the new INVALID_MIME_ONLY_FORM_DATA_IS_VALID enum value to the // response property for the response status

    • warning

      added the new INVALID_MIME_ONLY_FORM_DATA_IS_VALID enum value to the // response property for the response status

    • warning

      added the new INVALID_MIME_ONLY_FORM_DATA_IS_VALID enum value to the // response property for the response status

    • warning

      added the new INVALID_MIME_ONLY_JSON_IS_VALID enum value to the // response property for the response status

    • warning

      added the new INVALID_MIME_ONLY_JSON_IS_VALID enum value to the // response property for the response status

    • warning

      added the new INVALID_MIME_ONLY_JSON_IS_VALID enum value to the // response property for the response status

    • warning

      added the new INVALID_REQUEST enum value to the // response property for the response status

    • warning

      added the new INVALID_REQUEST enum value to the // response property for the response status

    • warning

      added the new INVALID_REQUEST enum value to the // response property for the response status

    • warning

      added the new INVALID_VALIDATION_DATABASE_SOURCE enum value to the // response property for the response status

    • warning

      added the new INVALID_VALIDATION_DATABASE_SOURCE enum value to the // response property for the response status

    • warning

      added the new INVALID_VALIDATION_DATABASE_SOURCE enum value to the // response property for the response status

    • warning

      added the new MISSING_QUERY_OR_COUNTRY_ISO_CODE enum value to the // response property for the response status

    • warning

      added the new MISSING_QUERY_OR_COUNTRY_ISO_CODE enum value to the // response property for the response status

    • warning

      added the new MISSING_QUERY_OR_COUNTRY_ISO_CODE enum value to the // response property for the response status

    • warning

      added the new MISSING_TAX_IDENTIFICATION_NUMBER_OR_COUNTRY_ISO_CODE enum value to the // response property for the response status

    • warning

      added the new MISSING_TAX_IDENTIFICATION_NUMBER_OR_COUNTRY_ISO_CODE enum value to the // response property for the response status

    • warning

      added the new MISSING_TAX_IDENTIFICATION_NUMBER_OR_COUNTRY_ISO_CODE enum value to the // response property for the response status

    • warning

      added the new NO_BATCH_FOUND enum value to the // response property for the response status

    • warning

      added the new NO_BATCH_FOUND enum value to the // response property for the response status

    • warning

      added the new NO_BATCH_FOUND enum value to the // response property for the response status

    • warning

      added the new NO_VALIDATION_FOUND enum value to the // response property for the response status

    • warning

      added the new NO_VALIDATION_FOUND enum value to the // response property for the response status

    • warning

      added the new NO_VALIDATION_FOUND enum value to the // response property for the response status

    • warning

      added the new TAX_IDENTIFICATION_NUMBER_TYPE_NOT_SUPPORTED enum value to the // response property for the response status

    • warning

      added the new TAX_IDENTIFICATION_NUMBER_TYPE_NOT_SUPPORTED enum value to the // response property for the response status

    • warning

      added the new TAX_IDENTIFICATION_NUMBER_TYPE_NOT_SUPPORTED enum value to the // response property for the response status

    • warning

      added the new TIN_SEARCH_NOT_FOUND enum value to the // response property for the response status

    • warning

      added the new TIN_SEARCH_NOT_FOUND enum value to the // response property for the response status

    • warning

      added the new TIN_SEARCH_NOT_FOUND enum value to the // response property for the response status

    • warning

      added the new TIN_SEARCH_NOT_SUPPORTED_FOR_SUBSCRIPTION enum value to the // response property for the response status

    • warning

      added the new TIN_SEARCH_NOT_SUPPORTED_FOR_SUBSCRIPTION enum value to the // response property for the response status

    • warning

      added the new TIN_SEARCH_NOT_SUPPORTED_FOR_SUBSCRIPTION enum value to the // response property for the response status

    • warning

      added the new TIN_SEARCH_QUERY_LENGTH_INVALID enum value to the // response property for the response status

    • warning

      added the new TIN_SEARCH_QUERY_LENGTH_INVALID enum value to the // response property for the response status

    • warning

      added the new TIN_SEARCH_QUERY_LENGTH_INVALID enum value to the // response property for the response status

    • warning

      added the new TIN_SEARCH_WORD_COUNT_INVALID enum value to the // response property for the response status

    • warning

      added the new TIN_SEARCH_WORD_COUNT_INVALID enum value to the // response property for the response status

    • warning

      added the new TIN_SEARCH_WORD_COUNT_INVALID enum value to the // response property for the response status

    • warning

      added the new UNSUPPORTED_CSV_COLUMNS enum value to the // response property for the response status

    • warning

      added the new UNSUPPORTED_CSV_COLUMNS enum value to the // response property for the response status

    • warning

      added the new UNSUPPORTED_CSV_COLUMNS enum value to the // response property for the response status

    • warning

      added the new UNSUPPORTED_PARAMETER_ERROR enum value to the // response property for the response status

    • warning

      added the new UNSUPPORTED_PARAMETER_ERROR enum value to the // response property for the response status

    • warning

      added the new UNSUPPORTED_PARAMETER_ERROR enum value to the // response property for the response status

    • warning

      added the new US_BOTH_FIRST_LAST_NAME_REQUIRED enum value to the // response property for the response status

    • warning

      added the new US_BOTH_FIRST_LAST_NAME_REQUIRED enum value to the // response property for the response status

    • warning

      added the new US_BOTH_FIRST_LAST_NAME_REQUIRED enum value to the // response property for the response status

    • warning

      added the new US_UNSUPPORTED_PARAMETER_FOR_BUSINESS enum value to the // response property for the response status

    • warning

      added the new US_UNSUPPORTED_PARAMETER_FOR_BUSINESS enum value to the // response property for the response status

    • warning

      added the new US_UNSUPPORTED_PARAMETER_FOR_BUSINESS enum value to the // response property for the response status

    • warning

      added the new US_UNSUPPORTED_PARAMETER_FOR_INDIVIDUAL enum value to the // response property for the response status

    • warning

      added the new US_UNSUPPORTED_PARAMETER_FOR_INDIVIDUAL enum value to the // response property for the response status

    • warning

      added the new US_UNSUPPORTED_PARAMETER_FOR_INDIVIDUAL enum value to the // response property for the response status

    • warning

      added the new VALIDATIONS_AMOUNT_EXCEEDED enum value to the // response property for the response status

    • warning

      added the new VALIDATIONS_AMOUNT_EXCEEDED enum value to the // response property for the response status

    • warning

      added the new VALIDATIONS_AMOUNT_EXCEEDED enum value to the // response property for the response status

    • warning

      added the new VALIDATION_SOURCE_NOT_SUPPORTED_FOR_COUNTRY enum value to the // response property for the response status

    • warning

      added the new VALIDATION_SOURCE_NOT_SUPPORTED_FOR_COUNTRY enum value to the // response property for the response status

    • warning

      added the new VALIDATION_SOURCE_NOT_SUPPORTED_FOR_COUNTRY enum value to the // response property for the response status

    • info

      added the new optional request property

    • 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

    • info

      added the media type application/json for the response with the status