Tax Identification Number (TIN) validation API supporting instant lookups and batch validation across 120+ countries. Enables real-time VAT/GST ID verification, TIN search by business name, result polling, and cancellation of pending validations.
openapi: 3.0.0
info:
title: Fonoa Validate API
description: >
Tax Identification Number (TIN) validation API supporting instant lookups and batch
validation across 120+ countries. Enables real-time VAT/GST ID verification, TIN
search by business name, result polling, and cancellation of pending validations.
contact:
name: Fonoa Support
url: https://www.fonoa.com/
email: [email protected]
version: '1.0'
servers:
- url: https://api-demo.fonoa.com
description: Fonoa API demo environment
- url: https://sandbox.fonoa.com/
description: Fonoa API sandbox environment
- url: https://api.fonoa.com
description: Fonoa API production (live) environment
paths:
/lookup/v2/single-validations:
post:
summary: Request a single validation
description: >
Submit a single Tax Identification Number (TIN) for validation. Supports instant
lookup and cached result retrieval across 120+ countries. The API returns either
an immediate response (200) or an accepted async response (202).
operationId: RequestavalidationV2
tags:
- Lookup V2
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LookupTinValidationRequest'
responses:
'200':
description: >
Immediate response for validations. Provides format validity details.
Also returned for TINs with invalid format or checksum digits.
content:
application/json:
schema:
$ref: '#/components/schemas/LookupValidationImmediateResponseV2'
'202':
description: >
The validation process has started. Fetch results from the resource provided
in the response or use webhooks for status updates.
content:
application/json:
schema:
$ref: '#/components/schemas/LookupValidationImmediateResponseV2'
'400':
description: Bad Request - invalid request parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/LookupErrorResponseV2'
'401':
description: Authentication failed - missing or incorrect subscription key.
'415':
description: Unsupported Media Type.
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/LookupErrorResponseV2'
'503':
description: Service Unavailable.
content:
application/json:
schema:
$ref: '#/components/schemas/LookupErrorResponseV2'
/lookup/v2/batch-validations:
post:
summary: Request a batch validation
description: >
Submit multiple Tax Identification Numbers (TINs) for batch validation.
Returns immediate results for TINs with invalid format; async processing
for others with polling via the batch_validation_result_url.
operationId: RequestbatchvalidationV2
tags:
- Lookup V2
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- validations
properties:
batch_name:
type: string
description: Optional name for the batch validation.
example: batch-2022-12-25
validations:
type: array
description: List of TINs to validate.
items:
$ref: '#/components/schemas/LookupTinValidationRequest'
responses:
'200':
description: All validations completed immediately.
content:
application/json:
schema:
$ref: '#/components/schemas/LookupBatchValidationResponse'
'202':
description: Batch validation accepted; processing in background.
content:
application/json:
schema:
$ref: '#/components/schemas/LookupBatchValidationResponse'
examples:
running:
value:
batch_id: 7e7f4459-5871-47a1-af3d-364df9c31fe0
batch_name: batch-2022-12-25-09-07-54
validations:
- validation_id: 3dc8b6d9-57af-4afb-9184-ef510be3f388
tax_identification_number: GB830930346
country_iso_code: gb
format: valid
requested_at: '2022-12-28T14:55:11.575Z'
is_business: unknown
requested_at: '2021-03-25T09:37:41.649Z'
status: running
batch_validation_result_url: https://api-demo.fonoa.com/lookup/v2/batch-validations/7e7f4459-5871-47a1-af3d-364df9c31fe0
'400':
description: Bad Request.
content:
application/json:
schema:
$ref: '#/components/schemas/LookupErrorResponseV2'
'401':
description: Authentication failed.
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/LookupErrorResponseV2'
/lookup/v2/batch-validations/{batch_id}:
get:
summary: Get result of batch validation
description: Poll for the result of a previously submitted batch validation.
operationId: GetresultofbatchvalidationV2
tags:
- Lookup V2
parameters:
- name: batch_id
in: path
required: true
description: The batch validation ID returned from the POST request.
schema:
type: string
responses:
'200':
description: Batch validation results.
content:
application/json:
schema:
$ref: '#/components/schemas/LookupBatchValidationResponse'
'401':
description: Authentication failed.
'404':
description: Batch validation not found.
delete:
summary: Cancel a batch validation
description: Cancel a pending batch validation.
operationId: CancelbatchvalidationV2
tags:
- Lookup V2
parameters:
- name: batch_id
in: path
required: true
description: The batch validation ID to cancel.
schema:
type: string
responses:
'204':
description: Batch validation successfully cancelled.
'401':
description: Authentication failed.
'404':
description: Batch validation not found.
/lookup/v2/single-validations/{validation_id}:
get:
summary: Get result of a single validation
description: Retrieve the result of a previously submitted single TIN validation.
operationId: GetresultofvalidationV2
tags:
- Lookup V2
parameters:
- name: validation_id
in: path
required: true
description: The validation ID returned from the POST request.
schema:
type: string
responses:
'200':
description: Validation result.
content:
application/json:
schema:
$ref: '#/components/schemas/LookupValidationImmediateResponseV2'
'401':
description: Authentication failed.
'404':
description: Validation not found.
delete:
summary: Delete result of a single validation
description: Delete the result of a completed single TIN validation.
operationId: DeleteresultofvalidationV2
tags:
- Lookup V2
parameters:
- name: validation_id
in: path
required: true
description: The validation ID to delete.
schema:
type: string
responses:
'204':
description: Validation result successfully deleted.
'401':
description: Authentication failed.
'404':
description: Validation not found.
/lookup/v2/tin-search:
post:
summary: Request a TIN search
description: Search for a Tax Identification Number by business name and country.
operationId: RequestTINsearch
tags:
- Lookup V2
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- country_iso_code
- name
properties:
country_iso_code:
type: string
description: ISO 3166-1 alpha-2 country code.
example: gb
name:
type: string
description: Business name to search for.
example: Fonoa Technologies
responses:
'200':
description: TIN search results.
'202':
description: TIN search accepted; processing in background.
'400':
description: Bad Request.
'401':
description: Authentication failed.
components:
schemas:
LookupTinValidationRequest:
type: object
required:
- country_iso_code
- tax_identification_number
properties:
country_iso_code:
type: string
description: ISO 3166-1 alpha-2 country code for the TIN.
example: gb
tax_identification_number:
type: string
description: The Tax Identification Number to validate.
example: GB830930346
additional_parameters:
$ref: '#/components/schemas/LookupAdditionalParametersV2'
prefer_cached_result:
type: boolean
description: Set to true to attempt returning a result from the Instant Lookup cache.
default: false
LookupAdditionalParametersV2:
type: object
description: Additional country-specific parameters for TIN validation.
properties:
name:
type: string
description: Business name for fuzzy matching.
example: teamwear
address:
type: string
description: Business address for fuzzy matching.
example: Wildflower 22 Belfast
LookupValidationImmediateResponseV2:
type: object
properties:
validation_id:
type: string
description: Unique identifier for this validation request.
example: 3dc8b6d9-57af-4afb-9184-ef510be3f388
tax_identification_number:
type: string
description: The TIN that was submitted for validation.
example: GB830930346
country_iso_code:
type: string
description: ISO 3166-1 alpha-2 country code.
example: gb
format:
type: string
description: Whether the TIN format is valid or invalid.
enum:
- valid
- invalid
requested_at:
type: string
format: date-time
description: Timestamp when the validation was requested.
example: '2022-12-28T14:55:11.575Z'
is_business:
type: string
description: Whether the TIN belongs to a business entity.
enum:
- 'yes'
- 'no'
- unknown
status:
type: string
description: Current status of the validation.
enum:
- completed
- running
- failed
result_url:
type: string
format: uri
description: URL to poll for the validation result.
fuzzy_matching:
type: object
description: Fuzzy matching results for name and address.
properties:
name:
type: string
description: Business name match result.
example: teamwear
address:
type: string
description: Business address match result.
example: Wildflower 22 Belfast
error_details:
$ref: '#/components/schemas/LookupErrorDetail'
business_name:
type: string
description: Registered business name associated with the TIN.
business_address:
type: string
description: Registered business address associated with the TIN.
LookupBatchValidationResponse:
type: object
required:
- batch_id
- batch_name
- validations
- requested_at
- status
- batch_validation_result_url
properties:
batch_id:
type: string
description: Unique identifier for the batch validation.
example: bd5fa7cc-3597-454e-86fb-a94b79514726
batch_name:
type: string
description: Name of the batch validation.
example: batch-2022-12-25-09-07-54
validations:
type: array
description: List of individual validation results.
items:
$ref: '#/components/schemas/LookupValidationImmediateResponseV2'
requested_at:
type: string
format: date-time
description: Timestamp when the batch was requested.
example: '2022-05-19T13:03:44.667Z'
status:
type: string
description: Current status of the batch.
enum:
- running
- completed
batch_validation_result_url:
type: string
format: uri
description: URL to poll for batch results.
example: https://api-demo.fonoa.com/lookup/v2/batch-validations/bd5fa7cc-3597-454e-86fb-a94b79514726
LookupErrorResponseV2:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/LookupErrorDetail'
message:
type: string
description: Human-readable error message.
LookupErrorDetail:
type: object
properties:
code:
type: string
description: Error code identifying the error type.
example: FORMAT_INVALID
message:
type: string
description: Detailed error description.
example: ABN should contain 11 digits, and ACN should contain 9 digits
field:
type: string
description: The field that caused the error, if applicable.
securitySchemes:
Ocp-Apim-Subscription-Key:
type: apiKey
description: API Subscription Key
name: Ocp-Apim-Subscription-Key
in: header
security:
- Ocp-Apim-Subscription-Key: []
tags:
- name: Lookup V2