Guide: IRS Outage Handling

Handling IRS Outages: TIN Verification Resilience

Baselayer maintains a real-time integration with the Internal Revenue Service (IRS), which enables real-time verification of Taxpayer Identification Numbers (TINs) against corresponding business or individual names. This ensures maximum accuracy, timeliness, and coverage in our verification process. A known and infrequent issue involves temporary unavailability of the IRS platform used for TIN verification. We commonly refer to these instances as IRS outages. Being aware of these potential scheduled or unscheduled outages can help in planning and mitigating disruptions when using the IRS TIN verification. This guide explains how Baselayer handles these situations automatically and how to build resilient verification workflows that gracefully handle temporary TIN validation unavailability. TIN Check uptime is available in our status page - which provides an overview of our API, Console and TIN Match availability.

Baselayer System Behavior During IRS Outages

If a TIN is provided in the search input and the IRS TIN Matching service is unavailable at the time of processing, Baselayer will continue with all other parts of the verification process and notify clients accordingly, returning all available data except the TIN verification status. The response explicitly states that the IRS service was unavailable at the time of the request.

Webhook Behavior During Outage

Webhook Type: BusinessSearch.completed or BusinessSearch.failed
TIN Status Field:
- tin_matched = null
Warnings Field:
- warnings = "IRS Validation is unavailable."

Webhook Behavior After Outage Resolution

Once the IRS TIN Matching service becomes available again, Baselayer will automatically retry validation of previously failed TIN checks.
Upon successful validation, an updated webhook is sent:
- Webhook Type: BusinessSearch.updated
- TIN Status Field:
  - tin_matched = true/false (based on actual IRS response)
- Warnings Field:
  - Omitted if validation is successful.

Retry Logic & Queue Management

During an IRS outage, all business searches where IRS TIN validation was not possible are placed into a retry queue. Baselayer initiates an automated retry sequence to reattempt verification. Retries are performed every 15 minutes for up to about 24 hours. If no BusinessSearch.updated webhook arrives after that, retries have stopped and tin_matched stays null. Retries occur sequentially to manage load and avoid redundant requests. Once the IRS service is restored, Baselayer automatically reprocesses any previously incomplete TIN verifications, updates the associated records, and notifies the affected customer systems with the completed information.

Illustrative Example Timeline

This example demonstrates Baselayer’s automatic retry behavior during a transient IRS outage. The key takeaway: you only need to handle the webhooks - Baselayer manages all retry logic automatically.

Time (UTC)	Event Description
09:00:00	Business Search initiated via Baselayer API or Console.
09:00:10	BusinessSearch.completed webhook emitted. TIN verification skipped due to IRS outage.
09:00:10 onward	Subsequent Business Searches continue processing. If IRS service recovers mid-search, retries are triggered early.
09:15:00	First retry (+15 minutes) of previously failed TIN check.
09:30:00	Second retry (+15 minutes) succeeds. BusinessSearch.updated webhook emitted with verified tin_matched value.
09:30:00 onward	Remaining queued cases are reprocessed automatically and updated webhooks are sent.
09:35:20	All queued TIN verifications completed. System resumes normal operation.

Expected Frequency of IRS Outages

The IRS conducts routine maintenance on its e-Services platform, which includes the TIN Matching service. While the IRS does not provide a detailed schedule of all maintenance periods, these outages are usually brief and scheduled during off-peak hours to minimize disruption. The most common maintenance window is on Sundays from 12:00 a.m. to 4:00 p.m. ET. In addition, the IRS infrequently faces unscheduled outages in the IRS TIN matching service, causing high rates of failure. While metrics are not officially tracked, based on Baselayer’s experience and monitoring the estimated frequency of unscheduled outages is:

Mild to moderate disruptions - intermittent failures or degraded service - occur 1-2 times per quarter
Major outages - where the service is entirely down or timing out consistently for +2 hours - appear to occur 1-2 times per year

These figures depend heavily on tax season traffic (Jan-Apr sees much higher usage), IRS infrastructure changes, and external network load or integrations with Social Security Administration systems.

