---
updatedAt: 2026-04-27T15:06:30.000Z
agentTools:
projectIndex: https://docs.fonoa.com/llms.txt
---
# Get TIN search results
This endpoint returns the results of a previously submitted TIN search request. The `status` field indicates whether processing is complete:
- **"running"** — the search is still in progress; poll again later.
- **"completed"** — results are available in the `search.results` array.
# 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-searches/{id}": {
"get": {
"tags": [
"Lookup V2"
],
"summary": "Get TIN search results",
"description": "This endpoint returns the results of a previously submitted TIN search request. The `status` field indicates whether processing is complete:\n- **\"running\"** — the search is still in progress; poll again later.\n- **\"completed\"** — results are available in the `search.results` array.",
"operationId": "GetTinSearchResult",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The `tin_search_id` value returned by the POST /lookup/v2/single-searches response",
"required": true,
"style": "simple",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "The TIN search request was found. Check `status` to determine whether results are ready.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"status",
"search"
],
"properties": {
"status": {
"type": "string",
"enum": [
"running",
"completed"
]
},
"search": {
"$ref": "#/components/schemas/LookupTinSearchResponse"
}
}
},
"examples": {
"example-running": {
"value": {
"status": "running",
"search": {
"id": "b470a195-8e83-4d89-b4a7-4d389ac358a4",
"country_iso_code": "ie",
"query": "Fonoa Technologies",
"requested_at": "2024-01-15T10:30:00.000Z",
"results": []
}
}
},
"example-completed": {
"value": {
"status": "completed",
"search": {
"id": "b470a195-8e83-4d89-b4a7-4d389ac358a4",
"country_iso_code": "ie",
"query": "Fonoa Technologies",
"requested_at": "2024-01-15T10:30:00.000Z",
"results": [
{
"tin_search_result_id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
"name": "FONOA TECHNOLOGIES LIMITED",
"tax_registered": "yes",
"tax_identification_number": "IE3717232WH",
"tax_registration_type": "Registered",
"business_status": "active",
"legal_entity_type": "Limited Company",
"registration_date": "2019-06-01",
"address": "6TH FLOOR, SOUTH BANK HOUSE, BARROW STREET, DUBLIN 4",
"fuzzy_matching_similarity_score": 100,
"address_fuzzy_matching_similarity_score": 62,
"is_business": "yes"
}
]
}
}
}
}
}
}
},
"400": {
"description": "Bad Request (usually means the `id` format is invalid)",
"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": "TIN_SEARCH_NOT_FOUND",
"message": "TIN search 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."
}
]
}
}
}
}
}
}
},
"deprecated": false
},
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"name": "id",
"in": "path",
"description": "TIN search request ID",
"required": true
}
]
}
},
"components": {
"schemas": {
"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"
}
}
},
"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."
},
"LookupCountryIsoResponse": {
"type": "string",
"description": "Customer ISO 3166-1 alpha-2 country code",
"example": "cl"
},
"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"
}
}
}
},
"LookupTinSearchAdditionalParameters": {
"title": "LookupTinSearchAdditionalParameters",
"type": "object",
"description": "Optional parameters to refine a TIN search request.",
"properties": {
"address": {
"type": "string",
"description": "Address used to narrow the search and score address fuzzy matching.",
"example": "Barrow Street Dublin 4"
}
}
},
"LookupTinSearchResponse": {
"title": "LookupTinSearchResponse",
"type": "object",
"description": "Full TIN search response including results (available once status is \"completed\").",
"required": [
"id",
"country_iso_code",
"query",
"requested_at",
"results"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the TIN search request.",
"example": "b470a195-8e83-4d89-b4a7-4d389ac358a4"
},
"country_iso_code": {
"$ref": "#/components/schemas/LookupCountryIsoResponse"
},
"query": {
"type": "string",
"description": "The search query that was submitted.",
"example": "Fonoa Technologies"
},
"requested_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the search was requested.",
"example": "2024-01-15T10:30:00.000Z"
},
"additional_parameters": {
"$ref": "#/components/schemas/LookupTinSearchAdditionalParameters"
},
"external_id": {
"$ref": "#/components/schemas/LookupResponseExternalId"
},
"error_details": {
"type": "object",
"description": "Error details if the search encountered an error.",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
},
"results": {
"type": "array",
"description": "List of matching entities found by the search. Empty while the search is still running.",
"items": {
"$ref": "#/components/schemas/LookupTinSearchResult"
}
}
}
},
"LookupTinSearchResult": {
"title": "LookupTinSearchResult",
"type": "object",
"description": "A single result entry returned by a TIN search.",
"required": [
"tin_search_result_id",
"tax_registered"
],
"properties": {
"tin_search_result_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of this search result entry.",
"example": "d1e2f3a4-b5c6-7890-abcd-ef1234567890"
},
"name": {
"type": "string",
"description": "Registered name of the entity.",
"example": "FONOA TECHNOLOGIES LIMITED"
},
"tax_registered": {
"$ref": "#/components/schemas/LookupTaxRegistered"
},
"tax_identification_number": {
"type": "string",
"description": "Tax identification number of the entity.",
"example": "IE3717232WH"
},
"tax_registration_type": {
"$ref": "#/components/schemas/LookupResponseTaxRegistrationType"
},
"business_status": {
"$ref": "#/components/schemas/LookupResponseBusinessStatus"
},
"legal_entity_type": {
"$ref": "#/components/schemas/LookupResponseLegalEntityType"
},
"registration_date": {
"$ref": "#/components/schemas/LookupResponseRegistrationDate"
},
"deregistration_date": {
"$ref": "#/components/schemas/LookupResponseDeRegistrationDate"
},
"address": {
"$ref": "#/components/schemas/LookupResponseAddress"
},
"is_business": {
"$ref": "#/components/schemas/LookupResponseIsBusiness"
},
"fuzzy_matching_similarity_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 100,
"description": "Similarity score (0–100) between the search query and this result's name.",
"example": 100
},
"address_fuzzy_matching_similarity_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 100,
"description": "Similarity score (0–100) between the `additional_parameters.address` provided in the request and this result's address.",
"example": 62
},
"business_registration_number": {
"type": "string",
"description": "Company registration number (distinct from the TIN), if available.",
"example": "123456"
},
"additional_data": {
"$ref": "#/components/schemas/LookupTinSearchAdditionalData"
}
}
},
"LookupTinSearchAdditionalData": {
"title": "LookupTinSearchAdditionalData",
"type": "object",
"description": "Country-specific additional data fields returned alongside the TIN search result, if available.",
"properties": {
"france_siret": {
"type": "string",
"description": "SIRET number.",
"example": "73282932000074"
},
"italy_codice_fiscale": {
"type": "string",
"description": "Codice Fiscale.",
"example": "RSSMRA80A01H501U"
},
"italy_pec_address": {
"type": "string",
"description": "Certified email address.",
"example": "example@pec.it"
},
"brazil_fantasy_name": {
"type": "string",
"description": "Fantasy name.",
"example": "FONOA BRAZIL"
},
"colombia_check_digit": {
"type": "string",
"description": "Check digit appended to the NIT.",
"example": "7"
},
"colombia_large_taxpayer": {
"type": "string",
"description": "Large taxpayer classification.",
"example": "GRAN CONTRIBUYENTE"
},
"colombia_tin_without_check_digit": {
"type": "string",
"description": "NIT without its check digit.",
"example": "900123456"
}
}
}
},
"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"
}
]
}
```