FOfonoa
Lookup V2

Request a batch validation

Changed on

This endpoint allows you to request a batch of TINs to be validated. In order to do so, our system needs a country where relevant TINs are registered (ISO code) and the TIN data. You can have multiple countries in the request, for eg. 50 Hungarian TINs and 120 Mexican TINs.

Set max_retry_duration (in hours) to enable smart retries for every validation in the batch: Fonoa keeps retrying each 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/batch-validations

Request

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

Request body

batch_namestring
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

{
  "batch_name": "batch-2022-12-25-09-07-54",
  "max_retry_duration": 24,
  "tax_identification_number_requests": [
    {
      "country_iso_code": "ee",
      "tax_identification_numbers": [
        "EE102360282, EE101757663, EE100210457, EE102019944, EE101279099"
      ],
      "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"
      }
    }
  ]
}

Response

This is an immediate response for validations and provides details whether the format were invalid, status or error details (no background processing needed). The 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.

batch_idstring required
batch_namestring required
requested_atstring date-time required
status'completed' required
batch_validation_result_urlstring uri required

Example response

{
  "validations": [
    {
      "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"
      }
    }
  ]
}

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