Decisioning Strategies During IRS Outages

When tin_matched = null due to an IRS outage, you’ll need a strategy for handling the application. Based on your risk tolerance and product requirements, here are two common approaches Baselayer customers use:

Strategy 1: Stop & Wait

Approach: Halt the application immediately and wait for IRS validation to complete before making any decision. How it works:

IF tin_matched == null AND "IRS Validation is unavailable." IN warnings:
    status = "PENDING_TIN_VALIDATION"
    user_message = "Your application is under review. We'll notify you shortly."
    
    # Wait for BusinessSearch.updated webhook
    # Then re-run decisioning logic with tin_matched result
    
# When BusinessSearch.updated webhook arrives:
IF tin_matched == true:
    # Continue with normal approval logic
    status = "APPROVED"
ELSE:
    status = "DECLINED"
    reason = "TIN validation failed"

Best for:

High-risk products (lending, large credit lines)
Regulated financial institutions with strict compliance requirements
Products where TIN validation is mandatory for regulatory reasons

Customer experience: Application paused, typically resolved within minutes to hours depending on outage duration.

Strategy 2: Conditional Approval

Approach: Approve the application provisionally based on all other verification checks, then monitor the TIN result when it arrives. How it works:

IF tin_matched == null AND "IRS Validation is unavailable." IN warnings:
    # Check all other verification criteria
    IF all_other_checks == PASS:
        status = "CONDITIONALLY_APPROVED"
        account_status = "ACTIVE_MONITORED"
        flag_for_tin_review = true
        user_message = "Your application is approved!"
        
    # When BusinessSearch.updated webhook arrives:
    IF tin_matched == false:
        account_status = "FROZEN"
        notify_fraud_team()
        trigger_user_reverification()
        user_message = "Account temporarily frozen for verification"
    ELSE:
        # Clear monitoring flag
        account_status = "ACTIVE"
        flag_for_tin_review = false

ELSE:
    # Normal decisioning with TIN result available
    IF tin_matched == true:
        status = "APPROVED"

Best for:

Low-risk products (marketplaces, basic accounts, vendor onboarding)
Products where speed-to-activation drives conversion
Customers with strong fraud controls beyond TIN (device signals, identity network, transaction monitoring)

Customer experience: Immediate approval, seamless onboarding. Account freeze only in rare TIN mismatch cases. Operational considerations:

Requires account freeze capabilities
Needs fraud team workflows for post-approval TIN failures
More complex to implement but better conversion
Consider limiting functionality until TIN validates (e.g., “Lite Profile”)

Note: Some customers enable a “Lite Profile” or “Pre-approved” status with limited functionality (lower transaction limits, restricted features) until final TIN validation completes.

Choosing Your Strategy

Factor	Stop & Wait	Conditional Approval
Risk Tolerance	Lower	Higher
Regulatory Requirements	TIN validation required	TIN validation optional
Speed Priority	Decision quality	Conversion rate
Operational Overhead	Minimal (just wait)	Medium (freeze workflow)
Customer Experience	Delayed approval	Immediate approval
What happens on TIN fail	Never approved	Approved then frozen
Implementation Complexity	Simple	Moderate
Best for	Lending, compliance-heavy	Marketplaces, low-risk

Recommendation: Most Baselayer customers use Stop & Wait as it provides the cleanest customer experience and simplest operational workflow. The delay is typically under 1 hour, which is acceptable for most products. Use Conditional Approval only if:

You have robust secondary fraud controls beyond TIN validation
Conversion rate is critical to your business model
You can operationally handle account freezes and customer reverification
Your risk profile allows for some exposure before full TIN validation

Testing IRS Outage Scenarios

Baselayer provides a sandbox test case that simulates IRS outage behavior, allowing you to validate your webhook handling and retry logic.

Test Case Setup

Use these exact inputs in sandbox:

{
  "name": "ampro industries inc",
  "address": "6465 n quail hollow rd ste 200 memphis tn 38120",
  "tin": "000000000"
}

Expected Behavior

Initial Response (immediate):

