TIN Matching API Integration: A Developer's Guide

Why Integrate TIN Matching via API?

The IRS TIN Matching Program has no API. It offers only a manual web interface for interactive matching (25 records at a time) and a file-upload workflow for bulk matching. Neither approach integrates with your existing systems. That means your team must manually export data, upload files, wait for results, and then import those results back into your ERP or vendor management platform.

The TINCorrect API eliminates this manual loop. With a simple REST call, your application can verify a name/TIN pair in real time and act on the result immediately. Here are the most common use cases:

• Vendor onboarding: Verify TINs at the moment a new vendor submits their W-9, before they enter your system.
• Payment processing: Confirm TIN validity before issuing a payment to a 1099-reportable payee.
• 1099 preparation: Batch-verify your entire vendor database programmatically before filing season.
• ERP integration: Embed TIN verification directly into your procurement or accounts payable workflow.
• Multi-tenant platforms: If you build software for vendor compliance, offer TIN matching as a feature to your users.

API Overview

The TINCorrect API follows REST conventions over HTTPS. All requests and responses use JSON. The base URL is:

Full endpoint documentation, including request schemas, response schemas, and interactive testing, is available in the TINCorrect API reference.

Authentication

The TINCorrect API uses JSON Web Tokens (JWT) for authentication. Here is how the authentication flow works:

Step 1: Obtain API Credentials

Create a TINCorrect account and generate an API key pair (client ID and client secret) from your account dashboard. Keep your client secret secure and never expose it in client-side code.

Step 2: Request a JWT Token

Exchange your credentials for a JWT token by calling the authentication endpoint:

POST /auth/token
Content-Type: application/json

{
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret"
}

The response includes a JWT token and its expiration time:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

Step 3: Include the Token in Requests

Pass the JWT token in the Authorization header of every subsequent API call:

Tokens expire after the duration specified in expiresIn (in seconds). Your application should cache the token and refresh it before expiration. Do not request a new token for every API call.

Endpoints

Single TIN Match

Verify a single name/TIN combination in real time:

POST /api/v1/tin-match
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Acme Corporation",
  "tin": "123456789"
}

Response:

{
  "resultCode": 0,
  "resultDescription": "Name/TIN combination matches IRS records",
  "name": "Acme Corporation",
  "tin": "***-**-6789",
  "matchedAt": "2026-04-12T14:30:00Z",
  "requestId": "req_abc123"
}

The resultCode field corresponds to the standard IRS TIN matching result codes (0-8). The resultDescription provides a human-readable explanation. Note that the TIN is partially masked in responses for security.

Batch TIN Match

Submit multiple name/TIN pairs in a single request for bulk processing:

POST /api/v1/tin-match/batch
Authorization: Bearer {token}
Content-Type: application/json

{
  "records": [
    { "name": "Acme Corporation", "tin": "123456789", "referenceId": "V-001" },
    { "name": "Jane Smith", "tin": "987654321", "referenceId": "V-002" },
    { "name": "Global Services LLC", "tin": "555123456", "referenceId": "V-003" }
  ]
}

Response:

{
  "batchId": "batch_xyz789",
  "totalRecords": 3,
  "results": [
    {
      "referenceId": "V-001",
      "resultCode": 0,
      "resultDescription": "Name/TIN combination matches IRS records"
    },
    {
      "referenceId": "V-002",
      "resultCode": 3,
      "resultDescription": "Name/TIN combination does not match"
    },
    {
      "referenceId": "V-003",
      "resultCode": 0,
      "resultDescription": "Name/TIN combination matches IRS records"
    }
  ],
  "summary": {
    "matched": 2,
    "mismatched": 1,
    "errors": 0
  }
}

The optional referenceId field lets you pass your own vendor identifier so you can easily map results back to your records. The summary object provides a quick count of matched vs. mismatched records.

Rate Limiting

The TINCorrect API applies rate limits to ensure fair usage and system stability. Current limits are:

Rate limit status is returned in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1744467600

