--- title: "Get result of batch validation" method: GET path: "/lookup/v2/batch-validations/{batch_id}" tags: ["Lookup V2"] --- # Get result of batch validation `GET /lookup/v2/batch-validations/{batch_id}` This endpoint provides batch Tax Identification Number validation results. To access it you need to use the batch_id returned from the “Request a batch validation” endpoint. It consists of a validation results list and status which can hold 3 states: - **"completed"** - validation for that request finished. - **"running"** - validation process for that request is still in progress, you should check its results again. - **"canceled"** - validation process for that request has been canceled by user when validation is part of canceled batch validation. ## Query parameters - `limit` number - `cursor` string ## Response `200` Batch result - object - `status` 'completed' | 'running' | 'canceled', required - `batch_id` string, required - `batch_name` string - `completion_percentage` integer, required - `requested_at` string, date-time, required - `pagination` object, required - `limit` integer, required - `next_cursor` string, nullable, required - `validations` object[], required - `validation_id` string, required — Specifies the unique string for particular validation - `tax_identification_number` string, 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. - `country_iso_code` string, required — Customer ISO 3166-1 alpha-2 country code - `status` 'completed' | 'pending' | 'canceled', required - `name` string — A name acquired from online database - `format` 'valid' | 'invalid', required — Specifies whether the format/checksum of a given TIN is correct (eg. TIN in country X has 10 digits starting with 4 and ending with 9) - `found_in_official_database` 'yes' | 'no' | 'unknown' | 'not_applicable', required — This field allows you to state whether the tax identification number provided was found in the official database. - `tax_registered` 'yes' | 'no' | 'unknown' | 'not_applicable', required — Specifies whether the TIN was identified in a given government database and whether this identified TIN is currently registered for VAT/GST. - `requested_at` string, date-time, required — Specifies the date, when the TIN validation has been requested. - `validation_database_source` 'vies' | 'local' | 'vies_and_local' | 'not_available' | 'fonoa_cache', required — 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 `not_available` as the source value. If prefer_cached_result was set to true and a cached result was found in the Instant Lookup database, Fonoa will return fonoa_cache. - `is_business` 'yes' | 'no' | 'unknown' | 'not_applicable', required — Specifies whether the taxpayer is an individual, or a legal entity. - `business_status` 'active' | 'inactive' | 'unknown', required — 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. - `legal_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 - `tax_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. - `registration_date` string, date — Date at which the entity became registered for indirect tax as shown in the official database. - `de_registration_date` string, date — Date at which the entity became deregistered for indirect tax as shown in the official database. - `address` string - `fuzzy_matching` LookupFuzzyMatchingResponseV2 — This signifies the result of a fuzzy matching request. A response exists if a fuzzy matching request was made and there was no error during the online validation. It contains requested values, actual values and the similarity score in the form of a percentage. If there is no data available, `actual`, and `similarity_percentage` will be replaced by `"error": "DATA_NOT_FOUND"`. - `name` LookupFuzzyMatchingNameResultV2 - `expected` string, required — Requested expected value - `similarity_percentage` number — Result in percentage 0-100 (integer) - `error` 'DATA_NOT_FOUND' — Optional error field when can't get similarity percentage - `matched_field` string — Field from the official source that produced the reported name similarity score. This can be the standard `name` field or a country-specific field. - `address` LookupFuzzyMatchingResultV2 - `expected` string, required — Requested expected value - `similarity_percentage` number — Result in percentage 0-100 (integer) - `error` 'DATA_NOT_FOUND' — Optional error field when can't get similarity percentage - `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. - `error_details` LookupErrorDetailsResultV2 — 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). FORMAT_INVALID - The provided TIN has an invalid format or checksum according to the selected country validation rules. - `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' | 'FORMAT_INVALID', required — Error code - `message` string, required — Human-readable error message - `extra_fields` LookupExtraFieldsV2 — 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. - `italy_codice_fiscale_status` string — This field shows the specific statuses of Codice Fiscale based on the Italian Tax Authority's response. It can show special cases when the Codice Fiscale is no longer valid e.g., in case a business's Codice Fiscale changed because their office moved, or when an Individual officially changed their name. - `italy_vat_split_payment` 'yes' | 'no' — This field indicates whether the validated TIN belongs to a company subject to the Italian split payment regime. In split payment, VAT is paid directly to the Italian tax authorities by the customer instead of the supplier. - `brazil_status_detail` string — This field provides detailed status information for Brazilian CNPJs based on the official registration status code. Available only via API validations. - `brazil_cnae_code` string — The principal CNAE (Economic Activity Classification) code for the Brazilian entity. Available only via API validations. - `brazil_cnae_description` string — The description of the principal CNAE (Economic Activity Classification) for the Brazilian entity. Available only via API validations. - `brazil_secondary_cnaes` object[] — Secondary CNAE (Economic Activity Classification) codes for the Brazilian entity. Available only via API validations. - `code` string — The secondary CNAE code - `description` string — The description of the secondary CNAE - `brazil_municipality` string — The municipality where the Brazilian entity has jurisdiction. Available only via API validations. - `brazil_federal_state` string — The federal state (UF) where the Brazilian entity is located. Available only via API validations. - `brazil_neighborhood` string — The neighborhood (bairro) where the Brazilian entity is located. Available only via API validations. - `brazil_company_size` string — The registered size/classification of the Brazilian company according to the Federal Revenue. Available only via API validations. - `brazil_special_status` string — Special status of the Brazilian entity if applicable (e.g., bankruptcy, judicial recovery). Available only via API validations. - `brazil_special_status_date` string, date — The date when the special status was applied to the Brazilian entity. Available only via API validations. - `brazil_date_of_birth` string, date — Date of birth for Brazilian individual taxpayers (CPF). Available only via API validations. - `brazil_year_of_death` string — Year of death for deceased Brazilian individual taxpayers (CPF). Available only via API validations. - `brazil_suframa` object — SUFRAMA (Superintendência da Zona Franca de Manaus) registration information for Brazilian entities. Available only via API validations. - `number` string — SUFRAMA registration number - `status` 'ACTIVE' | 'INACTIVE' | 'BLOCKED' | 'CANCELED' | 'CANCELED_AG_REC' — Current status of the SUFRAMA registration - `registration_date` string, date — Date when the SUFRAMA registration was established - `brazil_state_registrations` object[] — State tax registrations (Inscrição Estadual) for Brazilian entities across different states. Available only via API validations. - `number` string — State registration number - `federal_state` string — Federal state code - `enabled` boolean — Whether the state registration is currently enabled - `registration_date` string, date — Date of state registration - `status` 'NO_RESTRICTION' | 'BLOCKED' | 'VEDADA' — Current status of the state registration - `type` 'IE_NORMAL' | 'IE_SUBSTITUTO_TRIBUTARIO' | 'IE_NAO_CONTRIBUINTE' | 'IE_PRODUTOR_RURAL' | 'IE_CONTRIBUINTE_DA_UF_COM_ENDEREÇO_EM_OUTRA_UF' | 'IE_NÃO_INFORMADA' — Type of state registration - `brazil_simples` object — Simples Nacional tax regime status for Brazilian entities. Indicates whether the entity is opted into the simplified federal tax regime (Lei Complementar 123/2006) for micro and small businesses. - `optant` 'yes' | 'no' — Whether the entity is currently opted into the Simples Nacional tax regime - `company_representative_name` string — This optional field indicates the official representative of the company. - `brazil_status_reason` string — Reason for the current registration status of the Brazilian entity. Available only via API validations. - `brazil_status_date` string, date — Date when the current registration status was set for the Brazilian entity. Available only via API validations. - `brazil_address` object — Detailed address information for Brazilian entities. Available only via API validations. - `street` string — Street name and type - `number` string — Street number - `additional_info` string — Additional address information (complement) - `neighborhood` string — Neighborhood (bairro) - `city` string — City name - `state` string — State abbreviation - `postal_code` string — Postal code (CEP) - `country` string — Country name - `country_code` string — Country code - `city_code` string — IBGE city code - `brazil_legal_nature_code` string — Legal nature code of the Brazilian entity according to IBGE classification. Available only via API validations. - `brazil_entity_social_capital` string — Registered social capital of the Brazilian entity in Brazilian Reais. Available only via API validations. - `brazil_email` string, email — Official email address registered with the Brazilian Federal Revenue. Available only via API validations. - `indonesia_name_match_tin` 'yes' | 'no' — This field indicates if the sent name matches NIK (available for Indonesia NIK validations). - `indonesia_date_of_birth_match_tin` 'yes' | 'no' — This field indicates if the NIK contains correct date of birth information (available for Indonesia NIK validations). - `business_activities` object[] — A list of the business activities the entity is registered or authorized to perform. - `activity` string — A descriptive name of the business activity performed by the entity, based on the classification used by the local authority or registry. - `code` string — The official activity code assigned by the relevant authority or classification system. This code uniquely identifies the type of economic activity. - `category` string — The category or classification tier assigned to the activity, according to the applicable local or regulatory framework. - `subject_to_vat` 'yes' | 'no' | 'unknown' | 'not_applicable' — Indicates whether this activity is subject to value-added tax (VAT). - `registration_date` string, date — The date when this activity was officially registered, activated, or recognized by the relevant authority for regulatory or tax purposes. - `additional_parameters` LookupAdditionalParametersV2 — Additional parameters that can or need to be provided in particular countries. - `name` string — Optional for Canada, Lithuania, Mexico, Spain, India (PAN validation). Required for the US business TINs (EIN), Philippines business TINs, China individual TINs and Indonesia individual TINs. For Canada taxpayer's name can be added to perform a direct search, otherwise Fonoa will identify the name based on the TIN itself. For Spain and Lithuania taxpayer's name can be added to run a database validation on a personal tax identification number. For Mexico taxpayer's name can be provided to check 100% matching of the name with official database. For India PAN validations taxpayer's name can be provided to check 100% matching of the name with official database. The result will contain `india_pan_name_match` field in `extra_fields`. For the US company name has to be provided to check Employer Identification Number (EIN). For China taxpayer's name (full personal name in Chinese) is required for national ID validation (`individual` `tax_identification_number_type`). - `first_name` string — Required if validating individual TINs in Philippines and for the US if validating individual `tax_identification_number_type` (Social Security Number). - `last_name` string — Required if validating individual TINs in Philippines and for the US if validating individual `tax_identification_number_type` (Social Security Number). - `date` string — Optional for Canada, Croatia, Poland, and India. Date in YYYY-MM-DD format. For Canada, Croatia, Poland it can be provided to check if TIN was valid on a specific date. For India PAN validations it can be provided to check matching of the date of birth with official database. The result will contain `india_pan_date_match` field in `extra_fields`. Required for Philippines individual TINs (birth date of the individual). - `zip_code` string — Optional for Mexico. Zip code (5 digits) where the taxpayer is registered can be provided to check 100% matching. - `gender` 'male' | 'female' — Required for Philippines to validate individual TINs (gender of the individual). - `turkey_tax_office` string — Optional for Turkey. Tax office code (6 digits) where the taxpayer is registered. For validation in government database with the full list, this field is required, however, the request will proceed and be tried without it to see if tax id can be found in alternative government databases without the full list. - `canada_bc_pst` string — Optional for Canada. 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). - `india_state_name` string — Optional for India. 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"` - `egypt_uin` string — The UIN is a 39-character mixed format identifier which is required for Egyptian tax ID validation. - `malaysia_id_type` string — Optional for Malaysia. Required only for Malaysia TIN validation Type of the additional value for Malaysia TIN validation. Allowed values: `"army"`, "`passport"`, "`nric"`, "`brn"` - `malaysia_id_value` string — Optional for Malaysia. Required only for Malaysia TIN validation Additional value for Malaysia TIN validation - `nigeria_brn` string — Optional for Nigeria. Required for 13-digit Tax ID validation via the JRB portal. CAC/RC business registration number. Org type is hardcoded to Company on Fonoa's side. - `tax_identification_number_used_for_validation` string — A tax identification number used to query the official database - `tax_identification_number_name` string — Represents the full and abbreviated name of Tax Identification Number (TIN) provided by the user in the local language. ## Other responses - `401` — Unauthorized - `404` — Not Found - `500` — Internal Server Error - `503` — Service Unavailable --- [API](https://skmtc.net/fonoa/apis/fonoa-api.md) · [All operations](https://skmtc.net/fonoa/apis/fonoa-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fonoa/fonoa-api/versions/cf0ebc843a3f/schema)