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

# Request a validation

`POST /lookup/v1/validations`

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.

## Request body

- object
  - `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)
  - `tin` string, 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_online` boolean — 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.
  - `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
  - `cache_age_seconds` integer — 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.
  - `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.

## Response `200`

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.

- object
  - `status` 'completed', required
  - `validation` object, required
    - `id` string, required — Specifies the unique string for particular validation
    - `tin` string, required — Tax Identification Number (VAT ID, GST ID, etc.) expressed as a string
    - `country_iso` string, required — Customer ISO 3166-1 alpha-2 country code
    - `format_valid` boolean, required — Specifies whether the format of a given TIN is correct (eg. TIN in country X has 10 digits starting with 4 and ending with 9)
    - `checksum_valid` boolean — Specifies whether the number structure logic of a given TIN is correct if exists for this country (eg. the last digit might be calculated by MOD 11 algorithm or others)
    - `requested` string, required — Specifies the date, when the TIN validation has been requested.
    - `type` 'business' | 'individual' — Specifies whether the taxpayer is an individual, or a legal entity.
    - `validation_source` 'vies' | 'local' | 'vies_and_local' | 'none' — Validation source of the requested validation. If validation source was provided in the request, Fonoa will return the same in the response. If validation source was not provided, Fonoa will return the database source where the TIN was identified, including cases where VIES was temporarily unavailable and Fonoa fell back to the local government database. If we haven't found the result in any source, Fonoa will return `vies_and_local` value (assuming its a EU TIN) such that it is documented that we checked a given TIN in all available databases. If there were an issue where none of sources provided the result, we will return `none` as the source value.
    - `error_code` integer — An error code that occurred during a processing: 1 - Lookup experienced problems with online database, we could not find an answer for the request. 2 - The government TIN database is non-reachable due to planned maintenance. 3 - Unexpected behavior was detected with the online database. We are investigating the root cause. If you wish to obtain more information, please reach out to support@fonoa.com and share the request ID. 4 - Cannot return the result due to insufficient or wrongly formatted data provided. 5 - Online validation is not supported for this TIN. 7 - Missing {input-name}. Please include all required parameters to proceed with the validation. 8 - Invalid {input-name}. Ensure all required parameters are correct before proceeding with the validation. 9 - Missing your company credentials for the Tax Authority. Contact support@fonoa.com for assistance with securely providing credentials. 10 - The Tax Authority rejected your company credentials. Contact support@fonoa.com for assistance with securely providing valid credentials. 11 - The daily maximum number of validations of same TIN with various names, or, the same name with various TINs has been reached. Try again in 24 hours. 1001 - The taxpayer's name does not coincide with the one registered in the local database (only for Mexico). 1002 - The taxpayer's zip code does not coincide with the one registered in the local database (only for Mexico). 1003 - The taxpayer's name and zip code does not coincide with the one registered in the local database (only for Mexico). 1010 - The TIN and Tax Office do not match. Retry the validation with the correct Tax Office Code associated with the taxpayer (only for Turkey).
    - `error_details` LookupErrorDetailsResult — Error details of validation. Error codes: NETWORK_ERROR - Lookup experienced problems with online database, we could not find an answer for the request. TEMPORARY_UNAVAILABLE - The government TIN database is non-reachable due to planned maintenance. UNKNOWN_RESPONSE - Unexpected behavior was detected with the online database. We are investigating the root cause. If you wish to obtain more information, please reach out to support@fonoa.com and share the request ID. INCOMPLETE_IMPLEMENTATION - Cannot return the result due to insufficient or wrongly formatted data provided. ONLINE_CHECK_NOT_SUPPORTED - Online validation is not supported for this TIN. MISSING_REQUIRED_INPUT - Missing {input-name}. Please include all required parameters to proceed with the validation. INVALID_REQUIRED_INPUT - Invalid {input-name}. Ensure all required parameters are correct before proceeding with the validation. MISSING_TAX_AUTHORITY_CREDENTIALS - Missing your company credentials for the Tax Authority. Contact support@fonoa.com for assistance with securely providing credentials. TAX_AUTHORITY_CREDENTIALS_REJECTED - The Tax Authority rejected your company credentials. Contact support@fonoa.com for assistance with securely providing valid credentials. TAX_AUTHORITY_SAME_TAX_ID_LIMIT_REACHED - The daily maximum number of validations of same TIN with various names, or, the same name with various TINs has been reached. Try again in 24 hours. MX_NAME_MISMATCH - The taxpayer's name does not coincide with the one registered in the local database (only for Mexico). MX_ZIPCODE_MISMATCH - The taxpayer's zip code does not coincide with the one registered in the local database (only for Mexico). MX_NAME_AND_ZIPCODE_MISMATCH - The taxpayer's name and zip code does not coincide with the one registered in the local database (only for Mexico). TR_TIN_AND_TAX_OFFICE_MISMATCH - The TIN and Tax Office do not match. Retry the validation with the correct Tax Office Code associated with the taxpayer (only for Turkey).
      - `code` 'NETWORK_ERROR' | 'TEMPORARY_UNAVAILABLE' | 'UNKNOWN_RESPONSE' | 'INCOMPLETE_IMPLEMENTATION' | 'ONLINE_CHECK_NOT_SUPPORTED' | 'MISSING_REQUIRED_INPUT' | 'INVALID_REQUIRED_INPUT' | 'MISSING_TAX_AUTHORITY_CREDENTIALS' | 'TAX_AUTHORITY_CREDENTIALS_REJECTED' | 'TAX_AUTHORITY_SAME_TAX_ID_LIMIT_REACHED' | 'MX_NAME_MISMATCH' | 'MX_ZIPCODE_MISMATCH' | 'MX_NAME_AND_ZIPCODE_MISMATCH' | 'TR_TIN_AND_TAX_OFFICE_MISMATCH', required — Error code
      - `message` string, required — Human-readable error message
    - `company_name` string — A company name acquired from online database
    - `tin_exists_online` boolean — Specifies whether the TIN was identified in a given government database and whether this identified TIN is currently registered for VAT/GST
    - `last_checked_online` string — Specifies the date, when TIN has been checked against online database. Value will be close to requested if no cache has been specified.
    - `business_status` 'active' | 'inactive' | 'unknown' — Specifies whether the company identified by its TIN is currently active in the relevant government register, regardless of whether it is registered for VAT/GST.
    - `taxpayer` LookupResponseTaxpayer
      - `registration_type` 'Regular' | 'Composition' | 'Special Economic Zone' | 'Casual Taxable Person' | 'Unknown' | 'Non Resident Online Services Provider' | 'Registered' | 'Exempt' | 'Final Consumer' | 'Monotributo' | 'Input Service Distributor (ISD)' | 'SEZ Developer' | 'Tax Deductor' | 'Non Resident Foreign Taxpayer' | 'UN Bodies, Embassies and Other Notified Persons' | 'Tax Collector (Electronic Commerce Operator)' | 'Temporary' | 'According to §4 of the VAT Act' | 'According to §4b of the VAT Act' | 'According to §7 of the VAT Act' | 'According to §7a of the VAT Act' | 'Plátce' | 'Identifikovaná osoba' | 'Normal Trimestral' | 'Normal Trimestral por Opção' | 'Normal Mensal' | 'Normal Mensal por Opção' | 'Isenção Artº 53' | 'Isenção Artº 9' | 'Reg. Esp. Peq. Retalhistas' | 'Não Sujeito' | 'Reg. Especial Tributação' | 'Aquisições Intracomunitárias' | 'Micro' | 'Small' | 'Medium' | 'Large' — Type of tax registration.
      - `entity_type` string — It represents the legal entity type of the taxpayer, the values depend on the country. Some examples: - Public Limited Company - Private Limited Company - Limited Liability Partnership - General Partnership - Joint Stock Company
      - `registration_date` string, date — Date at which the entity became registered for indirect tax as shown in the official database.
      - `deregistration_date` string, date — Date at which the entity became deregistered for indirect tax as shown in the official database.
      - `address` string
    - `external_id` string — An additional reference identifier you provided in your request - typically, the identifier used in your own system. You can use this to match results back to your own data.
    - `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.

## Other responses

- `202` — The validation process has started and you need to fetch the results from a resource provided in the response
- `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 you do not provide valid additional_parameters value (ex. Turkey)
- `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)