How does Baselayer handle IRS TIN matching outages?

The IRS TIN matching service is the only step in a business search that depends on a live third-party system, so it is the one step that can be temporarily unavailable. When that happens, your search is not held up.

1. The search completes normally with all other results. The tin_matched field is null, which means the check could not be completed, not that it failed. The response also carries a warning that IRS validation is unavailable.

2. We automatically retry the TIN check in the background. Retries run every 15 minutes and pause while the IRS is down, so they resume as soon as the service is healthy again. You do not need to resubmit the search.

3. When the IRS responds, we update the original search with the real result and send a BusinessSearch.updated webhook. If you fetch the same search ID after that point, it returns the resolved tin_matched value.

In the console, a search that finished while the IRS was unavailable shows an IRS Error badge in place of the TIN result until the retry completes.

For your integration, treat tin_matched = null as "pending" and listen for BusinessSearch.updated rather than treating it as a no-match. Our guide walks through the webhook flow: BusinessSearch.updated webhook guide.