TINCorrect API Documentation

Quick Start

Get up and running with the TINCorrect API in minutes.

Create an account

Obtain a secure token

Authenticate by POSTing your credentials to the /Token endpoint. The response will include your bearer token (valid for 24 hours).

Make API requests

Include your token in the Authorization: Bearer <token> header on every subsequent API call to authenticate your requests.

Authentication

Learn how to securely authenticate your application.

TINCorrect employs Bearer Token authentication. To begin, request a token by sending your username and password to the Token endpoint. This token must be attached to the Authorization header for all endpoints.

Security Requirements
All API requests must be transmitted securely over HTTPS. Never expose your credentials in client-side code, frontend applications, or public repositories.

HTTP / REST

# Request Token
POST /Token HTTP/1.1
Host: api.tincorrect.com
Content-Type: application/json

{
  "username": "[email protected]",
  "password": "secure-password"
}

# Response Structure
{
  "access_token": "eyJhbGciOiJIUzI1...",
  "token_type": "bearer",
  "expires_in": 86399
}

Core Endpoints

Direct integration with the validation engine.

⚡ On-Demand Verification

POST /TinRequest

Submit a single TIN and Name combination for near real-time IRS validation testing. This returns a Job ID immediately.

GET /TinRequest/{id}

Poll with your Request ID to fetch verification results. Optimal polling frequency is 3-5 seconds after submission.

📦 Bulk Processing

POST /BulkTinRequest

Queue asynchronous validation for up to 100k pairs payload. Supply a webhook/email for completion alert.

GET /BulkTinRequest/{id}

Fetch bulk metadata and JSON-formatted pair outcomes.

🛠️ Utility

GET /SearchCredits

Returns the number of search credits remaining on your account.

GET /Status

Check an unauthenticated endpoint to verify the TINCorrect service is operational.

Error Handling

Predictable convention-based HTTP status codes are used across all endpoints.

Status Code	Description	Resolution
`200 OK`	Success	The request was successfully processed and returned data.
`400 Bad Request`	Validation Error	Malformed JSON or invalid parameters. Check the response body for specifics.
`401 Unauthorized`	Authentication Failed	Bearer token missing, malformed, or has expired after 24 hours. Request a new token.
`402 Payment Req.`	Insufficient Credits	Your account balance is too low to process this check. Top up on the dashboard.
`429 Too Many Req.`	Rate Limited	Exceeded endpoint limits. Please implement exponential backoff retry logic.

TINCorrect API Overview