Skip to main content
Verify a TIN checks a TIN + name pair against IRS records. SSNs and EINs both verify; a correct pair matches regardless of which kind of TIN it is (a sole proprietor’s EIN keyed to the owner’s personal name verifies with a first and last name). This page explains what comes back.

​
The three results

A 200 always carries one of three definitive results in result:
  • Matched: the name and TIN match IRS records.
  • Mismatched: the name and TIN do not match IRS records.
  • NotIssued: the TIN is not currently issued.
Alongside the result, verifiedAtUtc says when the answer was produced.

​
Invalid input

Invalid input returns a 400 with error set to invalid_request, whether the API caught it (a TIN without nine digits, anything other than exactly one complete name shape, a malformed body) or the IRS rejected the TIN or name as malformed. The message says what was wrong. Invalid requests never count toward usage.

​
Deferrals

A 503 with error set to verification_deferred means our system is approaching a rate limit and the request cannot be made. This may occur due to too many requests for verification using similar names and/or TINs, or simply too many requests overall. Exact rate limits are subject to change. Contact us to get your current rate limit at development@taxrock.com. No result was produced. Retry the same request after the Retry-After interval (in seconds). The header is a worst-case estimate, not a countdown; a retry may succeed much sooner.

​
Usage

Every delivered definitive result (every 200) counts toward the organization’s monthly TIN-verification usage, billed to the TaxRock organization the delegating user belongs to at the end of the month. Deferrals and invalid requests do not count.

​
Sandbox testing

The sandbox returns demo data. The result is determined by the last four digits of the TIN, so every response your integration must handle can be exercised deterministically: Requests must still be well-formed: a TIN without nine digits or a request without exactly one complete name shape returns a real 400, just as in production.