---
updatedAt: 2026-04-27T13:18:01.000Z
agentTools:
projectIndex: https://docs.fonoa.com/llms.txt
---
# Get result of validation
This endpoint provides Tax Identification Number validation results. To access it you need to use the validation_id returned from the “Request a validation” endpoint. It consists of a validation results and status which can hold 3 states:
- **"completed"** - validation for that request finished.
- **"pending"** - 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.
# 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/single-validations/{id}": {
"get": {
"summary": "Get result of validation",
"description": "This endpoint provides Tax Identification Number validation results. To access it you need to use the validation_id returned from the “Request a validation” endpoint. It consists of a validation results and status which can hold 3 states:\n- **\"completed\"** - validation for that request finished.\n- **\"pending\"** - validation process for that request is still in progress, you should check its results again. \n- **\"canceled\"** - validation process for that request has been canceled by user when validation is part of canceled batch validation.",
"operationId": "GetresultofvalidationV2",
"parameters": [
{
"name": "id",
"in": "path",
"description": "An \"id\" value from the validation request response body",
"required": true,
"style": "simple",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The validation request completed. Check the contents to get its result.",
"headers": {},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"status",
"validation"
],
"properties": {
"status": {
"$ref": "#/components/schemas/LookupValidationStatusResult"
},
"validation": {
"$ref": "#/components/schemas/LookupTinValidationResponseV2"
}
}
},
"examples": {
"example-1": {
"value": {
"status": "completed",
"validation": {
"validation_id": "a350e7c7-358e-4f96-b77e-9e13b3c5c338",
"country_iso_code": "ie",
"tax_identification_number": "IE3717232WH",
"name": "FONOA TECHNOLOGIES LIMITED",
"format": "valid",
"requested_at": "2022-08-03T12:00:18.057Z",
"found_in_official_database": "yes",
"tax_registered": "yes",
"is_business": "yes",
"business_status": "active",
"validation_database_source": "vies",
"address": "6TH FLOOR, SOUTH BANK HOUSE, BARROW STREET, DUBLIN 4",
"fuzzy_matching": {
"name": {
"expected": "Fonoa Technologies",
"matched_field": "name",
"similarity_percentage": 100
},
"address": {
"expected": "Barrow street Dublin 4",
"similarity_percentage": 62
}
}
}
}
},
"example-2": {
"value": {
"status": "completed",
"validation": {
"validation_id": "86d95104-7e3c-4cdf-8e1f-a1b2d4ce62da",
"country_iso_code": "au",
"tax_identification_number": "123",
"format": "invalid",
"requested_at": "2022-08-03T12:00:18.057Z",
"found_in_official_database": "unknown",
"tax_registered": "unknown",
"validation_database_source": "not_available",
"business_status": "active",
"is_business": "unknown",
"error_details": {
"code": "FORMAT_INVALID",
"message": "ABN should contain 11 digits, and ACN should contain 9 digits"
}
}
}
}
}
}
}
},
"400": {
"description": "Bad Request (usually means that the request model validation failed)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LookupErrorResponseV2"
},
"examples": {
"example-1": {
"value": {
"errors": [
{
"code": "INVALID_ID_ERROR",
"message": "Invalid 'id'."
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LookupErrorResponseV2"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LookupErrorResponseV2"
},
"examples": {
"example-1": {
"value": {
"errors": [
{
"code": "NO_VALIDATION_FOUND",
"message": "Validation cannot be found."
}
]
}
}
}
}
}
},
"500": {
"description": "Internal Server Error",
"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",
"content": {
"application/json": {
"schema": {}
}
}
}
},
"deprecated": false,
"tags": [
"Lookup V2"
]
},
"parameters": [
{
"schema": {
"type": "string"
},
"name": "id",
"in": "path",
"description": "Single validation ID",
"required": true
}
]
}
},
"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"
}
}
},
"LookupTinValidationResponseV2": {
"title": "LookupTinValidationResponseV2",
"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.",
"matched_field": "name",
"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": {
"type": "string",
"description": "A provided TIN number",
"example": "123123"
},
"tax_identification_number_type": {
"$ref": "#/components/schemas/LookupTinType"
},
"country_iso_code": {
"$ref": "#/components/schemas/LookupCountryIsoResponse"
},
"format": {
"$ref": "#/components/schemas/LookupFormatValidV2"
},
"found_in_official_database": {
"$ref": "#/components/schemas/LookupFoundInOfficialDatabase"
},
"tax_registered": {
"$ref": "#/components/schemas/LookupTaxRegistered"
},
"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"
},
"name": {
"type": "string",
"description": "A name acquired from online database",
"example": "ACME"
},
"business_status": {
"$ref": "#/components/schemas/LookupResponseBusinessStatus"
},
"address": {
"$ref": "#/components/schemas/LookupResponseAddress"
},
"tax_registration_type": {
"$ref": "#/components/schemas/LookupResponseTaxRegistrationType"
},
"registration_date": {
"$ref": "#/components/schemas/LookupResponseRegistrationDate"
},
"de_registration_date": {
"$ref": "#/components/schemas/LookupResponseDeRegistrationDate"
},
"legal_entity_type": {
"$ref": "#/components/schemas/LookupResponseLegalEntityType"
},
"fuzzy_matching": {
"$ref": "#/components/schemas/LookupFuzzyMatchingResponseV2"
},
"external_id": {
"$ref": "#/components/schemas/LookupResponseExternalId"
},
"error_details": {
"$ref": "#/components/schemas/LookupErrorDetailsResultV2"
},
"extra_fields": {
"$ref": "#/components/schemas/LookupExtraFieldsV2"
},
"additional_parameters": {
"$ref": "#/components/schemas/LookupAdditionalParametersV2"
},
"tax_identification_number_used_for_validation": {
"$ref": "#/components/schemas/LookupTinUsedForValidation"
},
"tax_identification_number_name": {
"$ref": "#/components/schemas/LookupTinName"
}
},
"required": [
"validation_id",
"tax_identification_number",
"country_iso_code",
"format",
"found_in_official_database",
"tax_registered",
"requested_at",
"is_business",
"validation_database_source",
"business_status"
]
},
"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)"
},
"LookupValidationStatusResult": {
"type": "string",
"enum": [
"completed",
"pending",
"canceled"
]
},
"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"
},
"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"
},
"LookupResponseTaxRegistrationType": {
"type": "string",
"enum": [
"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",
"Aquis. Intracom. por Opção",
"Micro",
"Small",
"Medium",
"Large"
],
"description": "Type of tax registration."
},
"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"
},
"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"
}
}
}
},
"LookupFuzzyMatchingResponseV2": {
"title": "LookupFuzzyMatchingResponseV2",
"type": "object",
"x-examples": {
"example with name and address": {
"name": {
"expected": "Fonoa Technologies",
"matched_field": "name",
"similarity_percentage": 100
},
"address": {
"expected": "Barrow street Dublin 4",
"similarity_percentage": 62
}
},
"example with name only": {
"name": {
"expected": "Fonoa Technologies",
"matched_field": "name",
"similarity_percentage": 100
}
},
"example with no data available": {
"address": {
"expected": "expected address",
"error": "DATA_NOT_FOUND"
}
}
},
"description": "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\"`. ",
"properties": {
"name": {
"$ref": "#/components/schemas/LookupFuzzyMatchingNameResultV2"
},
"address": {
"$ref": "#/components/schemas/LookupFuzzyMatchingResultV2"
}
}
},
"LookupFuzzyMatchingResultV2": {
"title": "LookupFuzzyMatchingResultV2",
"type": "object",
"x-examples": {
"successful example": {
"expected": "Fonoa Technologies",
"similarity_percentage": 100
},
"error example": {
"expected": "Fonoa Technologies",
"error": "DATA_NOT_FOUND"
}
},
"properties": {
"expected": {
"type": "string",
"description": "Requested expected value",
"example": "company name"
},
"similarity_percentage": {
"type": "number",
"description": "Result in percentage 0-100 (integer)",
"example": 100
},
"error": {
"type": "string",
"enum": [
"DATA_NOT_FOUND"
],
"description": "Optional error field when can't get similarity percentage"
}
},
"required": [
"expected"
]
},
"LookupFuzzyMatchingNameResultV2": {
"title": "LookupFuzzyMatchingNameResultV2",
"allOf": [
{
"$ref": "#/components/schemas/LookupFuzzyMatchingResultV2"
},
{
"type": "object",
"x-examples": {
"successful example": {
"expected": "Fonoa Technologies",
"matched_field": "name",
"similarity_percentage": 100
},
"error example": {
"expected": "Fonoa Technologies",
"error": "DATA_NOT_FOUND"
}
},
"properties": {
"matched_field": {
"type": "string",
"description": "Field from the official source that produced the reported name similarity score. This is `name` (the legal name) or, for Brazilian entities, `brazil_fantasy_name` (the fantasy name, returned in `country_specific.fantasy_name`). Brazilian fantasy-name matching is skipped when `match_legal_name_only` is `true`.",
"example": "name"
}
}
}
]
},
"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"
}
]
}
```