--- updatedAt: 2026-04-27T13:18:01.000Z agentTools: projectIndex: https://docs.fonoa.com/llms.txt --- # Find a tax identification number This endpoint allows you to request a validation of the Tax Identification Number and get the response instantly. In order to do so, our system needs a country of the client (ISO code) and a tax identification number of the client. # 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": { "/instant-lookup/v1/find": { "post": { "summary": "Find a tax identification number", "description": "This endpoint allows you to request a validation of the Tax Identification Number and get the response instantly. In order to do so, our system needs a country of the client (ISO code) and a tax identification number of the client.", "tags": [ "Instant Lookup" ], "operationId": "FindTIN", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "country_iso_code", "tax_identification_number" ], "properties": { "country_iso_code": { "$ref": "#/components/schemas/ILookupCountryIso" }, "tax_identification_number": { "$ref": "#/components/schemas/LookupTin" }, "fuzzy_matching": { "type": "object", "description": "Fuzzy matching compares expected tax payer name with actual value to provide you with a similarity score in the form of a percentage. Examples:\n- expected name `\"Fonoa Technologies\"` and actual `\"FONOA TECHNOLOGIES LIMITED\"` will produce `\"similarity_percentage\": 100`", "properties": { "name": { "type": "string", "description": "Expected taxpayer name" }, "match_legal_name_only": { "type": "boolean", "default": false, "description": "When `true`, the expected name is compared only with the legal name. When `false` or omitted, alternative names (currently the Brazilian fantasy name) are also compared and the best score is returned. Requires `name`." } } } } }, "examples": { "standard": { "summary": "Request TIN data", "value": { "country_iso_code": "pt", "tax_identification_number": "pt515175765" } }, "fuzzy_matching": { "summary": "Request TIN data with fuzzy matching score", "value": { "country_iso_code": "pt", "tax_identification_number": "pt515175765", "fuzzy_matching": { "name": "ACME" } } }, "fuzzy_matching_legal_name_only": { "summary": "Request Brazil TIN data with fuzzy matching on the legal name only", "value": { "country_iso_code": "br", "tax_identification_number": "00000000000000", "fuzzy_matching": { "name": "ACME", "match_legal_name_only": true } } } } } } }, "responses": { "200": { "description": "The requested TIN was found in our database.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ILookupResponse" }, "examples": { "caseTinFoundInDB": { "summary": "Response for TIN found in official DB", "value": { "found_tax_identification_number": "PT500000158", "found_in_official_database": "yes", "tax_registered": "yes", "format": "valid", "name": "ACME CO.", "business_status": "active", "is_business": "yes", "last_updated": "2025-03-06 15:28:40.253" } }, "caseTinFoundInDBWithFuzzyScore": { "summary": "Response for TIN found in official DB when fuzzy matching score requested", "value": { "found_tax_identification_number": "PT500000158", "found_in_official_database": "yes", "tax_registered": "yes", "format": "valid", "name": "ACME CO.", "fuzzy_matching": { "name": { "expected": "ACME", "similarity_percentage": 90, "matched_field": "name" } }, "business_status": "active", "is_business": "yes", "last_updated": "2025-03-06T15:28:40.253" } }, "caseTinNotFoundInDB": { "summary": "Response for TIN not found in official DB", "value": { "format": "valid", "found_in_official_database": "no", "last_updated": "2025-01-28T14:13:37.605Z" } }, "caseTinWrongFormat": { "summary": "Response for TIN with wrong format", "value": { "format": "not_valid", "errors": [ { "code": "TIN_WRONG_FORMAT", "message": "provided tin is in wrong format" } ] } }, "caseTinOnlineValidationNotAvailable": { "summary": "Response for TIN online validation not available at this time", "value": { "errors": [ { "code": "TIN_ONLINE_VALIDATION_NOT_AVAILABLE_AT_THIS_TIME", "message": "The provided Tax Identification Number could not be validated online at this time in the official source. Please try again later." } ] } } } } } }, "202": { "description": "The requested TIN was not found in our database, Lookup request is initiated, result is pending.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "running" ] }, "format": { "type": "string", "enum": [ "valid" ] } } } } } }, "400": { "description": "Bad request due to various reasons like unsupported country, individual TIN, wrong JSON format, wrong query parameters...", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ILookupErrorItem" } } } }, "examples": { "caseWrongFormat": { "summary": "Json was in wrong format", "value": { "errors": [ { "code": "WRONG_FORMAT", "message": "json request could not be read" } ] } }, "caseCountryNotSupported": { "summary": "Provided country is not supported", "value": { "errors": [ { "code": "COUNTRY_NOT_SUPPORTED", "message": "the provided country is not supported" } ] } }, "caseIndividualNotSupported": { "summary": "Individual is not supported", "value": { "errors": [ { "code": "INDIVIDUAL_NOT_SUPPORTED", "message": "the tax number belongs to an individual; not supported" } ] } } } } } } } } } }, "components": { "schemas": { "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." }, "ILookupFormat": { "type": "string", "x-stoplight": { "id": "3ea8806009ba5" }, "enum": [ "valid", "not_valid" ], "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" }, "LookupCompanyName": { "type": "string", "description": "A company name acquired from online database", "example": "ACME" }, "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" }, "ILookupResponse": { "type": "object", "x-stoplight": { "id": "8c7cc6ae6f006" }, "properties": { "found_tax_identification_number": { "type": "string" }, "found_in_official_database": { "type": "string", "description": "Whether the TIN was found in the official database. For Brazil CPF validations, \"unknown\" indicates the CPF may exist but the provided date of birth did not match the government records (DOB mismatch, only possible when `date` is sent), as distinct from \"no\" which means the CPF itself is invalid.", "enum": [ "yes", "no", "unknown" ] }, "tax_registered": { "$ref": "#/components/schemas/LookupTaxRegistered" }, "format": { "$ref": "#/components/schemas/ILookupFormat" }, "name": { "$ref": "#/components/schemas/LookupCompanyName" }, "fuzzy_matching": { "$ref": "#/components/schemas/ILookupFuzzyMatchingResult" }, "business_status": { "$ref": "#/components/schemas/LookupResponseBusinessStatus" }, "is_business": { "$ref": "#/components/schemas/LookupResponseIsBusiness" }, "legal_entity_type": { "$ref": "#/components/schemas/LookupResponseLegalEntityType" }, "registration_type": { "$ref": "#/components/schemas/LookupResponseTaxRegistrationType" }, "registration_date": { "$ref": "#/components/schemas/LookupResponseRegistrationDate" }, "de_registration_date": { "$ref": "#/components/schemas/LookupResponseDeRegistrationDate" }, "address": { "$ref": "#/components/schemas/LookupResponseAddress" }, "tax_registered_in_vies": { "$ref": "#/components/schemas/ILookupResponseTaxRegisteredInVies" }, "country_specific": { "type": "object" }, "last_updated": { "type": "string", "format": "date-time", "description": "Date at which the entity was last checked against official source and updated.", "example": "2025-01-28T14:13:37.605Z" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ILookupErrorItem" } } } }, "ILookupCountryIso": { "type": "string", "description": "- Country code in ISO 3166-1 alpha-2 format of the company whose TIN is being validated (e.g., `pt` for Portugal)", "example": "br", "enum": [ "pt", "br", "be", "pl", "fr", "co", "de", "es" ] }, "ILookupFuzzyMatchingResult": { "type": "object", "description": "This signifies the result of a fuzzy matching request. It contains requested/expected value and the similarity score in the form of a percentage.", "properties": { "name": { "type": "object", "properties": { "expected": { "type": "string", "description": "Requested expected taxpayer name" }, "similarity_percentage": { "type": "integer", "description": "Result in percentage 0-100 (integer)" }, "matched_field": { "type": "string", "description": "Field from the official source that produced the reported name similarity score. This can be the standard `name` field or a country-specific field (for example, `brazil_fantasy_name`).", "example": "name" } } } } }, "ILookupErrorItem": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string", "example": "json request could not be read" } } }, "ILookupResponseTaxRegisteredInVies": { "type": "string", "enum": [ "yes", "no", "unknown" ], "description": "Specifies whether the TIN is currently registered for VAT/GST in VIES." } }, "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": "Instant Lookup" } ] } ```