---
title: "Find a tax identification number"
method: POST
path: "/instant-lookup/v1/find"
tags: ["Instant Lookup"]
---

# Find a tax identification number

`POST /instant-lookup/v1/find`

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.

## Request body

- object
  - `country_iso_code` 'pt' | 'br' | 'be' | 'pl' | 'fr' | 'co' | 'de' | 'es', required — - Country code in ISO 3166-1 alpha-2 format of the company whose TIN is being validated (e.g., `pt` for Portugal)
  - `tax_identification_number` string, required — Tax Identification Number (VAT ID, GST ID, etc.) expressed as a string
  - `fuzzy_matching` object — Fuzzy matching compares expected tax payer name with actual value to provide you with a similarity score in the form of a percentage. Examples: - expected name `"Fonoa Technologies"` and actual `"FONOA TECHNOLOGIES LIMITED"` will produce `"similarity_percentage": 100`
    - `name` string — Expected taxpayer name

## Response `200`

The requested TIN was found in our database.

- ILookupResponse
  - `found_tax_identification_number` string
  - `found_in_official_database` 'yes' | 'no'
  - `tax_registered` 'yes' | 'no' | 'unknown' | 'not_applicable' — Specifies whether the TIN was identified in a given government database and whether this identified TIN is currently registered for VAT/GST.
  - `format` 'valid' | 'not_valid' — 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)
  - `name` string — A company name acquired from online database
  - `fuzzy_matching` ILookupFuzzyMatchingResult — This signifies the result of a fuzzy matching request. It contains requested/expected value and the similarity score in the form of a percentage.
    - `name` object
      - `expected` string — Requested expected taxpayer name
      - `similarity_percentage` integer — Result in percentage 0-100 (integer)
  - `business_status` 'active' | 'inactive' | 'unknown' — 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.
  - `is_business` 'yes' | 'no' | 'unknown' | 'not_applicable' — Specifies whether the taxpayer is an individual, or a legal entity.
  - `legal_entity_type` string — It represents the legal entity type of the taxpayer, the values depend on the country. Some examples: - Public Limited Company - Private Limited Company - Limited Liability Partnership - General Partnership - Joint Stock Company
  - `registration_type` 'Regular' | 'Composition' | 'Special Economic Zone' | 'Casual Taxable Person' | 'Unknown' | 'Non Resident Online Services Provider' | 'Registered' | 'Exempt' | 'Final Consumer' | 'Monotributo' | 'Input Service Distributor (ISD)' | 'SEZ Developer' | 'Tax Deductor' | 'Non Resident Foreign Taxpayer' | 'UN Bodies, Embassies and Other Notified Persons' | 'Tax Collector (Electronic Commerce Operator)' | 'Temporary' | 'According to §4 of the VAT Act' | 'According to §4b of the VAT Act' | 'According to §7 of the VAT Act' | 'According to §7a of the VAT Act' | 'Plátce' | 'Identifikovaná osoba' | 'Normal Trimestral' | 'Normal Trimestral por Opção' | 'Normal Mensal' | 'Normal Mensal por Opção' | 'Isenção Artº 53' | 'Isenção Artº 9' | 'Reg. Esp. Peq. Retalhistas' | 'Não Sujeito' | 'Reg. Especial Tributação' | 'Aquisições Intracomunitárias' | 'Micro' | 'Small' | 'Medium' | 'Large' — Type of tax registration.
  - `registration_date` string, date — Date at which the entity became registered for indirect tax as shown in the official database.
  - `de_registration_date` string, date — Date at which the entity became deregistered for indirect tax as shown in the official database.
  - `address` string
  - `tax_registered_in_vies` 'yes' | 'no' | 'unknown' — Specifies whether the TIN is currently registered for VAT/GST in VIES.
  - `country_specific` object
  - `last_updated` string, date-time — Date at which the entity was last checked against official source and updated.
  - `errors` ILookupErrorItem[]
    - `code` string
    - `message` string

## Other responses

- `202` — The requested TIN was not found in our database, Lookup request is initiated, result is pending.
- `400` — Bad request due to various reasons like unsupported country, individual TIN, wrong JSON format, wrong query parameters...

---

[API](https://skmtc.dev/fonoa/apis/fonoa-api.md) · [All operations](https://skmtc.dev/fonoa/apis/fonoa-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fonoa/fonoa-api/revisions/cf0ebc843a3f/schema)