ModernTax API

Verify employment, income, and tax payments with government-sourced data

SOC 2 Type II

Getting Started

The ModernTax API provides two comprehensive verification solutions: Employment & Income Verification for W-2/1099 data, and Tax Payment Verification for IRS payment confirmation.

Getting an API Key

Contact matt@moderntax.io to provision an API key. New accounts include 3 free requests to test the API.

Authentication

All API requests require authentication via the x-api-key header.

API keys follow the format: mt_live_emp_YOUR_API_KEY for Employment API and mt_live_tpv_YOUR_API_KEY for Tax Payment API.

CURL EXAMPLE 
curl -X GET https://portal.moderntax.io/api/webhook/employment-result \
  -H "x-api-key: mt_live_emp_your_api_key_here" \
  -H "Content-Type: application/json"

Base URL

All API requests should be made to:

BASE URL 
https://portal.moderntax.io

Employment & Income Verification API

Submit employment verification requests, poll for completion status, and receive structured W-2 and 1099 income data — all sourced from IRS Wage & Income transcripts.

POST /api/webhook/employment-intake

Submit Verification Request - Create a new employment/income verification request for a given employee.

Request Body Parameters

Parameter Type Required Description
request_token string ✓ Your unique identifier for this request. Used for polling results.
employee_name string ✓ Full legal name of the employee
employee_ssn string ✓ Social Security Number. Masked to last 4 digits in storage.
years string[] ✓ Array of tax years to verify (e.g., ["2022", "2023"])
employee_address object Optional Object with street, city, state, zip fields for address verification

Example Request

JSON 
curl -X POST https://portal.moderntax.io/api/webhook/employment-intake \
  -H "x-api-key: mt_live_emp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "request_token": "req_emp_12345_john_2023",
    "employee_name": "John Doe",
    "employee_ssn": "123-45-6789",
    "years": ["2022", "2023"],
    "employee_address": {
      "street": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102"
    }
  }'

Example Response

JSON 200 OK 
{
  "status": "pending",
  "request_token": "req_emp_12345_john_2023",
  "created_at": "2024-03-22T14:30:00Z",
  "estimated_completion": "2024-03-23T14:30:00Z",
  "usage": {
    "used": 1,
    "remaining": 2,
    "limit": 3
  }
}
GET /api/webhook/employment-result?token={request_token}

Get Verification Result - Poll for status and results once the verification is complete.

Polling Recommendation: Employment verification typically completes within 30-60 minutes, though may take until the next business day. Poll every 2-5 minutes after initial submission.

Example Request (Pending)

JSON RESPONSE 
{
  "status": "pending",
  "request_token": "req_emp_12345_john_2023",
  "message": "Verification in progress. Please check again later."
}

Example Response (Completed)

JSON 200 OK 
{
  "status": "completed",
  "request_token": "req_emp_12345_john_2023",
  "employee_name": "John Doe",
  "employee_ssn_last4": "6789",
  "years_verified": ["2022", "2023"],
  "employers": [
    {
      "year": "2023",
      "employer_name": "TechCorp Inc",
      "employer_ein": "12-3456789",
      "w2_wages": 145000.00,
      "federal_tax_withheld": 28900.00,
      "state_tax_withheld": 10440.00
    }
  ],
  "transcript_urls": [
    "https://portal.moderntax.io/transcripts/emp_2023_jdoe.pdf",
    "https://portal.moderntax.io/transcripts/emp_2022_jdoe.pdf"
  ],
  "completed_at": "2024-03-22T16:45:00Z"
}
PATCH /api/webhook/employment-result?token={request_token}

Push Result Data - Send structured employment data back to ModernTax for record-keeping and audit trail.

Request Body Parameters

Parameter Type Description
external_reference_id string Your internal ID for cross-reference
loan_amount number Associated loan amount if applicable
verification_status string Status from your system: "approved", "rejected", "review"

Example Request

JSON 
curl -X PATCH https://portal.moderntax.io/api/webhook/employment-result \
  -H "x-api-key: mt_live_emp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "request_token": "req_emp_12345_john_2023",
    "external_reference_id": "LOAN-2024-001234",
    "loan_amount": 250000,
    "verification_status": "approved"
  }'

Example Response

