Request a validation

post

https://api-demo.fonoa.com/lookup/v2/single-validations

This endpoint allows you to request a validation of the Tax Identification Number. In order to do so, our system needs a country of the client (ISO code) and a tax identification number of the client.

Set prefer_cached_result to true to attempt returning a result from the Instant Lookup cache before running a new online validation. This requires the Instant Lookup product entitlement on your account.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Find the tax office in Turkey and the corresponding value:

Turkish Tax Offices

Body Params

country_iso_code

string

enum

required

Country code in ISO 3166-1 alpha-2 format of the company whose TIN is being validated (e.g., au for Australia, hr for Croatia)

tax_identification_number

string

required

Tax Identification Number (VAT ID, GST ID, etc.) expressed as a string

tax_identification_number_type

string

enum

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.

This field is not yet supported for all countries.

Allowed:

additional_parameters

object

Additional parameters that can or need to be provided in particular countries.

validation_database_source

string

enum

When you are validating EU TINs, you can specify the validation source in the request. This will allow you to decide whether you would like Fonoa to validate TIN in VIES or in the local government database in a given EU country. If no source was requested, then Fonoa will by default first check VIES, and then the local database in case the TIN cannot be identified in VIES. If VIES is temporarily unavailable and unable to provide a result, Fonoa will also fall back to the local database.

Allowed:

fuzzy_matching

object

Fuzzy matching compares expected data with actual values to provide you with a similarity score in the form of a percentage. You can input either or both the expected taxpayer name and address. Examples:

expected name "Fonoa Technologies" and actual "FONOA TECHNOLOGIES LIMITED" will produce "similarity_percentage": 100
expected address "12 Wildflower way Belfast" and actual "UNIT 5, 12 WILDFLOWER WAY, BELFAST, BT12 6TA" will produce "similarity_percentage": 76

Fuzzy matching uses transliteration to the Latin alphabet before running the algorithm, for example:

expected name "Lukoil" and actual "ПУБЛИЧНОЕ АКЦИОНЕРНОЕ ОБЩЕСТВО \"НЕФТЯНАЯ КОМПАНИЯ \"ЛУКОЙЛ\"" will produce "similarity_percentage": 83 based on the transliteration of the actual name into the Latin alphabet

external_id

string

length ≥ 1

An additional reference identifier you can provide - typically, the identifier used in your own system. You can use this to match results back to your own data.

prefer_cached_result

boolean

Defaults to false

When set to true, Fonoa will first attempt to return a cached validation result from the Instant Lookup database instead of running an online validation.

This feature requires your account to have the Instant Lookup product entitlement. If your account has country restrictions for Instant Lookup, the requested country_iso_code must be within your allowed countries.

The TIN must pass format and checksum validation before a cache lookup is attempted. When a cached result is found, the validation completes immediately with validation_database_source set to fonoa_cache and includes the cached taxpayer data. If no cached result is available, the request proceeds with the standard validation flow.

When omitted or set to false, the standard online validation flow is used and no cache lookup is performed.

Responses

401

Unauthorized

202The validation process has started and you need to fetch the results from a resource provided in the response or by using the webhooks (https://docs.fonoa.com/reference/lookup-webhook-events).

400The provided data is not valid. This response will be served when you provide invalid parameters (ex. country code). It can also be returned if you do not provide valid additional_parameters value (ex. Turkey)

415Unsupported Media Type, we only accept application/json

500Internal Server Error, something went wrong and we are investigating it.

503Service Unavailable