API Endpoint: IRS TIN Name Matching
The irs-tin-name-matching endpoint is used to validate a Taxpayer Identification Number (TIN) and Name combination against IRS records.
POST /api/v1/validate/irs-tin-name-matching
https://www.tincomply.com/api/v1/validate/irs-tin-name-matching
Checks a TIN and name combination against IRS records in real time and returns the IRS result code. Works for EINs, SSNs and ITINs. No IRS e-Services enrollment is required.
Request body
| Field | Type | Description |
|---|---|---|
tinrequired |
string | The Taxpayer Identification Number (EIN, SSN or ITIN). 9 digits; hyphens are ignored. |
namerequired |
string | The entity or individual name associated with the TIN. |
Response object: irsTinNameMatchingResult
| Field | Type | Description |
|---|---|---|
result | int | The IRS result code (see the table below). |
message | string | Human-readable summary of the result. |
completed | bool | False when the upstream source was unavailable. The request is retried automatically; call request-details with the request id later to get the finished result. |
Possible values for result
| Value | Meaning |
|---|---|
0 | TIN and Name match |
1 | TIN was missing or not 9-digit numeric |
2 | TIN entered is not currently issued |
3 | TIN and Name combination does not match IRS records |
4 | Invalid TIN Matching request |
5 | Duplicate TIN Matching request |
6 | TIN and Name combination matches IRS SSN records |
7 | TIN and Name combination matches IRS EIN records |
8 | TIN and Name combination matches IRS SSN and EIN records |
Codes 0, 6, 7 and 8 are matches. Codes 1 through 5 are failures. When a match fails, a corrected W-9 is the usual next step.
What to do with this result
| When you see | Do this |
|---|---|
| 0, 6, 7 or 8 | Match. Keep the request id with the payee record as evidence of the check. |
| 6 when you expected an EIN, or 7 when you expected an SSN | The TIN is valid but is a different type than the payee claimed. Confirm the entity type and TIN on the W-9. |
| 1 | The TIN is not 9 digits. Fix the data entry and send it again. |
| 2 | The IRS has not issued this TIN. Hold payment and request a corrected W-9. |
| 3 | The name and TIN do not match. Request a corrected W-9 with the legal name exactly as the IRS has it, and check again. Mismatches left on filed 1099s lead to IRS B-notices and backup withholding. |
| 4 | The IRS rejected the request as invalid. Check that both tin and name were sent and that the name has no unusual characters. |
| 5 | The same TIN and name were already checked. Use the earlier result. |
| completed is false | The source was unavailable. Keep the request id and call request-details later; the result fills in once the retry succeeds. |
Sample request
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",
},
)
response.raise_for_status()
print(response.json()["irsTinNameMatchingResult"])using System.Text;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var body = """
{
"tin": "123-12-1234",
"name": "JOHN SMITH"
}
""";
var response = await client.PostAsync(
"https://www.tincomply.com/api/v1/validate/irs-tin-name-matching",
new StringContent(body, Encoding.UTF8, "application/json"));
Console.WriteLine(await response.Content.ReadAsStringAsync());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 data = await response.json();
console.log(data.irsTinNameMatchingResult);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.irsTinNameMatchingResultSample response
{
"id": "BZ5CF5Z2q0SwIBmhZylJggxp",
"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
}
}Errors
Requests that cannot be processed return HTTP 400 with an object keyed by field name, each listing what was wrong. Authentication, permission and other status codes are covered in Errors & service status.
This endpoint requires an API key with the Validate permission.
See how this check works in the portal and what it costs: IRS TIN Matching