API Documentation

Complete reference for the TIN Validator REST API. Validate Tax Identification Numbers for 120+ countries with simple HTTP requests.

Quick Start

Get started with the TIN Validator API in minutes. All API requests require authentication using an API key.

1. Get Your API Key

Create Free Account

2. Make Your First Request

curl -X POST https://api.tinvalidator.com/api/validate/tin \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tin": "123456789",
    "country_code": "US"
  }'

Try the API (Sandbox)

Test the single TIN validation endpoint directly from this page. Use a test API key and sample data only.

Interactive Request RunnerTest Mode

API Key

Country Code

TIN

Entity Type

Generated cURL

curl -X POST https://api.tinvalidator.com/api/validate/tin \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tin": "123456789",
  "country_code": "US",
  "entity_type": "individual"
}'

Authentication

All API requests must include your API key in the Authorization header using Bearer authentication.

Authorization: Bearer YOUR_API_KEY

Important: Keep your API key secure. Never share it publicly or commit it to version control.

Base URL

All API endpoints are relative to the base URL:

https://api.tinvalidator.com

API Endpoints

POST/api/validate/tin

Validate Single TIN

Validate a single Tax Identification Number for a specific country. This endpoint provides real-time validation against OECD rules.

Request Body

{
  "tin": "123456789",
  "country_code": "US",
  "entity_type": "individual"  // optional: "individual", "company", or "any"
}

Example Response

{
	"valid": false,
	"errors": [
		"Expected exactly 9 characters, got 8"
	],
	"error_codes": [
		"INVALID_LENGTH"
	],
	"checks": {
		"length": false,
		"charset": true,
		"format": false,
		"checksum": null
	},
	"matched_rule": "Social Security Number",
	"tin": "12345678",
	"country_code": "US",
	"confidence": "syntax_only"
}

cURL Example

curl -X POST https://api.tinvalidator.com/api/validate/tin \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tin": "123456789",
    "country_code": "US",
    "entity_type": "individual"
  }'

POST/api/validate/upload

Bulk TIN Validation

Upload a CSV or Excel file containing multiple TINs for asynchronous validation. Returns a job ID for tracking progress.

Request (multipart/form-data)

curl -X POST https://api.tinvalidator.com/api/validate/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "tin_column=tin" \
  -F "country_column=country_code" \
  -F "entity_type_column=entity_type"

Example Response

{
  "job_id": 12345,
  "status": "pending"
}

File Requirements:

Supported formats: CSV, XLSX, XLS
Must include columns for TIN and country code
Column names are auto-detected or can be specified
Entity type column is optional

GET/api/validate/jobs/{job_id}

Get Validation Job Status

Check the status of a bulk validation job and retrieve results when complete.

Example Response

{
  "id": 12345,
  "filename": "tins.csv",
  "status": "done",
  "submitted_at": "2026-03-18T07:00:00Z",
  "completed_at": "2026-03-18T07:05:00Z",
  "total_records": 1000,
  "invalid_records": 25,
  "download_url": "https://api.tinvalidator.com/api/validate/jobs/12345/download"
}

Status Values

pending - Job queued for processing
processing - Validation in progress
done - Validation complete, results available
error - Validation failed (check error_message)

GET/api/validate/jobs

List Validation Jobs

Retrieve a list of all validation jobs for your organization.

Query Parameters

search - Filter by filename (optional)
status - Filter by status (optional)
limit - Results per page (default: 50, max: 200)
offset - Pagination offset (default: 0)

Example Request

curl -X GET "https://api.tinvalidator.com/api/validate/jobs?status=done&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/validate/jobs/{job_id}/download

Download Validation Results

Download the validation results as an Excel file containing invalid TINs and a summary sheet.

curl -X GET https://api.tinvalidator.com/api/validate/jobs/12345/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o results.xlsx

Result File Structure:

Sheet 1 - Invalid TINs: Contains all rows that failed validation with error reasons
Sheet 2 - Summary: Statistics including total records, invalid count, and pass rate

GET/api/countries/

List Supported Countries

Get a list of all countries with TIN validation rules. Supports filtering by country code and entity type.

Query Parameters

country_code - Filter by country code (optional)
entity_type - Filter by entity type (optional)
skip - Pagination offset (default: 0)
limit - Results per page (default: 10000)

Example Response

[
  {
    "id": 1,
    "country_code": "US",
    "country_name": "United States",
    "entity_type": "individual",
    "rule_name": "Social Security Number",
    "regex_pattern": "^[0-9]{9}$",
    "description": "9-digit SSN",
    "length_min": 9,
    "length_max": 9,
    "example_tin": "123456789",
    "is_active": true
  }
]

GET/api/countries/stats

Country Statistics

Get statistics about supported countries and validation rules.

Example Response

{
  "total_countries": 120,
  "total_rules": 256,
  "latest_oecd_update": "2026-03-01T00:00:00Z"
}

GET/api/countries/{country_code}

Get Country Rules

Retrieve all validation rules for a specific country.

Example Request

curl -X GET https://api.tinvalidator.com/api/countries/US \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

[
  {
    "id": 1,
    "country_code": "US",
    "country_name": "United States",
    "entity_type": "individual",
    "rule_name": "Social Security Number",
    "regex_pattern": "^[0-9]{9}$",
    "description": "9-digit SSN for individuals",
    "length_min": 9,
    "length_max": 9,
    "allowed_chars": "0-9",
    "example_tin": "123456789",
    "is_active": true
  }
]

Webhooks

Receive HTTP POST notifications when validation jobs complete. Configure webhooks in your dashboard.

Webhook Events

job.completed - Validation job finished successfully
job.failed - Validation job encountered an error

Webhook Payload Example

{
  "event": "job.completed",
  "data": {
    "job_id": 12345,
    "total": 1000,
    "invalid": 25
  },
  "timestamp": "2026-03-18T07:05:00Z"
}

Error Handling

The API uses conventional HTTP response codes to indicate success or failure.

HTTP Status Codes

200

OK - Request succeeded

202

Accepted - Job queued for processing

400

Bad Request - Invalid parameters or malformed request

401

Unauthorized - Invalid or missing API key

404

Not Found - Resource not found

429

Too Many Requests - Rate limit or quota exceeded

500

Internal Server Error - Server error

Error Response Format

{
  "detail": "Rate limit exceeded: 300 requests per minute for your plan."
}

Rate Limits & Quotas

API usage is subject to plan-based monthly quotas and per-minute request limits.

Plan	Monthly Quota	Rate Limit
Starter	1,000 validations	10 req/min
Professional / Business	100,000 validations	300 req/min
Enterprise	Custom	300 req/min (higher on request)

429 responses include Retry-After, X-RateLimit-Limit, and X-RateLimit-Remaining headers.

SDKs & Code Examples

Examples in popular programming languages to help you get started quickly.

Node.js / TypeScript

const response = await fetch('https://api.tinvalidator.com/api/validate/tin', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    tin: '123456789',
    country_code: 'US',
    entity_type: 'individual'
  })
});

const result = await response.json();
console.log(result);

Python

import requests

response = requests.post(
    'https://api.tinvalidator.com/api/validate/tin',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'tin': '123456789',
        'country_code': 'US',
        'entity_type': 'individual'
    }
)

result = response.json()
print(result)

PHP

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.tinvalidator.com/api/validate/tin',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'tin' => '123456789',
    'country_code' => 'US',
    'entity_type' => 'individual'
  ])
]);

$response = curl_exec($curl);
$result = json_decode($response, true);
curl_close($curl);

print_r($result);

Support & Resources

Need Help?

Our support team is here to help you integrate and use the API.

Contact Support

Enterprise Solutions

Custom integrations, dedicated support, and higher limits available.

Contact Sales