JSON 200 OK 
{
  "status": "acknowledged",
  "request_token": "req_emp_12345_john_2023",
  "stored_at": "2024-03-22T17:00:00Z"
}

Tax Payment Verification API NEW

Confirm IRS tax payments in real-time using Record of Account transcripts. One-time consent authorization, same-day verification, full transaction history.

Payment Verification extends ModernTax's existing tax verification infrastructure to confirm that federal tax payments have been received and applied by the IRS. Same transcript infrastructure used by 60+ SBA lenders.

How It Works

Business Signs 8821
→
ModernTax Processes
→
IRS Authorizes
→
Record Pulled
→
Payment Verified

Key Benefits

  • Same-day confirmation: Verify payments the same day vs 3-4 week IRS reconciliation
  • One-time authorization: Single 8821 consent covers ongoing transcript pulls
  • Full form coverage: Support for 1120S, 1120, 1065, and 1040 tax forms
  • Government-sourced data: Direct from IRS's own ledger via transcript service
  • Dual access: API or web portal access to verification results

Record of Account

Pull the IRS Record of Account transcript for a business once 8821 authorization is active. Returns complete account history, transactions, and balances.

POST /v2/transcripts/record-of-account

Retrieve Record of Account - Fetch the IRS Record of Account transcript showing payment history and account status.

Request Parameters

Parameter Type Required Description
consent_id string ✓ The consent_id from 8821 authorization
tax_period string ✓ Tax period end date (YYYY-MM-DD format)
form_type string Optional Override form type (defaults to entity_type from consent)

Example Request

JSON 
curl -X POST https://portal.moderntax.io/v2/transcripts/record-of-account \
  -H "x-api-key: mt_live_tpv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "consent_id": "cons_4v82j9k2p1m5",
    "tax_period": "2022-12-31",
    "form_type": "1120S"
  }'

Example Response

JSON 200 OK 
{
  "tracking_number": "110049838477",
  "form_type": "1120S",
  "tax_period_ending": "2022-12-31",
  "entity": {
    "name": "DAVI AUT IN",
    "tin": "XX-XXX8247",
    "activity_code": "811110"
  },
  "account_summary": {
    "balance": 0.00,
    "accrued_interest": 0.00,
    "accrued_penalty": 0.00,
    "total_tax_per_return": 0.00,
    "balance_status": "clear"
  },
  "return_information": {
    "gross_receipts": 294570.00,
    "total_income": 200489.00,
    "total_deductions": 167396.00,
    "taxable_income": 33093.00,
    "compensation_of_officers": 35000.00,
    "total_assets_eoy": 156738.00
  },
  "transactions": [
    {
      "code": 150,
      "description": "Tax return filed",
      "date": "2023-06-05",
      "amount": 0.00,
      "cycle": "202320"
    },
    {
      "code": 670,
      "description": "Estimated tax payment",
      "date": "2023-04-15",
      "amount": -8273.25,
      "cycle": "202315"
    },
    {
      "code": 460,
      "description": "Extension of time to file",
      "date": "2023-04-03",
      "amount": 0.00,
      "cycle": "202314"
    }
  ],
  "shareholder_info": {
    "number_of_shareholders": 1,
    "total_property_distribution": 8500.00,
    "income_loss": 33093.00,
    "retained_earnings_eoy": 58737.00
  },
  "pulled_at": "2024-03-22T15:30:00Z"
}

Payment Confirmation

Confirm that a specific tax payment has been received and applied by the IRS. Returns matching transaction details and account status.

POST /v2/payments/confirm

Confirm Payment - Verify that a payment has been applied to the IRS account.

Request Parameters

Parameter Type Required Description
consent_id string ✓ The consent_id from 8821 authorization
tax_period string ✓ Tax period end date (YYYY-MM-DD format)
expected_amount number Optional Expected payment amount to match against
payment_date string Optional Expected payment date (YYYY-MM-DD format)

Example Request

JSON 
curl -X POST https://portal.moderntax.io/v2/payments/confirm \
  -H "x-api-key: mt_live_tpv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "consent_id": "cons_4v82j9k2p1m5",
    "tax_period": "2022-12-31",
    "expected_amount": 8273.25,
    "payment_date": "2023-04-15"
  }'

Example Response

