API Integration Help & Docs

Quickstart

Your first IRS TIN match takes about a minute.

Get an API key. In the portal, go to Admin › API Key Management and add a key with the Validate permission. No account yet? Create one.

Send a TIN and a name. Replace YOUR_API_KEY and run:

curl -X POST https://www.tincomply.com/api/v1/validate/irs-tin-name-matching \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tin": "123-12-1234", "name": "JOHN SMITH" }'

import requests

response = requests.post(
    "https://www.tincomply.com/api/v1/validate/irs-tin-name-matching",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"tin": "123-12-1234", "name": "JOHN SMITH"},
)
result = response.json()["irsTinNameMatchingResult"]
print(result["result"], result["message"])

using System.Net.Http.Json;

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");

var response = await client.PostAsJsonAsync(
    "https://www.tincomply.com/api/v1/validate/irs-tin-name-matching",
    new { tin = "123-12-1234", name = "JOHN SMITH" });

var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

const response = await fetch(
  "https://www.tincomply.com/api/v1/validate/irs-tin-name-matching",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ tin: "123-12-1234", name: "JOHN SMITH" }),
  }
);
const { irsTinNameMatchingResult } = await response.json();
console.log(irsTinNameMatchingResult.result, irsTinNameMatchingResult.message);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "tin": "123-12-1234",
              "name": "JOHN SMITH"
            }
            """;
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://www.tincomply.com/api/v1/validate/irs-tin-name-matching"))
            .header("X-API-Key", "YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        // Parse with your JSON library (Jackson, Gson) and read irsTinNameMatchingResult.
        System.out.println(response.body());
    }
}

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
)

func main() {
	body := []byte(`{
	  "tin": "123-12-1234",
	  "name": "JOHN SMITH"
	}`)

	req, err := http.NewRequest("POST", "https://www.tincomply.com/api/v1/validate/irs-tin-name-matching", bytes.NewReader(body))
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("X-API-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	var data map[string]any
	if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
		log.Fatal(err)
	}
	fmt.Println(data["irsTinNameMatchingResult"])
}

$body = @'
{
  "tin": "123-12-1234",
  "name": "JOHN SMITH"
}
'@

$response = Invoke-RestMethod -Method Post `
    -Uri "https://www.tincomply.com/api/v1/validate/irs-tin-name-matching" `
    -Headers @{ "X-API-Key" = "YOUR_API_KEY" } `
    -ContentType "application/json" `
    -Body $body

$response.irsTinNameMatchingResult

Read the result. The response carries the IRS result code:
```
"irsTinNameMatchingResult": {
    "message": "TIN and Name combination does not match IRS records",
    "result": 3,
    "completed": true
}
```
0, 6, 7 or 8 is a match. 3 means the name and TIN do not match, so request a corrected W-9. Every code and what to do about it is on the IRS TIN Name Matching page.

To try every endpoint without writing code, import the Postman collection or the OpenAPI spec.

Simple REST API Using JSON

TIN Comply's API follows a RESTful architecture and uses JSON for requests and responses.

Send an HTTP POST request to the API endpoint.
Include your API key in the X-API-Key header.
Send the request body as JSON with a Content-Type: application/json header.
All communication is encrypted over HTTPS.

Base URL: https://www.tincomply.com/api/v1/

Keys, permissions and authentication errors are covered on the Authentication page.

Always send Content-Type: application/json (and ideally Accept: application/json). Without one of them the same URL responds with an HTML page instead of JSON.

REST Endpoints

TIN Comply offers 11 validation services, each with its own endpoint, plus a multi-service validate endpoint and endpoints for request details and history.

Most users integrate with validate/irs-tin-name-matching, the dedicated endpoint for IRS TIN and name matching.
Each other service has its own endpoint in the same form, such as validate/list-sanctions.
To run several services on one record in a single call, use validate.

Each endpoint is designed to offer fast, reliable and compliant validation, so you can automate verification inside the systems you already use.

List of API Endpoints

Endpoint	Description
`validate/irs-tin-name-matching`	Checks a TIN and name combination against IRS records in real time and returns the IRS result code.
`validate/company-name-lookup-by-ein`	Submit an EIN and get back the registered business name associated with it.
`validate/company-ein-lookup-by-name`	Submit a company name and receive candidate EINs ranked by name-match confidence.
`request-details/reveal-ein`	Step two of an EIN lookup: unmasks the EIN of the candidate you choose from the company-ein-lookup-by-name results.
`validate/address-validation`	Verifies and standardizes a US mailing address against USPS records, adds the ZIP+4, county and congressional district, and lists every correction made to your input.
`validate/company-details-lookup-by-name-address`	Look up a business by legal name, by address, or both.
`validate/list-sanctions`	Screens a person or business name against more than 330 sanctions and watchlists, including OFAC SDN, the Consolidated Screening List, SAM exclusions, FinCEN, BIS, EU and UN, with fuzzy matching and alias detection.
`validate/fatca-giin`	Checks a GIIN against the IRS FATCA Foreign Financial Institution (FFI) list and returns the registered institution name and country.
`validate/legal-entity-identifier`	Validates a Legal Entity Identifier against the Global LEI Foundation (GLEIF) register and returns the registered entity's name, address, legal form, jurisdiction and status.
`validate/npi-registry`	Looks up a National Provider Identifier in the CMS NPPES registry and returns its status, the registered provider name, specialty, license and practice address.
`validate/medicare-enrollment`	Checks a provider's Medicare status by NPI: enrolled privileges (Part B, DME, home health, power mobility, hospice), opt-out status with its effective and end dates, and Care Compare profile details.
`validate/fmcsa-carrier`	Looks up a motor carrier by USDOT number and returns whether it is allowed to operate, its operating authority by type (common, contract, broker), insurance filings, out-of-service status and fleet size.
`validate`	Runs one or more validation services against a single record in one call.
`request-details`	Returns the complete stored result of one earlier validation request: the original request and every result object, in the same shape as the validate response.
`history`	Lists your previous validation requests, newest first, with a summary result for each service.
`status`	Current operating status of each validation service. No API key required.

Service identifiers

Use these values in requestedServices on validate, and in the per-service endpoint URLs.

Identifier	Service
`irs-tin-name-matching`	IRS TIN and name matching
`company-name-lookup-by-ein`	Company name lookup by EIN
`company-ein-lookup-by-name`	EIN lookup by company name
`address-validation`	USPS address validation and standardization
`company-details-lookup-by-name-address`	Company details lookup by name and address
`list-sanctions`	Sanctions and watchlist screening (330+ lists)
`fatca-giin`	FATCA GIIN validation
`legal-entity-identifier`	Legal Entity Identifier (LEI) validation
`npi-registry`	NPI registry lookup
`medicare-enrollment`	Medicare enrollment and opt-out check
`fmcsa-carrier`	FMCSA motor carrier verification

Setting Up a Simple IRS TIN Matching Request

Follow these steps to send a basic IRS TIN matching request using the API.

Step 1: Generate an API Key

In the portal, go to Admin › API Key Management and add a new key with the Validate permission.

Step 2: Create an HTTP POST Request

Include your API key in the X-API-Key header and set Content-Type: application/json.

Step 3: Set Request Parameters in JSON

{
    "tin": "123-12-1234",
    "name": "JOHN SMITH"
}

Step 4: Send the Request

Send the request to the IRS TIN matching endpoint: https://www.tincomply.com/api/v1/validate/irs-tin-name-matching

Step 5: Handle the JSON Response

{
    "id": "BG5CF5Z2q0SwIBmhZylJggxp",
    "request": {
        "tin": "XXXXX1234",
        "name": "JOHN SMITH",
        "requestDate": "2026-10-01T20:23:41Z",
        "requestedServices": "irs-tin-name-matching"
    },
    "irsTinNameMatchingResult": {
        "message": "TIN and Name combination does not match IRS records",
        "result": 3,
        "completed": true
    }
}

The result value is the IRS result code: 0, 6, 7 and 8 are matches; 1 through 5 are failures. The full table is on the IRS TIN Name Matching page.

Example Setup in Postman

The fastest way to try the API in Postman is to import our collection, which has a ready-made request for every endpoint.

Download the Postman collection

1. Import the collection

In Postman, choose Import and select the downloaded file. The requests are grouped the same way as this reference.

2. Add your API key

Open the collection's Variables tab and paste your key into apiKey. Every request sends it as the X-API-Key header automatically.

3. Send a request

Each request comes with a sample JSON body. Edit the values and send; the response appears below the request, as in this IRS TIN matching example.

Postman showing an IRS TIN matching request body and its JSON response

With this Postman setup you can quickly test requests before building them into your own systems.

Using another tool?

The OpenAPI 3 spec describes every endpoint, field and sample. Import it into Insomnia, Bruno, Swagger or your API gateway, or generate a typed client library in your language.

Before You Go Live

Authentication: create a key for each integration with only the permissions it needs.
Errors & service status: the status codes to handle, and how to check whether a source is down.
Checks & pending results: how calls are counted, and what to do when a result is not ready yet.
OpenAPI & client libraries: import the spec into your tools, or generate a typed client in your language.
Each endpoint page has a What to do with this result table for turning results into actions.

Prefer an AI assistant? The same validations are available to Claude, ChatGPT and other MCP-compatible assistants, with OAuth sign-in instead of an API key. See AI Connections.