[May 29, 2024] Enhancements to IRS Validation Retries

Since the launch of Baselayer, business search has included support for handling retries when the IRS TIN validation service becomes temporarily unavailable. This retry support is transparent and experienced by users as increased latency when the IRS services have intermittent issues on the order of seconds or minutes.

In this release, Baselayer is expanding the IRS Validation retry functionality to handle IRS availability issues on the order of hours or even days long outages. These change enhance the overall resilience of business searches where the TIN matching is a critical component of the lender workflow where processing cannot proceed until the TIN matching has been fully resolved.

What is changing?

Prior to this release, business searches that encountered a long-term TIN verification failure would be reported as a negative tin_matched=False attribute value of the search result. In this release, searches that encounter a long-term TIN verification outage will return with a tin_matched=null value to indicate that TIN verification was unable to complete within the business search execution SLA. These searches will be subject to the retry logic detailed below.

This API change is accompanied by a new badge in the Baselayer Console visually indicating which searches are in this state so that users can immediately identify searches subject to TIN verification retry.

How does TIN verification retry work?

Business searches that cannot complete TIN verification during the initial search execution become queued into a new batch processor that retries them several times a day attempting to complete the search. They remain in the queue being retried every few hours until the IRS TIN verification API becomes available once more and verification completes successfully.

Once the TIN verification has completed, the TIN verification information is used to recompute the Baselayer KYB and Risk scores and the updated results are reported via a new BusinessSearch.updatedwebhook.

The BusinessSearch.updated webhook will contain the final binary tin_matched value and the new scores. The schema is identical to the familiar BusinessSearch.completed payload.

Users who wish to halt their processing workflows can do so by inspecting the search results payload, flagging any searches with tin_matched=nullvalue as being in TIN verification retry, and await the BusinessSearch.updated payload which will contain tin_matched=(true|false)and a refreshed set of KYB and risk scores in the payload.