---
updatedAt: 2026-04-27T13:18:01.000Z
agentTools:
projectIndex: https://docs.fonoa.com/llms.txt
---
# Request a batch validation
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.
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"info": {
"title": "Fonoa API",
"description": "The Fonoa API allows you to automate tax compliance.\n\nThe Fonoa API gives you and your clients or employers access to various tax automation products, including Tax Identification Number validation, tax rate calculation, invoice generation, and real-time transaction reporting.\n\nThe API is organized around REST, has predictable, resource-oriented URLs, and uses JSON response codes to indicate API errors.\n\nThis API documentation provides information about each endpoint in the API. Using the pane on the right-hand side, you try out sample requests and responses for each endpoint in various programming languages.",
"contact": {
"name": "Fonoa Support",
"url": "https://www.fonoa.com/",
"email": "support@fonoa.com"
},
"version": "1.0"
},
"x-proxy-enabled": false,
"servers": [
{
"url": "https://api-demo.fonoa.com",
"description": "Fonoa API demo environment",
"variables": {}
},
{
"url": "https://sandbox.fonoa.com/",
"description": "Fonoa API sandbox environment",
"variables": {}
},
{
"url": "https://api.fonoa.com",
"description": "Fonoa API production (live) environment",
"variables": {}
}
],
"paths": {
"/lookup/v2/batch-validations": {
"post": {
"tags": [
"Lookup V2"
],
"summary": "Request a batch validation",
"operationId": "RequestbatchvalidationV2",
"responses": {
"200": {
"description": "This is an immediate response for validations and provides details whether the format were invalid, status or error details (no background processing needed).\nThe 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.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"batch_id": {
"type": "string",
"x-stoplight": {
"id": "xazap0o53jmv4"
}
},
"batch_name": {
"type": "string",
"x-stoplight": {
"id": "1ct6hjaju80id"
}
},
"validations": {
"type": "array",
"x-stoplight": {
"id": "sh8u8j0j1dmds"
},
"items": {
"$ref": "#/components/schemas/LookupValidationImmediateResponseV2",
"x-stoplight": {
"id": "wmtsgupaxr8vv"
}
}
},
"requested_at": {
"type": "string",
"x-stoplight": {
"id": "2qup9amp1p3mq"
},
"format": "date-time"
},
"status": {
"type": "string",
"x-stoplight": {
"id": "y1dwt8yn3v1xy"
},
"enum": [
"completed"
]
},
"batch_validation_result_url": {
"type": "string",
"x-stoplight": {
"id": "ybqywvlrrrtlz"
},
"format": "uri"
}
},
"required": [
"batch_id",
"batch_name",
"validations",
"requested_at",
"status",
"batch_validation_result_url"
]
}
}
}
},
"202": {
"description": "The validation process has started and you need to fetch the results from a resource provided in the response or use webhooks (https://docs.fonoa.com/reference/lookup-webhook-events).\nThis 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.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"batch_id": {
"type": "string",
"example": "bd5fa7cc-3597-454e-86fb-a94b79514726"
},
"batch_name": {
"type": "string",
"example": "batch-2022-12-25-09-07-54"
},
"validations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LookupValidationImmediateResponseV2"
}
},
"requested_at": {
"type": "string",
"format": "date-time",
"example": "2022-05-19T13:03:44.667Z"
},
"status": {
"type": "string",
"enum": [
"running"
]
},
"batch_validation_result_url": {
"type": "string",
"format": "uri",
"example": "https://api-demo.fonoa.com/lookup/v2/batch-validations/bd5fa7cc-3597-454e-86fb-a94b79514726"
}
},
"required": [
"batch_id",
"batch_name",
"validations",
"requested_at",
"status",
"batch_validation_result_url"
]
},
"examples": {
"example-1": {
"value": {
"batch_id": "7e7f4459-5871-47a1-af3d-364df9c31fe0",
"batch_name": "batch-2022-12-25-09-07-54",
"validations": [
{
"validation_id": "3dc8b6d9-57af-4afb-9184-ef510be3f388",
"tax_identification_number": "GB830930346",
"country_iso_code": "gb",
"format": "valid",
"requested_at": "2022-12-28T14:55:11.575Z",
"is_business": "unknown",
"fuzzy_matching": {
"name": "teamwear",
"address": "Wildflower 22 Belfast"
}
}
],
"requested_at": "2021-03-25T09:37:41.649Z",
"status": "running",
"batch_validation_result_url": "https://api-demo.fonoa.com/lookup/v2/batch-validations/7e7f4459-5871-47a1-af3d-364df9c31fe0"
}
},
"example-2": {
"value": {
"batch_id": "7e7f4459-5871-47a1-af3d-364df9c31fe0",
"batch_name": "batch-2022-12-25-09-07-54",
"validations": [
{
"validation_id": "13e8b6d9-57af-4afb-9184-ef510be3f399",
"tax_identification_number": "123",
"country_iso_code": "au",
"format": "invalid",
"requested_at": "2022-12-28T14:55:11.575Z",
"is_business": "unknown",
"error_details": {
"code": "FORMAT_INVALID",
"message": "ABN should contain 11 digits, and ACN should contain 9 digits"
}
}
],
"requested_at": "2021-03-25T09:37:41.649Z",
"status": "completed",
"batch_validation_result_url": "https://api-demo.fonoa.com/lookup/v2/batch-validations/7e7f4459-5871-47a1-af3d-364df9c31fe0"
}
}
}
}
}
},
"400": {
"description": "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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LookupErrorResponseV2"
},
"examples": {
"example-1": {
"value": {
"errors": [
{
"code": "COUNTRY_NOT_SUPPORTED",
"message": "Country 'xx' not supported."
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LookupErrorResponseV2"
}
}
}
},
"415": {
"description": "Unsupported Media Type, we only accept application/json",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LookupErrorResponseV2"
},
"examples": {
"example-1": {
"value": {
"errors": [
{
"code": "INVALID_MIME_ONLY_JSON_IS_VALID",
"message": "Invalid mime type, valid mime type is 'application/json'."
}
]
}
}
}
}
}
},
"500": {
"description": "Internal Server Error, something went wrong and we are investigating it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LookupErrorResponseV2"
},
"examples": {
"example-1": {
"value": {
"errors": [
{
"code": "INTERNAL_ERROR",
"message": "Something went wrong while processing your validation, please try again."
}
]
}
}
}
}
}
},
"503": {
"description": "Service Unavailable"
}
},
"description": "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.\n\nSet 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.\n",
"requestBody": {
"content": {
"application/json": {
"schema": {
"description": "",
"type": "object",
"title": "LookupBatchTinValidationRequest",
"properties": {
"batch_name": {
"type": "string",
"example": "batch-2022-12-25-09-07-54"
},
"max_retry_duration": {
"$ref": "#/components/schemas/LookupMaxRetryDuration"
},
"tax_identification_number_requests": {
"type": "array",
"uniqueItems": false,
"minItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"country_iso_code": {
"$ref": "#/components/schemas/LookupCountryIsoRequest"
},
"tax_identification_numbers": {
"type": "array",
"description": "List of Tax Identification Numbers (VAT ID, GST ID, etc.) expressed as a strings",
"example": [
"EE102360282, EE101757663, EE100210457, EE102019944, EE101279099"
],
"items": {
"type": "string"
}
},
"tax_identification_number_type": {
"$ref": "#/components/schemas/LookupTinType"
},
"additional_parameters": {
"$ref": "#/components/schemas/LookupAdditionalParametersV2"
},
"validation_database_source": {
"$ref": "#/components/schemas/LookupRequestValidationSource"
},
"fuzzy_matching": {
"$ref": "#/components/schemas/LookupFuzzyMatchingRequestV2"
},
"external_id": {
"$ref": "#/components/schemas/LookupRequestExternalId"
}
},
"required": [
"country_iso_code",
"tax_identification_numbers"
]
}
}
},
"required": [
"tax_identification_number_requests"
]
},
"examples": {
"example-1": {
"value": {
"tax_identification_number_requests": [
{
"country_iso_code": "ee",
"tax_identification_numbers": [
"EE102360282"
],
"validation_database_source": "vies",
"fuzzy_matching": {
"name": "expected name",
"address": "expected address"
},
"external_id": "cust000577"
}
]
}
},
"smart-retries": {
"summary": "Request batch validation with smart retries for up to 24 hours",
"value": {
"max_retry_duration": 24,
"tax_identification_number_requests": [
{
"country_iso_code": "de",
"tax_identification_numbers": [
"DE123456789"
]
},
{
"country_iso_code": "nl",
"tax_identification_numbers": [
"NL123456789B01"
]
}
]
}
}
}
}
},
"description": ""
}
}
}
},
"components": {
"schemas": {
"LookupAdditionalParametersV2": {
"type": "object",
"description": "Additional parameters that can or need to be provided in particular countries.",
"x-examples": {
"Example (Tax office for TR)": {
"turkey_tax_office": "034567"
},
"Example (Name for CA)": {
"name": "Amazon Advertising Canada, Inc."
},
"Example (Date for CA, PL, HR or IN)": {
"date": "2022-01-02"
},
"Example (india_state_name)": {
"india_state_name": "Delhi"
}
},
"properties": {
"name": {
"type": "string",
"description": "Optional for Canada, Lithuania, Mexico, Spain, India (PAN validation). \n\nRequired for the US business TINs (EIN), Philippines business TINs, China individual TINs and Indonesia individual TINs.\n\nFor Canada taxpayer's name can be added to perform a direct search, otherwise Fonoa will identify the name based on the TIN itself.\n\nFor Spain and Lithuania taxpayer's name can be added to run a database validation on a personal tax identification number.\n\nFor Mexico taxpayer's name can be provided to check 100% matching of the name with official database.\n\nFor 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`.\n\nFor the US company name has to be provided to check Employer Identification Number (EIN).\n\nFor China taxpayer's name (full personal name in Chinese) is required for national ID validation (`individual` `tax_identification_number_type`)."
},
"first_name": {
"type": "string",
"x-stoplight": {
"id": "qntvrfl2eoct6"
},
"description": "Required if validating individual TINs in Philippines and for the US if validating individual `tax_identification_number_type` (Social Security Number)."
},
"last_name": {
"type": "string",
"x-stoplight": {
"id": "0dr7iana3o9wb"
},
"description": "Required if validating individual TINs in Philippines and for the US if validating individual `tax_identification_number_type` (Social Security Number)."
},
"date": {
"type": "string",
"description": "Optional for Canada, Croatia, Poland, India, and Brazilian individual TINs.\n\nDate in YYYY-MM-DD format.\n\nFor Canada, Croatia, Poland it can be provided to check if TIN was valid on a specific date.\n\nFor 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`.\n\nFor Brazilian individual TINs (CPF) it is the birth date of the individual. If provided, the CPF is validated in real time. If omitted, the CPF is checked against an alternative data source, so the result may not be fully up to date.\n\nRequired for Philippine individual TINs (birth date of the individual).\n"
},
"zip_code": {
"type": "string",
"description": "Optional for Mexico.\n\nZip code (5 digits) where the taxpayer is registered can be provided to check 100% matching."
},
"gender": {
"type": "string",
"description": "Required for Philippines to validate individual TINs (gender of the individual).",
"enum": [
"male",
"female"
]
},
"turkey_tax_office": {
"type": "string",
"description": "Optional for Turkey.\n\nTax 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": {
"type": "string",
"description": "Optional for Canada.\n\nIn 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": {
"type": "string",
"x-stoplight": {
"id": "6tjhx44mp75qf"
},
"description": "Optional for India.\n\nUsed for validating whether the GSTIN corresponds to the relevant state where the taxpayer is based.\nAllowed 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": {
"type": "string",
"x-stoplight": {
"id": "8245y7qf5n3jh"
},
"description": "The UIN is a 39-character mixed format identifier which is required for Egyptian tax ID validation.",
"example": "10000010066d9770abe966h4vk7H9oj0cd7c8a8"
},
"malaysia_id_type": {
"type": "string",
"description": "Optional for Malaysia. Required only for Malaysia TIN validation\n\nType of the additional value for Malaysia TIN validation.\nAllowed values: `\"army\"`, \"`passport\"`, \"`nric\"`, \"`brn\"`",
"example": "brn"
},
"malaysia_id_value": {
"type": "string",
"description": "Optional for Malaysia. Required only for Malaysia TIN validation\n\nAdditional value for Malaysia TIN validation",
"example": "X19510100011"
},
"nigeria_brn": {
"type": "string",
"description": "Optional for Nigeria. Required for 13-digit Tax ID validation via the JRB portal.\n\nCAC/RC business registration number. Org type is hardcoded to Company on Fonoa's side.",
"example": "1234567"
}
}
},
"LookupValidationImmediateResponseV2": {
"title": "LookupValidationImmediateResponseV2",
"x-stoplight": {
"id": "i96amkn9oaayf"
},
"type": "object",
"x-examples": {
"example-1": {
"validation_id": "12345678901234567",
"tax_identification_number": "96828400-2",
"name": "PARQUE ARAUCO INTERNACIONAL S.A.",
"format": "valid",
"found_in_official_database": "yes",
"tax_registered": "yes",
"requested_at": "2021-03-25T09:37:06.075Z",
"validation_database_source": "vies",
"is_business": "yes",
"business_status": "active",
"fuzzy_matching": {
"name": {
"actual": "PARQUE ARAUCO INTERNACIONAL S.A.",
"similarity_percentage": 100
}
},
"external_id": "cust000577"
}
},
"properties": {
"validation_id": {
"type": "string",
"description": "Specifies the unique string for particular validation.",
"example": "b470a195-8e83-4d89-b4a7-4d389ac358a4"
},
"tax_identification_number": {
"$ref": "#/components/schemas/LookupTin"
},
"country_iso_code": {
"$ref": "#/components/schemas/LookupCountryIsoResponse"
},
"format": {
"$ref": "#/components/schemas/LookupFormatValidV2"
},
"requested_at": {
"type": "string",
"format": "date-time",
"description": "Specifies the date, when the TIN validation has been requested."
},
"is_business": {
"$ref": "#/components/schemas/LookupResponseIsBusiness"
},
"validation_database_source": {
"$ref": "#/components/schemas/LookupResponseValidationSourceV2"
},
"error_details": {
"$ref": "#/components/schemas/LookupErrorDetailsResultV2"
},
"external_id": {
"$ref": "#/components/schemas/LookupResponseExternalId"
},
"extra_fields": {
"$ref": "#/components/schemas/LookupExtraFieldsV2"
},
"tax_identification_number_type": {
"$ref": "#/components/schemas/LookupTinType"
},
"additional_parameters": {
"$ref": "#/components/schemas/LookupAdditionalParametersV2",
"x-stoplight": {
"id": "mueq6f85woqbv"
}
},
"fuzzy_matching": {
"description": "When validation_database_source is NOT fonoa_cache, this echoes back the fuzzy matching values from the request (see LookupFuzzyMatchingRequestV2).\n\nWhen validation_database_source is fonoa_cache (Instant Lookup cache hit), this contains the cached fuzzy matching result in response format with similarity scores (see LookupFuzzyMatchingResponseV2).\n"
},
"found_in_official_database": {
"allOf": [
{
"$ref": "#/components/schemas/LookupFoundInOfficialDatabase"
}
],
"description": "Only present when validation_database_source is fonoa_cache. Indicates whether the TIN was found in the official database according to the cached result."
},
"tax_registered": {
"allOf": [
{
"$ref": "#/components/schemas/LookupTaxRegistered"
}
],
"description": "Only present when validation_database_source is fonoa_cache. Indicates whether the TIN is currently registered for tax according to the cached result."
},
"name": {
"type": "string",
"description": "Taxpayer name from the cached result. Only present when validation_database_source is fonoa_cache.",
"example": "ACME CO."
},
"business_status": {
"allOf": [
{
"$ref": "#/components/schemas/LookupResponseBusinessStatus"
}
],
"description": "Only present when validation_database_source is fonoa_cache."
},
"address": {
"allOf": [
{
"$ref": "#/components/schemas/LookupResponseAddress"
}
],
"description": "Only present when validation_database_source is fonoa_cache."
},
"legal_entity_type": {
"allOf": [
{
"$ref": "#/components/schemas/LookupResponseLegalEntityType"
}
],
"description": "Only present when validation_database_source is fonoa_cache."
},
"registration_type": {
"type": "string",
"description": "Tax registration type from the cached result. Only present when validation_database_source is fonoa_cache.",
"example": "Regular"
},
"registration_date": {
"allOf": [
{
"$ref": "#/components/schemas/LookupResponseRegistrationDate"
}
],
"description": "Only present when validation_database_source is fonoa_cache."
},
"de_registration_date": {
"allOf": [
{
"$ref": "#/components/schemas/LookupResponseDeRegistrationDate"
}
],
"description": "Only present when validation_database_source is fonoa_cache."
},
"tax_identification_number_used_for_validation": {
"allOf": [
{
"$ref": "#/components/schemas/LookupTinUsedForValidation"
}
],
"description": "The TIN that was used to query the official database, as returned by the Instant Lookup cache. Only present when validation_database_source is fonoa_cache."
},
"tax_identification_number_name": {
"allOf": [
{
"$ref": "#/components/schemas/LookupTinName"
}
],
"description": "Full name of the Tax Identification Number type in the local language. Only present when validation_database_source is fonoa_cache."
},
"last_updated": {
"type": "string",
"format": "date-time",
"description": "Timestamp of when the cached result was last updated in the Instant Lookup database. Only present when validation_database_source is fonoa_cache.",
"example": "2026-03-05T08:00:00.000Z"
},
"country_specific": {
"type": "object",
"additionalProperties": true,
"description": "Country-specific fields from the cached result. The contents vary by country. Only present when validation_database_source is fonoa_cache.",
"example": {
"fantasy_name": "Example Corp"
}
}
},
"required": [
"validation_id",
"tax_identification_number",
"country_iso_code",
"format",
"requested_at",
"is_business"
]
},
"LookupDetailedErrorMessage": {
"title": "LookupDetailedErrorMessage",
"type": "object",
"properties": {
"detailed_error_messages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}
},
"LookupRequestErrorCode": {
"title": "LookupRequestErrorCode",
"type": "string",
"description": "Request-level error codes returned by the public Lookup v2 API, including validation and TIN Search requests (JSON and CSV).\nThese are distinct from validation-result error_details codes returned in successful responses.\n\n`retryable: false` means an unchanged request will fail again. Correct the input, credentials, subscription or limits before retrying.\n`retryable: true` means a transient failure may resolve. Retry with backoff. Before resubmitting a create request, check whether it already succeeded to avoid duplicate work.\nHTTP statuses depend on the endpoint and input format. Messages with braces are templates; numeric limits and other values shown are illustrative and may vary.\nThe message and details fields can provide more context, including CSV record numbers and validation errors.\nUS and Philippines JSON field-validation messages appear under INVALID_REQUEST in details.detailed_error_messages. US-specific codes are returned by CSV validation.\n\n| Code | HTTP status | Message | retryable |\n| --- | --- | --- | --- |\n| `CURSOR_PARSING_ERROR` | 400 | Cursor cannot be parsed. | false |\n| `INVALID_ID_ERROR` | 400 | Invalid 'id'. | false |\n| `INTERNAL_ERROR` | 500 | Something went wrong. | true |\n| `NO_VALIDATION_FOUND` | 404 | Validation cannot be found. | false |\n| `NO_BATCH_FOUND` | 404 | Batch cannot be found. | false |\n| `TIN_SEARCH_NOT_FOUND` | 404 | TIN search cannot be found. | false |\n| `AUTHENTICATION_ERROR` | 401 | Unauthorized request. | false |\n| `MISSING_QUERY_OR_COUNTRY_ISO_CODE` | 422 | Incorrect CSV format, missing 'query' or 'country_iso_code'. | false |\n| `MISSING_TAX_IDENTIFICATION_NUMBER_OR_COUNTRY_ISO_CODE` | 422 | Incorrect CSV format, missing 'tax_identification_number' or 'country_iso_code'. | false |\n| `CANNOT_HAVE_ZERO_ENTRIES` | 422 | Number of entries cannot be zero. | false |\n| `INVALID_MIME_ONLY_FORM_DATA_IS_VALID` | 415 | Invalid mime type, valid mime type is 'multipart/form-data'. | false |\n| `INVALID_MIME_ONLY_JSON_IS_VALID` | 415 | Invalid mime type, valid mime type is 'application/json'. | false |\n| `VALIDATIONS_AMOUNT_EXCEEDED` | 400 | Your subscription has run out of available validations. Max number: {max}, remaining number: {remaining}, number of validations in request: {inRequest}. | false |\n| `COUNTRIES_NOT_ALLOWED` | 400 | Your subscription does not allow you to validate the next countries: {countries}. | false |\n| `CANNOT_HAVE_MORE_THAN_X_TINS` | 400 | Request should not have more than 50000 tins, current request have {currentLength}. | false |\n| `COUNTRY_NOT_SUPPORTED` | 400, 422 | Country '{unsupportedCountry}' not supported.
Countries '{country1}', '{country2}' not supported. | false |\n| `BATCH_REQUEST_CANNOT_BE_EMPTY` | 400 | Batch request cannot be empty. | false |\n| `CSV_COLUMN_MISMATCH_ERROR` | 422 | CSV has more columns than expected. | false |\n| `CSV_GENERIC_PARSING_ERROR` | 422 | CSV cannot be parsed. | false |\n| `INVALID_VALIDATION_DATABASE_SOURCE` | 422 | Invalid validation database source: {source}. | false |\n| `VALIDATION_SOURCE_NOT_SUPPORTED_FOR_COUNTRY` | 400 | Validation source '{source}' not supported for country '{countryIso}'.
Validation source requested is not supported for countries: {countryIso} ({source}). | false |\n| `CSV_COUNTRY_CODE_FORMAT_ERROR` | 422 | CSV contains invalid country format. Country column should contain 2-letter country codes. | false |\n| `UNSUPPORTED_PARAMETER_ERROR` | 422 | Additional parameter \"{parameter}\" not supported for country \"{countryIso}\". | false |\n| `INVALID_REQUEST` | 400, 413 | Invalid request.
Validation is still running and cannot be deleted.
Batch contains validation/s that are still running and cannot be deleted.
Validation belongs to a batch and cannot be deleted. | false |\n| `DIRECT_TAX_ID_NOT_SUPPORTED` | 400, 422 | Direct tax id validation is not supported for country: {countries}.
Direct tax id validation is not supported for countries: {country1}, {country2}. | false |\n| `TAX_IDENTIFICATION_NUMBER_TYPE_NOT_SUPPORTED` | 422 | Unsupported tax identification number type: {type}. Must be one of: business, individual | false |\n| `UNSUPPORTED_CSV_COLUMNS` | 422 | Unsupported column name \"{column}\" in csv header at index 0.
Unsupported column names \"{column1}\", \"{column2}\" in csv header at indexes [0, 1]. | false |\n| `CSV_FILE_NOT_PROVIDED` | 400 | CSV file not provided to multipart from data (field name: \"file\") | false |\n| `TIN_SEARCH_NOT_SUPPORTED_FOR_SUBSCRIPTION` | 400 | Tin search is not supported for this subscription. | false |\n| `INVALID_FIELD_FORMAT` | 422 | The field '{field}' has an invalid format. It {formatRequirement}. | false |\n| `CANNOT_HAVE_MORE_THAN_X_SEARCHES` | 400 | Request should not have more than 50000 searches, current request have {currentLength}. | false |\n| `TIN_SEARCH_QUERY_LENGTH_INVALID` | 400, 422 | The query length of '0' for country '{countryIso}' did not meet the minimum query length of '3' characters. | false |\n| `CANNOT_REQUEST_MORE_THAN_X_RESULTS` | 400 | Request should not have more than 1000 requested as limit/page size query parameter, current request have 1001 as query parameter. | false |\n| `US_UNSUPPORTED_PARAMETER_FOR_INDIVIDUAL` | 422 | US individual validation can't contain 'name' parameter used for businesses | false |\n| `US_BOTH_FIRST_LAST_NAME_REQUIRED` | 422 | US individual online validation requires both 'first_name' and 'last_name' parameters | false |\n| `US_UNSUPPORTED_PARAMETER_FOR_BUSINESS` | 422 | US business validation can't contain 'first_name' or 'last_name' parameter used for individuals | false |\n| `TIN_SEARCH_WORD_COUNT_INVALID` | 400, 422 | The word count of '6' in the query for country '{countryIso}' did not meet the maximum word count requirement of '5' words. | false |\n| `CANNOT_HAVE_MORE_THAN_X_RESULTS` | 400 | Response can carry up to 1000 validations, current request will have 1001. | false |",
"enum": [
"CURSOR_PARSING_ERROR",
"INVALID_ID_ERROR",
"INTERNAL_ERROR",
"NO_VALIDATION_FOUND",
"NO_BATCH_FOUND",
"TIN_SEARCH_NOT_FOUND",
"AUTHENTICATION_ERROR",
"MISSING_QUERY_OR_COUNTRY_ISO_CODE",
"MISSING_TAX_IDENTIFICATION_NUMBER_OR_COUNTRY_ISO_CODE",
"CANNOT_HAVE_ZERO_ENTRIES",
"INVALID_MIME_ONLY_FORM_DATA_IS_VALID",
"INVALID_MIME_ONLY_JSON_IS_VALID",
"VALIDATIONS_AMOUNT_EXCEEDED",
"COUNTRIES_NOT_ALLOWED",
"CANNOT_HAVE_MORE_THAN_X_TINS",
"COUNTRY_NOT_SUPPORTED",
"BATCH_REQUEST_CANNOT_BE_EMPTY",
"CSV_COLUMN_MISMATCH_ERROR",
"CSV_GENERIC_PARSING_ERROR",
"INVALID_VALIDATION_DATABASE_SOURCE",
"VALIDATION_SOURCE_NOT_SUPPORTED_FOR_COUNTRY",
"CSV_COUNTRY_CODE_FORMAT_ERROR",
"UNSUPPORTED_PARAMETER_ERROR",
"INVALID_REQUEST",
"DIRECT_TAX_ID_NOT_SUPPORTED",
"TAX_IDENTIFICATION_NUMBER_TYPE_NOT_SUPPORTED",
"UNSUPPORTED_CSV_COLUMNS",
"CSV_FILE_NOT_PROVIDED",
"TIN_SEARCH_NOT_SUPPORTED_FOR_SUBSCRIPTION",
"INVALID_FIELD_FORMAT",
"CANNOT_HAVE_MORE_THAN_X_SEARCHES",
"TIN_SEARCH_QUERY_LENGTH_INVALID",
"CANNOT_REQUEST_MORE_THAN_X_RESULTS",
"US_UNSUPPORTED_PARAMETER_FOR_INDIVIDUAL",
"US_BOTH_FIRST_LAST_NAME_REQUIRED",
"US_UNSUPPORTED_PARAMETER_FOR_BUSINESS",
"TIN_SEARCH_WORD_COUNT_INVALID",
"CANNOT_HAVE_MORE_THAN_X_RESULTS"
],
"x-error-codes": [
{
"code": "CURSOR_PARSING_ERROR",
"messages": [
"Cursor cannot be parsed."
],
"httpStatuses": [
400
],
"retryable": false
},
{
"code": "INVALID_ID_ERROR",
"messages": [
"Invalid 'id'."
],
"httpStatuses": [
400
],
"retryable": false
},
{
"code": "INTERNAL_ERROR",
"messages": [
"Something went wrong."
],
"httpStatuses": [
500
],
"retryable": true
},
{
"code": "NO_VALIDATION_FOUND",
"messages": [
"Validation cannot be found."
],
"httpStatuses": [
404
],
"retryable": false
},
{
"code": "NO_BATCH_FOUND",
"messages": [
"Batch cannot be found."
],
"httpStatuses": [
404
],
"retryable": false
},
{
"code": "TIN_SEARCH_NOT_FOUND",
"messages": [
"TIN search cannot be found."
],
"httpStatuses": [
404
],
"retryable": false
},
{
"code": "AUTHENTICATION_ERROR",
"messages": [
"Unauthorized request."
],
"httpStatuses": [
401
],
"retryable": false
},
{
"code": "MISSING_QUERY_OR_COUNTRY_ISO_CODE",
"messages": [
"Incorrect CSV format, missing 'query' or 'country_iso_code'."
],
"httpStatuses": [
422
],
"retryable": false
},
{
"code": "MISSING_TAX_IDENTIFICATION_NUMBER_OR_COUNTRY_ISO_CODE",
"messages": [
"Incorrect CSV format, missing 'tax_identification_number' or 'country_iso_code'."
],
"httpStatuses": [
422
],
"retryable": false
},
{
"code": "CANNOT_HAVE_ZERO_ENTRIES",
"messages": [
"Number of entries cannot be zero."
],
"httpStatuses": [
422
],
"retryable": false
},
{
"code": "INVALID_MIME_ONLY_FORM_DATA_IS_VALID",
"messages": [
"Invalid mime type, valid mime type is 'multipart/form-data'."
],
"httpStatuses": [
415
],
"retryable": false
},
{
"code": "INVALID_MIME_ONLY_JSON_IS_VALID",
"messages": [
"Invalid mime type, valid mime type is 'application/json'."
],
"httpStatuses": [
415
],
"retryable": false
},
{
"code": "VALIDATIONS_AMOUNT_EXCEEDED",
"messages": [
"Your subscription has run out of available validations. Max number: {max}, remaining number: {remaining}, number of validations in request: {inRequest}."
],
"httpStatuses": [
400
],
"retryable": false
},
{
"code": "COUNTRIES_NOT_ALLOWED",
"messages": [
"Your subscription does not allow you to validate the next countries: {countries}."
],
"httpStatuses": [
400
],
"retryable": false
},
{
"code": "CANNOT_HAVE_MORE_THAN_X_TINS",
"messages": [
"Request should not have more than 50000 tins, current request have {currentLength}."
],
"httpStatuses": [
400
],
"retryable": false
},
{
"code": "COUNTRY_NOT_SUPPORTED",
"messages": [
"Country '{unsupportedCountry}' not supported.",
"Countries '{country1}', '{country2}' not supported."
],
"httpStatuses": [
400,
422
],
"retryable": false
},
{
"code": "BATCH_REQUEST_CANNOT_BE_EMPTY",
"messages": [
"Batch request cannot be empty."
],
"httpStatuses": [
400
],
"retryable": false
},
{
"code": "CSV_COLUMN_MISMATCH_ERROR",
"messages": [
"CSV has more columns than expected."
],
"httpStatuses": [
422
],
"retryable": false
},
{
"code": "CSV_GENERIC_PARSING_ERROR",
"messages": [
"CSV cannot be parsed."
],
"httpStatuses": [
422
],
"retryable": false
},
{
"code": "INVALID_VALIDATION_DATABASE_SOURCE",
"messages": [
"Invalid validation database source: {source}."
],
"httpStatuses": [
422
],
"retryable": false
},
{
"code": "VALIDATION_SOURCE_NOT_SUPPORTED_FOR_COUNTRY",
"messages": [
"Validation source '{source}' not supported for country '{countryIso}'.",
"Validation source requested is not supported for countries: {countryIso} ({source})."
],
"httpStatuses": [
400
],
"retryable": false
},
{
"code": "CSV_COUNTRY_CODE_FORMAT_ERROR",
"messages": [
"CSV contains invalid country format. Country column should contain 2-letter country codes."
],
"httpStatuses": [
422
],
"retryable": false
},
{
"code": "UNSUPPORTED_PARAMETER_ERROR",
"messages": [
"Additional parameter \"{parameter}\" not supported for country \"{countryIso}\"."
],
"httpStatuses": [
422
],
"retryable": false
},
{
"code": "INVALID_REQUEST",
"messages": [
"Invalid request.",
"Validation is still running and cannot be deleted.",
"Batch contains validation/s that are still running and cannot be deleted.",
"Validation belongs to a batch and cannot be deleted."
],
"httpStatuses": [
400,
413
],
"retryable": false
},
{
"code": "DIRECT_TAX_ID_NOT_SUPPORTED",
"messages": [
"Direct tax id validation is not supported for country: {countries}.",
"Direct tax id validation is not supported for countries: {country1}, {country2}."
],
"httpStatuses": [
400,
422
],
"retryable": false
},
{
"code": "TAX_IDENTIFICATION_NUMBER_TYPE_NOT_SUPPORTED",
"messages": [
"Unsupported tax identification number type: {type}. Must be one of: business, individual"
],
"httpStatuses": [
422
],
"retryable": false
},
{
"code": "UNSUPPORTED_CSV_COLUMNS",
"messages": [
"Unsupported column name \"{column}\" in csv header at index 0.",
"Unsupported column names \"{column1}\", \"{column2}\" in csv header at indexes [0, 1]."
],
"httpStatuses": [
422
],
"retryable": false
},
{
"code": "CSV_FILE_NOT_PROVIDED",
"messages": [
"CSV file not provided to multipart from data (field name: \"file\")"
],
"httpStatuses": [
400
],
"retryable": false
},
{
"code": "TIN_SEARCH_NOT_SUPPORTED_FOR_SUBSCRIPTION",
"messages": [
"Tin search is not supported for this subscription."
],
"httpStatuses": [
400
],
"retryable": false
},
{
"code": "INVALID_FIELD_FORMAT",
"messages": [
"The field '{field}' has an invalid format. It {formatRequirement}."
],
"httpStatuses": [
422
],
"retryable": false
},
{
"code": "CANNOT_HAVE_MORE_THAN_X_SEARCHES",
"messages": [
"Request should not have more than 50000 searches, current request have {currentLength}."
],
"httpStatuses": [
400
],
"retryable": false
},
{
"code": "TIN_SEARCH_QUERY_LENGTH_INVALID",
"messages": [
"The query length of '0' for country '{countryIso}' did not meet the minimum query length of '3' characters."
],
"httpStatuses": [
400,
422
],
"retryable": false
},
{
"code": "CANNOT_REQUEST_MORE_THAN_X_RESULTS",
"messages": [
"Request should not have more than 1000 requested as limit/page size query parameter, current request have 1001 as query parameter."
],
"httpStatuses": [
400
],
"retryable": false
},
{
"code": "US_UNSUPPORTED_PARAMETER_FOR_INDIVIDUAL",
"messages": [
"US individual validation can't contain 'name' parameter used for businesses"
],
"httpStatuses": [
422
],
"retryable": false
},
{
"code": "US_BOTH_FIRST_LAST_NAME_REQUIRED",
"messages": [
"US individual online validation requires both 'first_name' and 'last_name' parameters"
],
"httpStatuses": [
422
],
"retryable": false
},
{
"code": "US_UNSUPPORTED_PARAMETER_FOR_BUSINESS",
"messages": [
"US business validation can't contain 'first_name' or 'last_name' parameter used for individuals"
],
"httpStatuses": [
422
],
"retryable": false
},
{
"code": "TIN_SEARCH_WORD_COUNT_INVALID",
"messages": [
"The word count of '6' in the query for country '{countryIso}' did not meet the maximum word count requirement of '5' words."
],
"httpStatuses": [
400,
422
],
"retryable": false
},
{
"code": "CANNOT_HAVE_MORE_THAN_X_RESULTS",
"messages": [
"Response can carry up to 1000 validations, current request will have 1001."
],
"httpStatuses": [
400
],
"retryable": false
}
]
},
"LookupErrorDetail": {
"title": "LookupErrorDetail",
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/LookupRequestErrorCode"
},
"message": {
"type": "string"
},
"details": {
"$ref": "#/components/schemas/LookupDetailedErrorMessage"
}
}
},
"LookupTinType": {
"type": "string",
"title": "LookupTinType",
"description": "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. \n\nThis field is not yet supported for all countries.",
"x-examples": {},
"enum": [
"individual",
"business"
]
},
"LookupFoundInOfficialDatabase": {
"type": "string",
"enum": [
"yes",
"no",
"unknown",
"not_applicable"
],
"title": "LookupFoundInOfficialDatabase",
"description": "This field allows you to state whether the tax identification number provided was found in the official database."
},
"LookupTaxRegistered": {
"type": "string",
"enum": [
"yes",
"no",
"unknown",
"not_applicable"
],
"title": "LookupTaxRegistered",
"description": "Specifies whether the TIN was identified in a given government database and whether this identified TIN is currently registered for VAT/GST."
},
"LookupFormatValidV2": {
"type": "string",
"enum": [
"valid",
"invalid"
],
"description": "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)"
},
"LookupTin": {
"type": "string",
"description": "Tax Identification Number (VAT ID, GST ID, etc.) expressed as a string",
"example": "100070008"
},
"LookupExtraFieldsV1": {
"type": "object",
"x-stoplight": {
"id": "dc3d89d2b407b"
},
"x-examples": {
"Brazil fantasy name": {
"brazil_fantasy_name": "BAR E LANCHES 111"
},
"Canada federal state": {
"canada_federal_state": "Federal"
},
"Colombia check digit": {
"colombia_check_digit": "9"
},
"Colombia large taxpayer": {
"colombia_large_taxpayer": "yes"
},
"Colombia tin without check digit": {
"colombia_tin_without_check_digit": "123456789"
},
"Germany federal state": {
"germany_federal_state": "Berlin"
},
"Hungary full tax identification number": {
"hungary_full_tax_identification_number": "13353298-2-44"
},
"Japan qualified invoice issuer": {
"japan_qualified_invoice_issuer": "yes"
},
"USA IRS response": {
"usa_irs_response": "TIN and Name combination does not match IRS records."
}
},
"description": "Contains country-specific fields (API V1).",
"properties": {
"brazil_fantasy_name": {
"type": "string",
"example": "BAR E LANCHES 111",
"description": "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": {
"type": "string",
"example": "Federal",
"description": "This optional field indicates the Canada federal state (ex. Quebec)."
},
"colombia_check_digit": {
"type": "string",
"example": "9",
"description": "This optional field represents check digit for the provided tax identification number."
},
"colombia_large_taxpayer": {
"type": "string",
"enum": [
"yes",
"no"
],
"example": "yes",
"description": "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": {
"type": "string",
"example": "123456789",
"description": "This optional field represents tax identification number without last check digit."
},
"egypt_uin_expiry_date": {
"type": "string",
"x-stoplight": {
"id": "zr16avkx3uxx6"
},
"description": "It provides UIN expiry date in 'YYYY-MM-DD' format for Egyptian tax ID validation.",
"example": "2010-10-10"
},
"germany_federal_state": {
"type": "string",
"example": "Berlin",
"description": "This optional field indicates the Germany Federal State based on STNR 13 digit tin format."
},
"hungary_full_tax_identification_number": {
"type": "string",
"example": "13353298-2-44",
"description": "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": {
"x-stoplight": {
"id": "bmssxggrss43i"
},
"enum": [
"yes",
"no"
],
"description": "This field indicates the e-invoicing status of the validated TIN in India."
},
"india_gstin_status": {
"type": "string",
"x-stoplight": {
"id": "2d0exdkji4bfe"
},
"description": "This field indicates whether the GSTIN is active, cancelled or suspended in India. Example values: \"Active\", \"Cancelled\", \"Suspended\"."
},
"india_pan_name_match": {
"x-stoplight": {
"id": "652n0d8rx96zh"
},
"enum": [
"yes",
"no"
],
"description": "This field indicates if the sent name matches PAN (available for India PAN validation only)."
},
"india_pan_date_match": {
"x-stoplight": {
"id": "kr7jzjyw6bnd4"
},
"enum": [
"yes",
"no"
],
"description": "This field indicates if the sent date matches PAN (available for India PAN validation only)."
},
"india_pan_aadhaar_linked": {
"type": "string",
"enum": [
"yes",
"no",
"not_applicable"
],
"example": "not_applicable",
"description": "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.",
"x-stoplight": {
"id": "mtkuhzuv67hg7"
}
},
"india_pan_specified_person": {
"type": "string",
"enum": [
"yes",
"no"
],
"example": "no",
"description": "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).",
"x-stoplight": {
"id": "1qnghn3p3atbb"
}
},
"india_trade_name": {
"type": "string",
"description": "This optional field indicates the trade name of a given business in India.",
"example": "ACME TRADE"
},
"japan_qualified_invoice_issuer": {
"type": "string",
"enum": [
"yes",
"no"
],
"example": "yes",
"description": "This field indicates whether the validated TIN belongs to a company eligible to issue qualified e-invoices in Japan."
},
"mexico_taxpayer_can_receive_einvoices": {
"x-stoplight": {
"id": "4x60l4xap0bkk"
},
"enum": [
"yes",
"no"
],
"description": "This field indicates whether the validated TIN belongs to an entity eligible to receive e-invoices in Mexico."
},
"mexico_zip_code_used_for_validation": {
"type": "string",
"x-stoplight": {
"id": "u9imenfsnacry"
},
"description": "This field represents the cleaned ZIP Code used during the validation process. Only the first five digits of the provided ZIP Code are utilized.",
"example": "12345"
},
"usa_irs_response": {
"type": "string",
"x-stoplight": {
"id": "1ahyfbhw86obr"
},
"description": "This response field shows the TIN validation response of the United States Internal Revenue Service (IRS).",
"example": "TIN and Name combination does not match IRS records."
},
"usa_suggested_name": {
"type": "string",
"x-stoplight": {
"id": "anf4fe7dsmvp3"
},
"description": "This field provides name suggestions for cases when the name provided does not match the TIN provided according to the IRS's database."
}
}
},
"LookupExtraFieldsV2": {
"type": "object",
"description": "Contains country-specific fields (API V2).",
"allOf": [
{
"$ref": "#/components/schemas/LookupExtraFieldsV1"
},
{
"type": "object",
"properties": {
"italy_codice_fiscale_status": {
"type": "string",
"description": "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.",
"example": "Codice Fiscale valid"
},
"italy_vat_split_payment": {
"type": "string",
"enum": [
"yes",
"no"
],
"description": "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.",
"example": "no"
},
"brazil_status_detail": {
"type": "string",
"description": "This field provides detailed status information for Brazilian CNPJs based on the official registration status code. Available only via API validations.",
"example": "Active"
},
"brazil_cnae_code": {
"type": "string",
"description": "The principal CNAE (Economic Activity Classification) code for the Brazilian entity. Available only via API validations.",
"example": "6201500"
},
"brazil_cnae_description": {
"type": "string",
"description": "The description of the principal CNAE (Economic Activity Classification) for the Brazilian entity. Available only via API validations.",
"example": "Desenvolvimento de programas de computador sob encomenda"
},
"brazil_secondary_cnaes": {
"type": "array",
"description": "Secondary CNAE (Economic Activity Classification) codes for the Brazilian entity. Available only via API validations.",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "The secondary CNAE code",
"example": "6202300"
},
"description": {
"type": "string",
"description": "The description of the secondary CNAE",
"example": "Desenvolvimento e licenciamento de programas de computador customizaveis"
}
}
}
},
"brazil_municipality": {
"type": "string",
"description": "The municipality where the Brazilian entity has jurisdiction. Available only via API validations.",
"example": "SAO PAULO"
},
"brazil_federal_state": {
"type": "string",
"description": "The federal state (UF) where the Brazilian entity is located. Available only via API validations.",
"example": "SP"
},
"brazil_neighborhood": {
"type": "string",
"description": "The neighborhood (bairro) where the Brazilian entity is located. Available only via API validations.",
"example": "VILA OLIMPIA"
},
"brazil_company_size": {
"type": "string",
"description": "The registered size/classification of the Brazilian company according to the Federal Revenue. Available only via API validations.",
"example": "Demais"
},
"brazil_special_status": {
"type": "string",
"description": "Special status of the Brazilian entity if applicable (e.g., bankruptcy, judicial recovery). Available only via API validations.",
"example": "Recuperacao Judicial"
},
"brazil_special_status_date": {
"type": "string",
"format": "date",
"description": "The date when the special status was applied to the Brazilian entity. Available only via API validations.",
"example": "2023-01-15"
},
"brazil_date_of_birth": {
"type": "string",
"format": "date",
"description": "Date of birth for Brazilian individual taxpayers (CPF). Available only via API validations.",
"example": "1985-03-20"
},
"brazil_year_of_death": {
"type": "string",
"description": "Year of death for deceased Brazilian individual taxpayers (CPF). Available only via API validations.",
"example": "2020"
},
"brazil_suframa": {
"type": "object",
"description": "SUFRAMA (Superintendência da Zona Franca de Manaus) registration information for Brazilian entities. Available only via API validations.",
"properties": {
"number": {
"type": "string",
"description": "SUFRAMA registration number",
"example": "123456789"
},
"status": {
"type": "string",
"enum": [
"ACTIVE",
"INACTIVE",
"BLOCKED",
"CANCELED",
"CANCELED_AG_REC"
],
"description": "Current status of the SUFRAMA registration",
"example": "ACTIVE"
},
"registration_date": {
"type": "string",
"format": "date",
"description": "Date when the SUFRAMA registration was established",
"example": "2020-01-15"
}
}
},
"brazil_state_registrations": {
"type": "array",
"description": "State tax registrations (Inscrição Estadual) for Brazilian entities across different states. Available only via API validations.",
"items": {
"type": "object",
"properties": {
"number": {
"type": "string",
"description": "State registration number",
"example": "123456789"
},
"federal_state": {
"type": "string",
"description": "Federal state code",
"example": "SP"
},
"enabled": {
"type": "boolean",
"description": "Whether the state registration is currently enabled",
"example": true
},
"registration_date": {
"type": "string",
"format": "date",
"description": "Date of state registration",
"example": "2019-05-10"
},
"status": {
"type": "string",
"enum": [
"NO_RESTRICTION",
"BLOCKED",
"VEDADA"
],
"description": "Current status of the state registration",
"example": "NO_RESTRICTION"
},
"type": {
"type": "string",
"enum": [
"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"
],
"description": "Type of state registration",
"example": "IE_NORMAL"
}
}
}
},
"brazil_simples": {
"type": "object",
"description": "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.",
"properties": {
"optant": {
"type": "string",
"enum": [
"yes",
"no"
],
"description": "Whether the entity is currently opted into the Simples Nacional tax regime",
"example": "yes"
}
}
},
"company_representative_name": {
"type": "string",
"example": "John Doe",
"description": "This optional field indicates the official representative of the company."
},
"brazil_status_reason": {
"type": "string",
"description": "Reason for the current registration status of the Brazilian entity. Available only via API validations.",
"example": "Sem motivo"
},
"brazil_status_date": {
"type": "string",
"format": "date",
"description": "Date when the current registration status was set for the Brazilian entity. Available only via API validations.",
"example": "2019-01-01"
},
"brazil_address": {
"type": "object",
"description": "Detailed address information for Brazilian entities. Available only via API validations.",
"properties": {
"street": {
"type": "string",
"description": "Street name and type",
"example": "RUA EXEMPLO"
},
"number": {
"type": "string",
"description": "Street number",
"example": "123"
},
"additional_info": {
"type": "string",
"description": "Additional address information (complement)",
"example": "SALA 456"
},
"neighborhood": {
"type": "string",
"description": "Neighborhood (bairro)",
"example": "VILA OLIMPIA"
},
"city": {
"type": "string",
"description": "City name",
"example": "SAO PAULO"
},
"state": {
"type": "string",
"description": "State abbreviation",
"example": "SP"
},
"postal_code": {
"type": "string",
"description": "Postal code (CEP)",
"example": "04551065"
},
"country": {
"type": "string",
"description": "Country name",
"example": "BRASIL"
},
"country_code": {
"type": "string",
"description": "Country code",
"example": "076"
},
"city_code": {
"type": "string",
"description": "IBGE city code",
"example": "7107"
}
}
},
"brazil_legal_nature_code": {
"type": "string",
"description": "Legal nature code of the Brazilian entity according to IBGE classification. Available only via API validations.",
"example": "206-2"
},
"brazil_entity_social_capital": {
"type": "string",
"description": "Registered social capital of the Brazilian entity in Brazilian Reais. Available only via API validations.",
"example": "100000000"
},
"brazil_email": {
"type": "string",
"format": "email",
"description": "Official email address registered with the Brazilian Federal Revenue. Available only via API validations.",
"example": "contato@empresa.com.br"
},
"indonesia_name_match_tin": {
"enum": [
"yes",
"no"
],
"description": "This field indicates if the sent name matches NIK (available for Indonesia NIK validations)."
},
"indonesia_date_of_birth_match_tin": {
"enum": [
"yes",
"no"
],
"description": "This field indicates if the NIK contains correct date of birth information (available for Indonesia NIK validations)."
},
"business_activities": {
"type": "array",
"description": "A list of the business activities the entity is registered or authorized to perform.",
"items": {
"type": "object",
"properties": {
"activity": {
"type": "string",
"description": "A descriptive name of the business activity performed by the entity, based on the classification used by the local authority or registry.",
"example": "ACTIVIDADES DE CONSULTORIA DE INFORMATICA Y DE GESTION DE INSTALACIONE"
},
"code": {
"type": "string",
"description": "The official activity code assigned by the relevant authority or classification system. This code uniquely identifies the type of economic activity.",
"example": "620200"
},
"category": {
"type": "string",
"description": "The category or classification tier assigned to the activity, according to the applicable local or regulatory framework.",
"example": "Primera"
},
"subject_to_vat": {
"type": "string",
"enum": [
"yes",
"no",
"unknown",
"not_applicable"
],
"example": "yes",
"description": "Indicates whether this activity is subject to value-added tax (VAT)."
},
"registration_date": {
"type": "string",
"format": "date",
"description": "The date when this activity was officially registered, activated, or recognized by the relevant authority for regulatory or tax purposes.",
"example": "05-10-2015"
}
}
}
}
}
}
]
},
"LookupCountryIsoResponse": {
"type": "string",
"description": "Customer ISO 3166-1 alpha-2 country code",
"example": "cl"
},
"LookupCountryIsoRequest": {
"type": "string",
"description": "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)",
"example": "ee",
"enum": [
"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"
]
},
"LookupTinUsedForValidation": {
"type": "string",
"x-stoplight": {
"id": "rix0ciq5rdw85"
},
"description": "A tax identification number used to query the official database",
"title": ""
},
"LookupTinName": {
"type": "string",
"description": "Represents the full and abbreviated name of Tax Identification Number (TIN) provided by the user in the local language.",
"example": "Système d’Identification du Répertoire des Entreprises (SIREN)"
},
"LookupResponseValidationSourceV2": {
"title": "LookupResponseValidationSourceV2",
"enum": [
"vies",
"local",
"vies_and_local",
"not_available",
"fonoa_cache"
],
"description": "Validation source of the requested validation. \n\nIf validation source was provided in the request, Fonoa will return the same in the response.\n\nIf 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.\n\nIf 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.\n\nIf there were an issue where none of sources provided the result, we will return `not_available` as the source value.\n\nIf prefer_cached_result was set to true and a cached result was found in the Instant Lookup database, Fonoa will return fonoa_cache.\n",
"x-examples": {
"example-1": "vies"
},
"type": "string"
},
"LookupResponseIsBusiness": {
"title": "LookupResponseIsBusiness",
"enum": [
"yes",
"no",
"unknown",
"not_applicable"
],
"description": "Specifies whether the taxpayer is an individual, or a legal entity."
},
"LookupResponseBusinessStatus": {
"title": "LookupResponseBusinessStatus",
"enum": [
"active",
"inactive",
"unknown"
],
"description": "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.",
"x-examples": {
"example-1": "active"
},
"type": "string"
},
"LookupResponseLegalEntityType": {
"type": "string",
"description": "It represents the legal entity type of the taxpayer, the values depend on the country. Some examples:\n- Public Limited Company\n- Private Limited Company\n- Limited Liability Partnership\n- General Partnership\n- Joint Stock Company"
},
"LookupResponseRegistrationDate": {
"type": "string",
"example": "2017-07-20",
"format": "date",
"description": "Date at which the entity became registered for indirect tax as shown in the official database."
},
"LookupResponseDeRegistrationDate": {
"type": "string",
"example": "2017-07-20",
"format": "date",
"description": "Date at which the entity became deregistered for indirect tax as shown in the official database."
},
"LookupResponseAddress": {
"type": "string",
"example": "Tower A DLF Tower, 4th Floor, DLF INFINTY TOWER, Sector 25A, Gurugram, Haryana, 122002"
},
"LookupMaxRetryDuration": {
"type": "integer",
"minimum": 1,
"maximum": 48,
"description": "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.\n\nA 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.\n\nSmart retries are available for selected countries. For other countries the parameter is accepted, but the standard retry behavior applies.\n\nWhen omitted, the standard retry behavior applies.\n",
"example": 24
},
"LookupRequestExternalId": {
"type": "string",
"minLength": 1,
"description": "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."
},
"LookupResponseExternalId": {
"type": "string",
"minLength": 1,
"description": "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."
},
"LookupErrorResponseV2": {
"title": "LookupErrorResponseV2",
"type": "object",
"x-examples": {
"x-example-1": {
"errors": [
{
"code": "INVALID_REQUEST",
"message": "Invalid request.",
"details": [
{
"detailed_error_messages": [
{
"message": "\"page\" is not allowed"
}
]
}
]
}
]
}
},
"x-stoplight": {
"id": "59b1e70795039"
},
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LookupErrorDetail"
}
}
}
},
"LookupRequestValidationSource": {
"type": "string",
"description": "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.\n",
"enum": [
"vies",
"local"
],
"x-examples": {
"example-1": "vies"
}
},
"LookupFuzzyMatchingRequestV2": {
"title": "LookupFuzzyMatchingRequestV2",
"x-examples": {
"example with name and address": {
"name": "expected name",
"address": "expected address"
},
"example with name only": {
"name": "expected name"
}
},
"description": "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:\n- expected name `\"Fonoa Technologies\"` and actual `\"FONOA TECHNOLOGIES LIMITED\"` will produce `\"similarity_percentage\": 100`\n- expected address `\"12 Wildflower way Belfast\"` and actual `\"UNIT 5, 12 WILDFLOWER WAY, BELFAST, BT12 6TA\"` will produce `\"similarity_percentage\": 76`\n\nFuzzy matching uses transliteration to the Latin alphabet before running the algorithm, for example:\n- expected name `\"Lukoil\"` and actual `\"ПУБЛИЧНОЕ АКЦИОНЕРНОЕ ОБЩЕСТВО \\\"НЕФТЯНАЯ КОМПАНИЯ \\\"ЛУКОЙЛ\\\"\"` will produce `\"similarity_percentage\": 83` based on the transliteration of the actual name into the Latin alphabet",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "expected taxpayer name",
"example": "expected taxpayer name"
},
"address": {
"type": "string",
"description": "expected taxpayer address",
"example": "expected taxpayer address"
}
}
},
"LookupErrorDetailsResultV2": {
"title": "LookupErrorDetailsResultV2",
"type": "object",
"x-examples": {
"MX_NAME_MISMATCH": {
"error_details": [
{
"code": "MX_NAME_MISMATCH",
"message": "The taxpayer's name does not match with the one registered in the local database."
}
]
},
"MX_ZIPCODE_MISMATCH": {
"error_details": [
{
"code": "MX_ZIPCODE_MISMATCH",
"message": "The taxpayer's zip code does not coincide with the one registered in the local database."
}
]
},
"MX_NAME_AND_ZIPCODE_MISMATCH": {
"error_details": [
{
"code": "MX_NAME_AND_ZIPCODE_MISMATCH",
"message": "The taxpayer's name and zip code does not match with the ones registered in the local database."
}
]
},
"TR_TIN_AND_TAX_OFFICE_MISMATCH": {
"error_details": [
{
"code": "TR_TIN_AND_TAX_OFFICE_MISMATCH",
"message": "The TIN and Tax Office do not match. Retry the validation with the correct Tax Office Code associated with the taxpayer."
}
]
},
"FORMAT_INVALID": {
"error_details": [
{
"code": "FORMAT_INVALID",
"message": "ABN should contain 11 digits, and ACN should contain 9 digits"
}
]
}
},
"properties": {
"code": {
"type": "string",
"enum": [
"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"
],
"description": "Error code"
},
"message": {
"type": "string",
"description": "Human-readable error message"
}
},
"required": [
"code",
"message"
],
"description": "Error details of validation.\n\nError codes:\n\nNETWORK_ERROR - Lookup experienced problems with online database, we could not find an answer for the request.\n\nTEMPORARY_UNAVAILABLE - The government TIN database is non-reachable due to planned maintenance.\n\nUNKNOWN_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.\n\nINCOMPLETE_IMPLEMENTATION - Cannot return the result due to insufficient or wrongly formatted data provided.\n\nONLINE_CHECK_NOT_SUPPORTED - Online validation is not supported for this TIN.\n\nMISSING_REQUIRED_INPUT - Missing {input-name}. Please include all required parameters to proceed with the validation.\n\nINVALID_REQUIRED_INPUT - Invalid {input-name}. Ensure all required parameters are correct before proceeding with the validation.\n\nMISSING_TAX_AUTHORITY_CREDENTIALS - Missing your company credentials for the Tax Authority. Contact support@fonoa.com for assistance with securely providing credentials.\n\nTAX_AUTHORITY_CREDENTIALS_REJECTED - The Tax Authority rejected your company credentials. Contact support@fonoa.com for assistance with securely providing valid credentials.\n\nTAX_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.\n\nMX_NAME_MISMATCH - The taxpayer's name does not coincide with the one registered in the local database (only for Mexico).\n\nMX_ZIPCODE_MISMATCH - The taxpayer's zip code does not coincide with the one registered in the local database (only for Mexico).\n\nMX_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).\n\nTR_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).\n\nFORMAT_INVALID - The provided TIN has an invalid format or checksum according to the selected country validation rules."
}
},
"securitySchemes": {
"Ocp-Apim-Subscription-Key": {
"type": "apiKey",
"description": "API Subscription Key",
"name": "Ocp-Apim-Subscription-Key",
"in": "header"
}
}
},
"security": [
{
"Ocp-Apim-Subscription-Key": []
}
],
"tags": [
{
"name": "Lookup V2"
}
]
}
```