Real-Time IRS US TIN Matching

Taxbit's Real-Time IRS US TIN Matching feature allows you to validate a name and U.S. TIN combination against the IRS records via API. Referencing Taxbit’s associated API doc (Real-Time TIN Validation), the endpoint for this workflow is POST /v1/validation/us-tin, and it uses tenant-scoped authentication.

The results from the IRS typically take 2 - 3 seconds, however, there are instances where a result may not be available immediately. The IRS has limitations around the number of times you can send the same name and/or TIN within a 24-hour period. They do this in order to prevent users from abusing the system to identify someone’s TIN. As a result, checking TINs for common names (e.g., John Smith) can be delayed by several days. If validation cannot be completed immediately, such as when the IRS is unavailable or rate limits apply, the request is queued for asynchronous processing instead of failing immediately.

Submitting a Real-Time IRS US TIN Validation Request via API

To submit a real-time TIN validation request, send a JSON body with the following:

Field	Definition	Example
legal_name	Required; must be the full legal name of the individual or entity. It cannot be an empty string.	John Doe
tin	Required; must be a string containing exactly 9 digits, with no hyphens, symbols, or punctuation.	987654321

Please note: You can also pass the optional use_async query parameter. When use_async=true, Taxbit immediately returns a PENDING status and an identifier that can be used to retrieve the result later. This is useful when you want to avoid waiting for IRS response latency during the initial request.

Reviewing the Results

The response includes the following:

id
legal_name
tin
status
validation_date

If the request is handled asynchronously, there are two supported ways to receive the final result:

Poll the GET /v1/validations/us-tin/{tin_validation_id} endpoint using the id returned by the original request. The GET response has the same shape as the POST response. If the status is still PENDING, continue polling until it resolves.
Configure webhooks so Taxbit can send a notification after the request is processed. The real-time TIN validation webhook event is RTTM_TIN_VALIDATION and includes the validation_id, status, and validation_date.

The real-time TIN validation endpoint can return the following statuses:

Status	Definition
PENDING	The request was submitted and has not yet been validated.
VALID_SSN_MATCH	The SSN matches IRS records.
VALID_EIN_MATCH	The EIN matches IRS records.
VALID_SSN_EIN_MATCH	Both the SSN and EIN match IRS records.
MISMATCH	The name and TIN do not match IRS records.
TIN_NOT_ISSUED	The TIN has not been issued by the IRS.
INVALID_DATA	The submitted data is malformed or incomplete for validation.
FOREIGN	The TIN is foreign and is not validated against the IRS.
ERROR	An error occurred during IRS validation.

Using this with the React SDK

If you are using the Tax Documentation React SDK for W-9 collection, you can enable this behavior with the realTimeTinValidation prop on W-FORM. This prop is W-9 only, requires RTT configuration, and attempts TIN matching at submission so mismatches can be surfaced inline rather than only later in the process.

Please note: If realTimeTinValidation is not enabled, W-9 submissions default to batch processing.

When using the SDK, note that onSuccess confirms Taxbit received the submission, not that IRS validation is complete. Final validation results should be read from tinStatus or received through webhook-driven status updates.