JSON 200 OK 
{
  "confirmation_id": "pay_confirm_8k3j2m1l",
  "status": "confirmed",
  "tax_period": "2022-12-31",
  "account_balance": 0.00,
  "payment_matched": true,
  "matched_transaction": {
    "code": 670,
    "description": "Estimated tax payment",
    "date": "2023-04-15",
    "amount": -8273.25
  },
  "filing_status": {
    "entity_type_confirmed": "1120S",
    "liens": false,
    "collection_activity": false,
    "balance_due": 0.00
  },
  "confirmed_at": "2024-03-22T15:35:00Z"
}

Payment Confirmation Status Values

Status Description
confirmed Payment has been found and applied to the account
pending Payment is in process but not yet applied
misapplied Payment was applied to wrong tax period or entity
not_found No matching payment found on account
partial Partial payment applied, remaining amount pending

End-to-End Payment Solution

Complete payment submission and confirmation workflow. ModernTax handles the 8821 consent layer, routes payments through connected processors, and pulls records to close the loop.

Integrated Workflow: ModernTax handles the 8821 consent layer, routes payments through connected processors (e.g., Remitian ACH), and pulls the Record of Account to confirm payments are applied. No manual follow-up needed.
POST /v2/payments/submit-and-confirm

Submit & Confirm - Combined endpoint to submit a payment and confirm it in one request.

Request Parameters

Parameter Type Required Description
consent_id string ✓ The consent_id from 8821 authorization
payment_type enum ✓ One of: estimated_quarterly, balance_due, extension
tax_period string ✓ Tax period end date (YYYY-MM-DD format)
amount number ✓ Payment amount in dollars
payment_method object ✓ Payment details (type: ach/wire, account info)
auto_confirm boolean Optional Auto-confirm payment after posting (default: true)

Example Request

JSON 
curl -X POST https://portal.moderntax.io/v2/payments/submit-and-confirm \
  -H "x-api-key: mt_live_tpv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "consent_id": "cons_4v82j9k2p1m5",
    "payment_type": "estimated_quarterly",
    "tax_period": "2024-03-31",
    "amount": 15000.00,
    "payment_method": {
      "type": "ach",
      "account_number": "XXXXXX1234",
      "routing_number": "XXXXXX789"
    },
    "auto_confirm": true
  }'

Example Response

JSON 202 ACCEPTED 
{
  "payment_id": "pay_7k2m3j1l9p",
  "status": "processing",
  "amount": 15000.00,
  "payment_type": "estimated_quarterly",
  "tax_period": "2024-03-31",
  "expected_posting_date": "2024-03-25",
  "confirmation_expected": "2024-03-26",
  "message": "Payment submitted. Confirmation will occur automatically once IRS posts the transaction."
}

Quarterly Monitoring

Set up automated monitoring of tax account status. Receive webhook notifications for payment posts, balance changes, liens, or entity election mismatches.

POST /v2/monitoring/schedule

Schedule Monitoring - Set up automated quarterly or monthly account monitoring.

Request Parameters

Parameter Type Required Description
consent_id string ✓ The consent_id from 8821 authorization
frequency enum ✓ One of: quarterly, monthly, on_demand
webhook_url string ✓ HTTPS endpoint to receive monitoring notifications
check_items string[] Optional Array of checks: payment_posted, balance_change, lien_filed, entity_election

Example Request

JSON 
curl -X POST https://portal.moderntax.io/v2/monitoring/schedule \
  -H "x-api-key: mt_live_tpv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "consent_id": "cons_4v82j9k2p1m5",
    "frequency": "quarterly",
    "webhook_url": "https://yourapp.com/webhooks/irs-monitoring",
    "check_items": ["payment_posted", "balance_change", "entity_election"]
  }'

Example Response

JSON 201 CREATED 
{
  "monitor_id": "mon_5p2k9j1m3l",
  "consent_id": "cons_4v82j9k2p1m5",
  "frequency": "quarterly",
  "status": "active",
  "check_items": ["payment_posted", "balance_change", "entity_election"],
  "next_check": "2024-06-22T12:00:00Z",
  "created_at": "2024-03-22T14:30:00Z"
}

S-Corp Services

Only ~10% of 5.3M US S-Corps have an IRS Business Tax Account. ModernTax bridges the gap via 8821 access, enabling verification of entity status and transaction history.

Entity Election Detection