If you exceed the rate limit, the API returns HTTP 429 (Too Many Requests). Your application should implement exponential backoff and retry logic. For high-volume needs beyond the standard limits, contact sales for enterprise rate limits.

Error Handling

The TINCorrect API uses standard HTTP status codes and returns structured error objects:

Error response format:

{
  "error": {
    "code": "INVALID_TIN_FORMAT",
    "message": "TIN must be exactly 9 digits",
    "details": "The 'tin' field contained 8 characters. Expected 9 numeric digits."
  }
}

Handling IRS Downtime

The IRS TIN Matching system has scheduled maintenance windows and occasional unplanned outages. When the IRS system is unavailable, the TINCorrect API returns a 503 status. Your application should:

• Queue the request for retry
• Implement exponential backoff (e.g., retry after 30 seconds, then 1 minute, then 5 minutes)
• Set a maximum retry count to avoid infinite loops
• Optionally, allow the user workflow to continue and verify the TIN asynchronously

Integration Use Cases

Vendor Onboarding Workflow

The most impactful integration point is vendor onboarding. When a vendor submits their information (typically via a W-9 form), your system can immediately call the TINCorrect API to verify the name/TIN combination. If the result is Code 0 (match), the vendor proceeds through onboarding. If the result is a mismatch, the system can prompt the vendor to correct their information before they are added to your vendor database.

This "verify at the gate" approach means you never add a vendor with unverified or mismatched TIN data. It eliminates downstream problems like CP2100 notices, failed 1099 filings, and backup withholding.

Payment Processing Gate

For organizations that need to ensure compliance before issuing payments, the API can serve as a verification gate in the payment approval workflow. Before a payment above the 1099 reporting threshold is released, the system checks whether the payee's TIN has been verified within the last 12 months. If not, it triggers a real-time match and holds the payment until verification completes.

Year-End Batch Verification

While the web-based bulk upload works well for ad-hoc batch matching, the API batch endpoint allows you to automate the entire process. Schedule a job to extract 1099-reportable vendors from your database, submit them to the batch endpoint, and process the results, all without manual intervention. This is particularly valuable for year-end 1099 preparation.

Multi-Tenant SaaS Platforms

If you build software that serves AP teams or tax professionals, integrating the TINCorrect API lets you offer TIN verification as a native feature of your platform. Your users get the benefit of IRS-level TIN matching without needing their own TINCorrect account or IRS e-Services registration.

Best Practices

Cache Tokens, Not Results

Cache your JWT token and reuse it until it approaches expiration. Do not request a new token for every API call; this wastes your auth rate limit and adds latency. However, do not cache TIN match results for extended periods. Payee information can change, so re-verify periodically.

Use Reference IDs

Always include a referenceId in batch requests. This makes it straightforward to map results back to your vendor records without relying on name or TIN matching, which can be error-prone if you have similar records.

Handle All Result Codes

Do not just check for Code 0 vs. "everything else." Each result code has a different meaning and may require a different workflow in your application. For example, Code 1 (missing TIN) should trigger a data collection workflow, while Code 3 (name mismatch) might trigger a name correction prompt.

Log Everything

Log every TIN match request and response (with TINs partially masked). This creates the audit trail you need for reasonable cause documentation and helps with debugging integration issues.

Implement Retry Logic

Network errors and IRS downtime happen. Implement retry logic with exponential backoff for 429 and 503 responses. For 400-level errors (other than 429), do not retry; fix the request.

Secure Your Credentials

Store API credentials in environment variables or a secrets manager. Never hardcode them in source code, commit them to version control, or expose them in client-side JavaScript.

Getting Started

1. Create a TINCorrect account
2. Generate your API key pair from the account dashboard
3. Review the full API documentation
4. Test with the sandbox environment using test TINs
5. Integrate into your staging environment
6. Deploy to production

Need help with your integration? Our developer support team is available via the dashboard. For a broader understanding of TIN matching concepts, visit our complete TIN matching guide, or explore how the top TIN matching services compare on API capabilities.

Author

Ken Ham

Founder at TINCorrect

Passionate about making tax identity verification simple so businesses can focus on what matters.