Developer reference

API Documentation

REST API for validating tax IDs across 106+ countries — single checks, bulk uploads, webhooks, and Bearer token auth.

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

Sign up for an account and generate an API key from the dashboard.

Create free account

2. Make Your First Request

Loading...

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

Generated cURL

Loading...

Authentication

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

Loading...

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:

Loading...

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
Loading...
Example Response
Loading...
cURL Example
Loading...
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)
Loading...
Example Response
Loading...
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
Loading...
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
Loading...
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.

Loading...
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
Loading...
GET/api/countries/stats

Country Statistics

Get statistics about supported countries and validation rules.

Example Response
Loading...
GET/api/countries/{country_code}

Get Country Rules

Retrieve all validation rules for a specific country.

Example Request
Loading...
Example Response
Loading...

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

Loading...

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

Loading...

Rate Limits & Quotas

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

PlanMonthly QuotaRate Limit
Starter1,000 validations10 req/min
Professional / Business100,000 validations300 req/min
EnterpriseCustom300 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

Loading...

Python

Loading...

PHP

Loading...

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