---
title: "Request a batch validation"
method: POST
path: "/lookup/v1/validations/batches"
tags: ["Lookup V1"]
---

# Request a batch validation

`POST /lookup/v1/validations/batches`

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.

## Request body

- object
  - `tin_requests` object[], required
    - `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)
    - `tins` string[], required — List of Tax Identification Numbers (VAT ID, GST ID, etc.) expressed as a strings
    - `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.
    - `additional_parameters` object[] — A list of additional parameters that can or need to be provided in particular countries. Each item is an object consisting of two properties: name - which is the name of the parameters, and value - which holds a value of additional parameters. Current supported usage per country: Canada (CA): `taxpayer_name` *optional*, `date` *optional*, `canada_bc_pst` *optional* - In case you are validating PST numbers in CA-British Columbia, you need to provide both the taxpayer's Business Number as `tin` (9 digits), and PST number (8 digits); China (CN): `taxpayer_name` *required* to check an `individual` `tin_type` - full personal name in Chinese is required for national ID validation Croatia (HR): `date` *optional*; Egypt (EG): `egypt_uin` *optional* - The UIN is a 39-character mixed format identifier which is required for Egyptian tax ID validation; India (IN): `india_state_name` *optional* - Used for validating whether the GSTIN corresponds to the relevant state where the taxpayer is based. Allowed values: `"Jammu & Kashmir"`, `"Himachal Pradesh"`, `"Punjab"`, `"Chandigarh"`, `"Uttarakhand"`, `"Haryana"`, `"Delhi"`, `"Rajasthan"`, `"Uttar Pradesh"`, `"Bihar"`, `"Sikkim"`, `"Arunachal Pradesh"`, `"Nagaland"`, `"Manipur"`, `"Mizoram"`, `"Tripura"`, `"Meghalaya"`, `"Assam"`, `"West Bengal"`, `"Jharkhand"`, `"Odisha"`, `"Chhattisgarh"`, `"Madhya Pradesh"`, `"Gujarat"`, `"Dadra and Nagar Haveli and Daman and Diu"`, `"Maharashtra"`, `"Karnataka"`, `"Goa"`, `"Lakshadweep"`, `"Kerala"`, `"Tamil Nadu"`, `"Puducherry"`, `"Andaman and Nicobar"`, `"Telangana"`, `"Andhra Pradesh"`, `"Ladakh"`, `name` *optional* - Taxpayer's name can be provided in PAN validations to check 100% matching of the name with official database. The result will contain `india_pan_name_match` field in `extra_fields`, `date` *optional* - Date of birth can be provided in PAN validations to check matching with official database. The result will contain `india_pan_date_match` field in `extra_fields`; Lithuania (LT): `taxpayer_name` *optional*; Mexico (MX); `taxpayer_name` *optional*, `zip_code` *optional*; Poland (PL): `date` *optional*; Spain (ES): `taxpayer_name` *optional*; Turkey (TR): `tax_office` *optional*, `province` *optional* for validation in government database with the full list, these fields are required, however, the request will proceed and be tried without them to see if tax id can be found in alternative government databases without the full list.. United States of America (US): `taxpayer_name` *required* to check Employer Identification Number (EIN) or `first_name`, `last_name` *required* to check an `individual` `tin_type` (Social Security Number)
      - `name` 'tax_office' | 'province' | 'taxpayer_name' | 'date' | 'zip_code' | 'canada_bc_pst' | 'first_name' | 'last_name' | 'india_state_name' | 'egypt_uin', required — Name of the parameter
      - `value` string, required — A value of the parameter
    - `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.
    - `fuzzy_matching` LookupFuzzyMatchingRequestV1 — Fuzzy matching compares expected data with actual values to provide you with a similarity score in the form of a percentage. You can input either or both the expected taxpayer name and address. Examples: - expected name `"Fonoa Technologies"` and actual `"FONOA TECHNOLOGIES LIMITED"` will produce `"similarity_percentage": 100` - expected address `"12 Wildflower way Belfast"` and actual `"UNIT 5, 12 WILDFLOWER WAY, BELFAST, BT12 6TA"` will produce `"similarity_percentage": 76` Fuzzy matching uses transliteration to the Latin alphabet before running the algorithm, for example: - expected name `"Lukoil"` and actual `"ПУБЛИЧНОЕ АКЦИОНЕРНОЕ ОБЩЕСТВО \"НЕФТЯНАЯ КОМПАНИЯ \"ЛУКОЙЛ\""` will produce `"similarity_percentage": 83` based on the transliteration of the actual name into the Latin alphabet
      - `taxpayer` object, required
        - `name` string — expected taxpayer name
        - `address` string — expected taxpayer address
    - `external_id` string — 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.
  - `check_tin_online` boolean — Whether TINs 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.

## Response `200`

The validation process has started and you need to fetch the results from a resource provided in the response.
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.

- object
  - `batch_id` string, required
  - `validations` object[], required
    - `id` string, required
    - `tin` string, required — Tax Identification Number (VAT ID, GST ID, etc.) expressed as a string
    - `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)
    - `format_valid` boolean, required
    - `checksum_valid` boolean
    - `additional_parameters` object[] — A list of additional parameters that can or need to be provided in particular countries. Each item is an object consisting of two properties: name - which is the name of the parameters, and value - which holds a value of additional parameters. Current supported usage per country: Canada (CA): `taxpayer_name` *optional*, `date` *optional*, `canada_bc_pst` *optional* - In case you are validating PST numbers in CA-British Columbia, you need to provide both the taxpayer's Business Number as `tin` (9 digits), and PST number (8 digits); China (CN): `taxpayer_name` *required* to check an `individual` `tin_type` - full personal name in Chinese is required for national ID validation Croatia (HR): `date` *optional*; Egypt (EG): `egypt_uin` *optional* - The UIN is a 39-character mixed format identifier which is required for Egyptian tax ID validation; India (IN): `india_state_name` *optional* - Used for validating whether the GSTIN corresponds to the relevant state where the taxpayer is based. Allowed values: `"Jammu & Kashmir"`, `"Himachal Pradesh"`, `"Punjab"`, `"Chandigarh"`, `"Uttarakhand"`, `"Haryana"`, `"Delhi"`, `"Rajasthan"`, `"Uttar Pradesh"`, `"Bihar"`, `"Sikkim"`, `"Arunachal Pradesh"`, `"Nagaland"`, `"Manipur"`, `"Mizoram"`, `"Tripura"`, `"Meghalaya"`, `"Assam"`, `"West Bengal"`, `"Jharkhand"`, `"Odisha"`, `"Chhattisgarh"`, `"Madhya Pradesh"`, `"Gujarat"`, `"Dadra and Nagar Haveli and Daman and Diu"`, `"Maharashtra"`, `"Karnataka"`, `"Goa"`, `"Lakshadweep"`, `"Kerala"`, `"Tamil Nadu"`, `"Puducherry"`, `"Andaman and Nicobar"`, `"Telangana"`, `"Andhra Pradesh"`, `"Ladakh"`, `name` *optional* - Taxpayer's name can be provided in PAN validations to check 100% matching of the name with official database. The result will contain `india_pan_name_match` field in `extra_fields`, `date` *optional* - Date of birth can be provided in PAN validations to check matching with official database. The result will contain `india_pan_date_match` field in `extra_fields`; Lithuania (LT): `taxpayer_name` *optional*; Mexico (MX); `taxpayer_name` *optional*, `zip_code` *optional*; Poland (PL): `date` *optional*; Spain (ES): `taxpayer_name` *optional*; Turkey (TR): `tax_office` *optional*, `province` *optional* for validation in government database with the full list, these fields are required, however, the request will proceed and be tried without them to see if tax id can be found in alternative government databases without the full list.. United States of America (US): `taxpayer_name` *required* to check Employer Identification Number (EIN) or `first_name`, `last_name` *required* to check an `individual` `tin_type` (Social Security Number)
      - `name` 'tax_office' | 'province' | 'taxpayer_name' | 'date' | 'zip_code' | 'canada_bc_pst' | 'first_name' | 'last_name' | 'india_state_name' | 'egypt_uin', required — Name of the parameter
      - `value` string, required — A value of the parameter
    - `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.
    - `type` 'business' | 'individual' — Specifies whether the taxpayer is an individual, or a legal entity.
    - `external_id` string — 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.
    - `fuzzy_matching` LookupFuzzyMatchingRequestV1 — Fuzzy matching compares expected data with actual values to provide you with a similarity score in the form of a percentage. You can input either or both the expected taxpayer name and address. Examples: - expected name `"Fonoa Technologies"` and actual `"FONOA TECHNOLOGIES LIMITED"` will produce `"similarity_percentage": 100` - expected address `"12 Wildflower way Belfast"` and actual `"UNIT 5, 12 WILDFLOWER WAY, BELFAST, BT12 6TA"` will produce `"similarity_percentage": 76` Fuzzy matching uses transliteration to the Latin alphabet before running the algorithm, for example: - expected name `"Lukoil"` and actual `"ПУБЛИЧНОЕ АКЦИОНЕРНОЕ ОБЩЕСТВО \"НЕФТЯНАЯ КОМПАНИЯ \"ЛУКОЙЛ\""` will produce `"similarity_percentage": 83` based on the transliteration of the actual name into the Latin alphabet
      - `taxpayer` object, required
        - `name` string — expected taxpayer name
        - `address` string — expected taxpayer address
    - `extra_fields` LookupExtraFieldsV1 — Contains country-specific fields (API V1).
      - `brazil_fantasy_name` string — This optional field indicates the trade name of a given business in Brazil. It can be different than the official entity name that is otherwise used in government registries and used on official legal documents, etc.
      - `canada_federal_state` string — This optional field indicates the Canada federal state (ex. Quebec).
      - `colombia_check_digit` string — This optional field represents check digit for the provided tax identification number.
      - `colombia_large_taxpayer` 'yes' | 'no' — This field indicates whether the validated TIN belongs to a company that has been included in the Colombian Tax Authority’s list of Large Taxpayers (Grandes Contribuyentes).
      - `colombia_tin_without_check_digit` string — This optional field represents tax identification number without last check digit.
      - `egypt_uin_expiry_date` string — It provides UIN expiry date in 'YYYY-MM-DD' format for Egyptian tax ID validation.
      - `germany_federal_state` string — This optional field indicates the Germany Federal State based on STNR 13 digit tin format.
      - `hungary_full_tax_identification_number` string — This optional field indicates the Hungarian VAT ID in the local format. It is relevant for e-invoicing in Hungary as only the local format is supported.
      - `india_einvoice_status_active` 'yes' | 'no' — This field indicates the e-invoicing status of the validated TIN in India.
      - `india_gstin_status` string — This field indicates whether the GSTIN is active, cancelled or suspended in India. Example values: "Active", "Cancelled", "Suspended".
      - `india_pan_name_match` 'yes' | 'no' — This field indicates if the sent name matches PAN (available for India PAN validation only).
      - `india_pan_date_match` 'yes' | 'no' — This field indicates if the sent date matches PAN (available for India PAN validation only).
      - `india_pan_aadhaar_linked` 'yes' | 'no' | 'not_applicable' — This field indicates whether an Aadhaar number is linked with a PAN (available for India PAN validation only). Not applicable if PAN belongs to a business.
      - `india_pan_specified_person` 'yes' | 'no' — This field indicates if PAN belongs to a specified person according to sections 206AB and 206CCA of the Indian Income Tax Act (available for India PAN validation only).
      - `india_trade_name` string — This optional field indicates the trade name of a given business in India.
      - `japan_qualified_invoice_issuer` 'yes' | 'no' — This field indicates whether the validated TIN belongs to a company eligible to issue qualified e-invoices in Japan.
      - `mexico_taxpayer_can_receive_einvoices` 'yes' | 'no' — This field indicates whether the validated TIN belongs to an entity eligible to receive e-invoices in Mexico.
      - `mexico_zip_code_used_for_validation` string — This field represents the cleaned ZIP Code used during the validation process. Only the first five digits of the provided ZIP Code are utilized.
      - `usa_irs_response` string — This response field shows the TIN validation response of the United States Internal Revenue Service (IRS).
      - `usa_suggested_name` string — This field provides name suggestions for cases when the name provided does not match the TIN provided according to the IRS's database.
  - `requested` string, date-time, required
  - `status` 'running' | 'completed', required
  - `validation_status` string, uri, required

## Other responses

- `400` — The provided data is not valid. This response will be served when you provide invalid parameters (ex. country code). It can also be returned if your batch is over 10000 unique Tax Identification Numbers.
- `401` — Unauthorized
- `415` — Unsupported Media Type, we only accept application/json
- `500` — Internal Server Error, something went wrong and we are investigating it.
- `503` — Service Unavailable

---

[API](https://skmtc.dev/fonoa/apis/fonoa-api.md) · [All operations](https://skmtc.dev/fonoa/apis/fonoa-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fonoa/fonoa-api/revisions/cf0ebc843a3f/schema)