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

FieldTypeDescription
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

FieldTypeDescription
resultintThe IRS result code (see the table below).
messagestringHuman-readable summary of the result.
completedboolFalse 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

ValueMeaning
0TIN and Name match
1TIN was missing or not 9-digit numeric
2TIN entered is not currently issued
3TIN and Name combination does not match IRS records
4Invalid TIN Matching request
5Duplicate TIN Matching request
6TIN and Name combination matches IRS SSN records
7TIN and Name combination matches IRS EIN records
8TIN 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 seeDo this
0, 6, 7 or 8Match. 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 SSNThe TIN is valid but is a different type than the payee claimed. Confirm the entity type and TIN on the W-9.
1The TIN is not 9 digits. Fix the data entry and send it again.
2The IRS has not issued this TIN. Hold payment and request a corrected W-9.
3The 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.
4The IRS rejected the request as invalid. Check that both tin and name were sent and that the name has no unusual characters.
5The same TIN and name were already checked. Use the earlier result.
completed is falseThe 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"}'

Sample 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