Sign in

v1

latestOpenAPI 3.0.02026-07-2436163302.7 KB
Lookup V1

Request a batch validation

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.

post/lookup/v1/validations/batches

Request body

check_tin_onlineboolean

Whether TINs should be checked in real-time against a local government database that stores TINs. If you put this to false, then only the validation of the format and the number structure will be performed.

Example request

{
  "tin_requests": [
    {
      "country_iso": "ee",
      "tins": [
        "EE102360282, EE101757663, EE100210457, EE102019944, EE101279099"
      ],
      "fuzzy_matching": {
        "taxpayer": {
          "name": "expected taxpayer name",
          "address": "expected taxpayer address"
        }
      }
    }
  ]
}

Response

The validation process has started and you need to fetch the results from a resource provided in the response. This response will also be returned if you provide a TIN number that has invalid format or checksum digit(s), the response will provide details whether the format or/and checksum digit(s) were invalid.

batch_idstring required
requestedstring date-time required
status'running' | 'completed' required
validation_statusstring uri required

Example response

{
  "batch_id": "bd5fa7cc-3597-454e-86fb-a94b79514726",
  "validations": [
    {
      "id": "bf69ee0a-95be-4037-a202-82f1c7562d16",
      "tin": "100070008",
      "country_iso": "ee",
      "fuzzy_matching": {
        "taxpayer": {
          "name": "expected taxpayer name",
          "address": "expected taxpayer address"
        }
      },
      "extra_fields": {
        "brazil_fantasy_name": "BAR E LANCHES 111",
        "canada_federal_state": "Federal",
        "colombia_check_digit": "9",
        "colombia_large_taxpayer": "yes",
        "colombia_tin_without_check_digit": "123456789",
        "egypt_uin_expiry_date": "2010-10-10",
        "germany_federal_state": "Berlin",
        "hungary_full_tax_identification_number": "13353298-2-44",
        "india_pan_aadhaar_linked": "not_applicable",
        "india_pan_specified_person": "no",
        "india_trade_name": "ACME TRADE",
        "japan_qualified_invoice_issuer": "yes",
        "mexico_zip_code_used_for_validation": "12345",
        "usa_irs_response": "TIN and Name combination does not match IRS records."
      }
    }
  ],
  "requested": "2022-05-19T13:03:44.667Z",
  "validation_status": "https://api-demo.fonoa.com/lookup/v1/validations/batches/bd5fa7cc-3597-454e-86fb-a94b79514726"
}