Webhook: BusinessSearch.completed
Fields:
- tin_matched: null
- warnings: ["IRS Validation is unavailable."]
- state: "COMPLETED"

Updated Response (immediately afterwards):

Webhook: BusinessSearch.updated
Fields:
- tin_matched: true or false (actual validation result)
- warnings: [] (empty, validation succeeded)
- All other fields remain the same

What to Verify in Your Tests

✅ Initial webhook handling: Your system correctly processes tin_matched: null according to your chosen strategy ✅ Status tracking: Application status is properly recorded and can be updated later ✅ Updated webhook handling: Your system receives and processes BusinessSearch.updated events ✅ Decisioning logic: Final approval/decline decision correctly incorporates the TIN validation result ✅ User notifications: Customers receive appropriate messages based on your strategy (pending vs. approved vs. review)

Best Practices

Monitor IRS Availability

Check Baselayer Status Page for real-time TIN check availability
Subscribe to status page notifications for proactive alerts
Monitor your own tin_matched: null and warnings rates to detect emerging issues

Webhook Handling

Always check both tin_matched and warnings fields to distinguish IRS outages from invalid TINs
Process BusinessSearch.updated events idempotently (retries may cause duplicates)
Log all webhook events for debugging and audit trails

Establish a Clear Policy

Document your IRS outage strategy for compliance audits
Train support and operations teams on expected behavior
Set SLAs for resolving pending applications (e.g., 4 hours max during business hours)

Next Steps

Understand verification workflows:

Business Search: Basics - How TIN verification fits into KYB
Business Search: Best Practices - Complete decision logic including TIN validation
Scores & Ratings - How TIN impacts KYB ratings

Implement webhook handling:

Webhooks at Baselayer - Complete webhook integration guide
Business Search: API Quickstart - Understanding Business Search responses

Handle edge cases:

Sole Proprietorship Verification - When to rely on TIN validation alone
Business Search: Best Practices - Rules-based verification with TIN as one factor

KEY CONCEPTS

PLAYBOOKS

PRODUCT GUIDES

Guide: IRS Outage Handling

Handling IRS Outages: TIN Verification Resilience

Baselayer System Behavior During IRS Outages

Webhook Behavior During Outage

Webhook Behavior After Outage Resolution

Retry Logic & Queue Management

Illustrative Example Timeline

Expected Frequency of IRS Outages

Decisioning Strategies During IRS Outages

Strategy 1: Stop & Wait

Strategy 2: Conditional Approval

Choosing Your Strategy

Testing IRS Outage Scenarios

Test Case Setup

Expected Behavior

What to Verify in Your Tests

Best Practices

Monitor IRS Availability

Webhook Handling

Establish a Clear Policy

Next Steps

​Handling IRS Outages: TIN Verification Resilience

​Baselayer System Behavior During IRS Outages

​Webhook Behavior During Outage

​Webhook Behavior After Outage Resolution

​Retry Logic & Queue Management

​Illustrative Example Timeline

​Expected Frequency of IRS Outages

​Decisioning Strategies During IRS Outages

​Strategy 1: Stop & Wait

​Strategy 2: Conditional Approval

​Choosing Your Strategy

​Testing IRS Outage Scenarios

​Test Case Setup

​Expected Behavior

​What to Verify in Your Tests

​Best Practices

​Monitor IRS Availability

​Webhook Handling

​Establish a Clear Policy

​Next Steps

Handling IRS Outages: TIN Verification Resilience

Baselayer System Behavior During IRS Outages

Webhook Behavior During Outage

Webhook Behavior After Outage Resolution

Retry Logic & Queue Management

Illustrative Example Timeline

Expected Frequency of IRS Outages

Decisioning Strategies During IRS Outages

Strategy 1: Stop & Wait

Strategy 2: Conditional Approval

Choosing Your Strategy

Testing IRS Outage Scenarios

Test Case Setup

Expected Behavior

What to Verify in Your Tests

Best Practices

Monitor IRS Availability

Webhook Handling

Establish a Clear Policy

Next Steps