My TIN result is not matched. How do I tell an IRS mismatch from a failed lookup?

Look at the value of tin_matched and the search’s warnings:

• true: the IRS confirmed the TIN and name combination.

• false: the IRS answered, and the TIN and name do not match its records (or the TIN was not issued). This is a real mismatch.

• null: we did not get an answer from the IRS. Either no TIN was submitted, or the IRS service was unavailable, in which case the search includes a warning that IRS validation is unavailable.

A failed TIN lookup does not fail the whole search. The search still completes with its other results, and tin_matched stays null.

When the IRS was unavailable, we retry the TIN check automatically. If the retry gets an answer, the search is updated and a BusinessSearch.updated webhook is sent, so consume that webhook or re-fetch the search.