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.

🚧

Caching

All TIN validation results are stored for caching purposes. You can decide for how long you would like to receive the cached result by setting the parameter in the validation request. If you select 30 days, then we would first check our cache for past TIN validations up to 30 days of the last time this TIN was validated. Fonoa stores validated data for a period of 7 years, so these can be retrieved for tax compliance purposes with an exact timestamp of when the validation of that specific TIN took place.

Depending on the country you select, you might need to provide further information in order to verify the Tax Identification Number.

Currently, only Turkey requires such additional piece of information you will need to specify the Province, and the relevant Tax Office. See attached request examples below, the request composes parameters for Istanbul (034) province and BÜYÜK MÜK. VD. B VERGİ DAİRESİ (034230) tax office, the values were taken from the section below.

curl --request POST \
  --url https://api-demo.fonoa.com/Lookup/v1/Validations \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Ocp-Apim-Subscription-Key' \
  --data '{"country_iso":"tr","tin":"123456789","check_tin_online":true,"additional_parameters":[{"name":"tax_office","value":"034230"},{"name":"province","value":"034"}]}'
const fetch = require('node-fetch');

const url = 'https://api-demo.fonoa.com/Lookup/v1/Validations';

const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    'Ocp-Apim-Subscription-Key': '8b144782eec54b159917c8c4a367d694'
  },
  body: JSON.stringify({
    country_iso: 'tr',
    tin: '123456789',
    check_tin_online: true,
    additional_parameters: [{name: 'tax_office', value: '034230'}, {name: 'province', value: '034'}]
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api-demo.fonoa.com/Lookup/v1/Validations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["Accept"] = 'application/json'
request["Content-Type"] = 'application/json'
request["Ocp-Apim-Subscription-Key"] = '8b144782eec54b159917c8c4a367d694'
request.body = "{\"country_iso\":\"tr\",\"tin\":\"123456789\",\"check_tin_online\":true,\"additional_parameters\":[{\"name\":\"tax_office\",\"value\":\"034230\"},{\"name\":\"province\",\"value\":\"034\"}]}"

response = http.request(request)
puts response.read_body
const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    'Ocp-Apim-Subscription-Key': '8b144782eec54b159917c8c4a367d694'
  },
  body: '{"country_iso":"tr","tin":"123456789","check_tin_online":true,"additional_parameters":[{"name":"tax_office","value":"034230"},{"name":"province","value":"034"}]}'
};

fetch('https://api-demo.fonoa.com/Lookup/v1/Validations', options)
  .then(response => console.log(response))
  .catch(err => console.error(err));
import requests

url = "https://api-demo.fonoa.com/Lookup/v1/Validations"

payload = {
    "country_iso": "tr",
    "tin": "123456789",
    "check_tin_online": True,
    "additional_parameters": [
        {
            "name": "tax_office",
            "value": "034230"
        },
        {
            "name": "province",
            "value": "034"
        }
    ]
}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Ocp-Apim-Subscription-Key": "8b144782eec54b159917c8c4a367d694"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Find the province in Turkey and the corresponding value:

Find the tax office in Turkey and the corresponding value:

This endpoint receives mandatory parameters and validates format, syntax, and/or checks whether the given Tax Number is available in the relevant government database. This confirms that, when transacting with the company this Tax Number belongs to, you are engaging in a B2B transaction.

📘

Examples of the request and response

You can find an example of the request in various programming languages in the console pane on the right-hand side. All you need to do is to click on "Examples" in the upper right corner of that console pane, select "example-1" and click on the 'Try it' button. As a result, you will get a response.

Language
Authorization
Header
URL
Click Try It! to start a request and see the response here!