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 at progressively increasing intervals - every 10, 20 minutes, then hourly - until a valid response is received. 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.

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 three 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

Recommendation: Most Baselayer customers use Pause & 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 Proprietor Verification - When to rely on TIN validation alone
• Business Search: Best Practices - Rules-based verification with TIN as one factor