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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

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 if TIN is not identified in VIES. Note that the following countries do not have local implementation available:

cy, de, fr, ie, lu, mt, nl, se.

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.

Responses

401

Unauthorized

200This is an immediate response for validation and provide details whether the format were invalid, status or error details.

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