Request a batch validation

post

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

This endpoint allows you to request a batch of TINs to be validated. In order to do so, our system needs a country where relevant TINs are registered (ISO code) and the TIN data. You can have multiple countries in the request, for eg. 50 Hungarian TINs and 120 Mexican TINs.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

batch_name

string

tax_identification_number_requests

array of objects

required

length ≥ 1

tax_identification_number_requests*

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_numbers

array of strings

required

List of Tax Identification Numbers (VAT ID, GST ID, etc.) expressed as a strings

tax_identification_numbers*

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.

Responses

401

Unauthorized

503

Service Unavailable

Language

Credentials

Header

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

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 your batch is over 10000 unique Tax Identification Numbers.

415Unsupported Media Type, we only accept application/json

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