A common issue: businesses file Form 2553 (S-Corp election) but the IRS still classifies the entity as a C-Corp (1120) or Partnership (1065) on their tax account. This endpoint detects such mismatches.

EXAMPLE RESPONSE - ENTITY MISMATCH 
{
  "entity_election": {
    "expected_type": "1120S",
    "irs_type_on_record": "1120",
    "match": false,
    "alert": "Entity election mismatch detected. Form 2553 filed but IRS has not updated classification."
  }
}

Transaction Codes Reference

Understanding transaction codes on the Record of Account helps interpret account activity and identify issues.

Payment Codes

Code Description Amount
610 Payment with return Negative (credit)
650 Electronic payment Negative (credit)
660 Estimated payment Negative (credit)
670 Subsequent payment Negative (credit)
700 Credit applied Negative (credit)
706 Credit transferred out Negative (credit)

Filing & Account Codes

Code Description Type
150 Tax return filed Filing Event
460 Extension of time to file Filing Event
290 Additional tax Account Adjustment
300 Audit adjustment Account Adjustment
570 Action pending Account Status
582 Lien filed Account Status

Webhooks

ModernTax sends webhook notifications for key events in the payment verification and monitoring workflows.

Event Types

Event Trigger
consent.authorized 8821 form authorized by IRS
consent.rejected IRS rejected 8821 authorization
payment.confirmed Payment found and applied to account
payment.not_found Expected payment not found on account
payment.misapplied Payment applied to wrong tax period
account.balance_change Account balance changed since last check
account.lien_filed Tax lien has been filed
entity.election_mismatch Entity type mismatch detected (e.g., 2553 filed but IRS shows 1120)
irs.letter_detected IRS correspondence detected on account

Example Webhook Payload

Event: payment.confirmed

JSON 
{
  "event_id": "evt_9m2l7k3j1p",
  "event_type": "payment.confirmed",
  "timestamp": "2024-03-25T14:30:00Z",
  "consent_id": "cons_4v82j9k2p1m5",
  "data": {
    "confirmation_id": "pay_confirm_8k3j2m1l",
    "tax_period": "2022-12-31",
    "amount": 8273.25,
    "matched_transaction": {
      "code": 670,
      "description": "Estimated tax payment",
      "date": "2023-04-15"
    },
    "account_balance": 0.00,
    "status": "confirmed"
  }
}

Reference

Error Codes

Code Description Resolution
401 Unauthorized - Missing or invalid API key Verify x-api-key header and key format
400 Bad Request - Missing required parameters Check request payload for required fields
404 Not Found - Request token or consent_id does not exist Verify the token/consent_id is correct and still valid
409 Conflict - Duplicate request token Use a unique request_token for each new request
429 Too Many Requests - Rate limit exceeded Contact sales@moderntax.io for rate limit increase

Rate Limits

Free Tier: 3 requests total to test the API.

For production use or higher volumes, contact sales@moderntax.io.

Rate limits are enforced per API key per minute. In excess, requests return HTTP 429 with retry information.

Data Schemas

TypeScript interface definitions for common data structures:

EmploymentData

TYPESCRIPT 
interface EmploymentData {
  request_token: string;
  employee_name: string;
  employee_ssn_last4: string;
  years_verified: string[];
  employers: EmploymentEmployer[];
  transcript_urls: string[];
  completed_at: string;
}

interface EmploymentEmployer {
  year: string;
  employer_name: string;
  employer_ein: string;
  w2_wages: number;
  federal_tax_withheld: number;
  state_tax_withheld: number;
}

interface EmploymentYearData {
  year: string;
  gross_income: number;
  federal_tax: number;
  state_tax: number;
  social_security_tax: number;
  medicare_tax: number;
}

PaymentVerificationData

TYPESCRIPT 
interface PaymentConfirmation {
  confirmation_id: string;
  status: "confirmed" | "pending" | "misapplied" | "not_found" | "partial";
  tax_period: string;
  account_balance: number;
  payment_matched: boolean;
  matched_transaction?: Transaction;
  filing_status: FilingStatus;
}

interface Transaction {
  code: number;
  description: string;
  date: string;
  amount: number;
  cycle?: string;
}

interface FilingStatus {
  entity_type_confirmed: string;
  liens: boolean;
  collection_activity: boolean;
  balance_due: number;
}