ModernTax API Documentation

Version 3.0 | IRS-Sourced Income Verification Platform

← Back to Home

Overview

ModernTax provides direct IRS income and employment verification through three specialized APIs:

Base URLs

Sandbox: https://sandbox.moderntax.io/.netlify/functions/employment-verify

Production: https://api.moderntax.io/v1

Authentication

All API requests require authentication via API key in the header:

X-API-Key: your_api_key_here

# Sandbox testing key:
X-API-Key: mt_sandbox_employer_2025_demo
Note: Contact [email protected] for production API keys and pricing information.

Benefits Eligibility API

POST/verify

Determine eligibility for Medicaid and SNAP benefits with MAGI calculations.

Request Body:

{
  "use_case": "benefits",
  "applicant": {
    "ssn": "111-11-1111",
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-01-01"
  },
  "state": "CO",
  "household_size": 1,
  "consent_timestamp": "2024-09-17T15:00:00Z"
}

Response:

{
  "request_id": "req_1694965200000",
  "status": "completed",
  "use_case": "benefits",
  "data_preview": {
    "annual_income": 15000,
    "magi": 16500,
    "eligibility": {
      "medicaid": true,
      "snap": true,
      "medicaid_threshold": 20782.8,
      "snap_threshold": 19578
    }
  }
}

Test SSNs - Benefits

SSN Annual Income MAGI Medicaid SNAP
111-11-1111 $15,000 $16,500 ✅ Eligible ✅ Eligible
222-22-2222 $22,000 $23,500 ❌ Not Eligible ✅ Eligible
333-33-3333 $45,000 $47,000 ❌ Not Eligible ❌ Not Eligible

Lending Verification API

POST/verify

Verify income for lending decisions with AGI and document availability.

Request Body:

{
  "use_case": "lending",
  "borrower": {
    "ssn": "444-44-4444",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "loan_type": "mortgage",
  "years_requested": 2,
  "consent_timestamp": "2024-09-17T15:00:00Z"
}

Response:

{
  "request_id": "req_1694965200001",
  "status": "completed",
  "use_case": "lending",
  "verification_data": {
    "adjusted_gross_income": 85000,
    "wage_income": 75000,
    "self_employment_income": 10000,
    "filing_status": "married_filing_jointly",
    "documents_available": {
      "form_1040": true,
      "form_w2": true,
      "schedule_c": true
    }
  }
}

Test SSNs - Lending

SSN AGI W-2 Income Self-Employment Documents
444-44-4444 $85,000 $75,000 $10,000 1040, W-2, Schedule C
555-55-5555 $120,000 $0 $120,000 1040, Schedule C
666-66-6666 $150,000 $100,000 $35,000 1040, W-2, Schedule C

Employment Verification API

POST/verify

Detect overemployment and analyze W-2/1099 income sources.

Request Body:

{
  "use_case": "employment",
  "candidate_info": {
    "ssn": "777-77-7777",
    "first_name": "Bob",
    "last_name": "Johnson"
  },
  "consent_token": "consent_abc123",
  "service_level": "express"
}

Response:

{
  "request_id": "req_1694965200002",
  "status": "completed",
  "use_case": "employment",
  "overemployment_risk": "low",
  "employer_count": 1,
  "total_wages": 95000,
  "w2_count": 1,
  "primary_employer": "TechCorp Solutions Inc"
}

Test SSNs - Employment

SSN Risk Level W-2 Count Total Wages Scenario
777-77-7777 Low 1 $95,000 Single Employer
888-88-8888 High 3 $255,000 Multiple Concurrent W-2s
999-99-9999 Medium 1 $135,000 W-2 + 1099 Income

Testing

Health Check Endpoint

GET/health

Check API status and available endpoints.

{
  "status": "healthy",
  "version": "3.0.0",
  "endpoints": {
    "health": "GET /health",
    "verify": "POST /verify"
  },
  "use_cases": ["benefits", "lending", "employment"]
}

Quick Test URLs

Error Codes

Code Description Resolution
200 Success Request completed successfully
400 Bad Request Check required fields and format
401 Unauthorized Invalid or missing API key
403 Forbidden Expired consent (72hr window)
404 Not Found Invalid endpoint
429 Rate Limited Implement exponential backoff
500 Server Error Contact [email protected]

Need Help?

Contact our support team for API keys and integration assistance:

📧 [email protected]