One POST creates a verification. A webhook returns it — parsed JSON, the raw IRS HTML, and a PDF, in whatever shape your LOS actually wants. Built for platforms that own their own origination stack.
# Create a verification — see moderntax.io/docs for the current path curl -X POST https://portal.moderntax.io/api/{verification-endpoint} \ -H "x-api-key: $MT_API_KEY" \ -H "Idempotency-Key: loan-4482-atlas" \ -d '{ "entity": { "legal_name": "Atlas Roofing LLC", "tin": "88-1213417", "tin_type": "ein" }, "years": [2024, 2023, 2022], "form": "auto", // we detect election status "products": ["return_transcript", "record_of_account"], "authorization": { "mode": "upload" }, "reference": "SBA-7a-4482", "schema": "partner.v2" }' # 202 Accepted { "id": "vrf_8af3c12e", "status": "awaiting_authorization", "form_detected": "1120S", "authorization_url": "https://.../8821/vrf_8af3c12e.pdf", "estimated_complete": "2026-08-11T16:00:00Z" }
# POST to your endpoint when the pull completes { "event": "verification.completed", "id": "vrf_8af3c12e", "reference": "SBA-7a-4482", "form": "1120S", "compliance": { "status": "warning", "unfiled_years": [2025], "civil_penalties": false, "balance_due": 0 }, "years": { "2024": { "gross_receipts": 4182910, "total_income": 4204118, "net_income": 612488, "total_tax": 0 } }, "artifacts": { "parsed": "https://.../parsed.json", "raw_html": "https://.../irs.html", "pdf": "https://.../transcript.pdf" } }
No polling loops required — every transition fires a webhook, and a status endpoint is available if you'd rather poll.
Create a verification with the entity, years, and products. Send form:"auto" and we resolve the actual election status before pulling.
We return a pre-populated 8821 at authorization_url. Route it through your own signature flow, then POST it back — or set mode:"cached" to reuse one inside the 120-day window.
Status moves to in_progress. A credentialed expert on our network works the IRS PPS line with their own CAF — never a single shared credential.
verification.completed fires with parsed JSON, raw IRS HTML, and PDF. Same-day target available on integrated plans, 24h standard.
Every platform wants a different shape — some want four quarters of 941 detail, some want three Records of Account and nothing else. Name a schema on the request and every payload comes back in it. We version yours; it doesn't break when we ship.
Set schema per request, or pin a default per API key.
// schema: "minimal" — just tell me if it's clean { "id": "vrf_8af3c12e", "reference": "SBA-7a-4482", "form": "1120S", "status": "complete", "years_filed": [2024, 2023, 2022], "years_unfiled": [], "flags": "clean", "pdf": "https://.../transcript.pdf" }
// schema: "underwriting" — the five lines a credit memo needs { "id": "vrf_8af3c12e", "form": "1120S", "entity": { "legal_name": "Atlas Roofing LLC", "naics": "238160", "established": "2014-03-11", "election_status": "S-Corp · required 1120S" }, "years": { "2024": { "gross_receipts": 4182910, "total_income": 4204118, "deductions": 3591630, "net_income": 612488, "total_tax": 0 }, "2023": { "gross_receipts": 3740228, "total_income": 3752901, "deductions": 3298440, "net_income": 454461, "total_tax": 0 } }, "compliance": { "status": "clean", "civil_penalties": false, "balance_due": 0, "liens": [], "unfiled_years": [] }, "sba_sop": { "transcript_type": "record_of_account", "compliant": true } }
// schema: "raw" — you parse it yourself { "id": "vrf_8af3c12e", "artifacts": [ { "year": 2024, "type": "record_of_account", "html": "https://.../2024-roa.html", "pdf": "https://.../2024-roa.pdf", "sha256": "9f2c…a41b" }, { "year": 2024, "type": "return_transcript", "html": "https://.../2024-rt.html", "pdf": "https://.../2024-rt.pdf", "sha256": "3d81…7c02" } ], "retrieved_at": "2026-08-10T15:42:11Z", "caf_on_file": true, "authorization_expires": "2026-12-08" }
An underwriter who logs in sees the request your LOS created — same record, same artifacts, same audit trail. Your engineers integrate; your credit team never has to.
Structured payload against your pinned schema, delivered by webhook with signature verification and automatic retry.
# your handler POST /webhooks/moderntax X-MT-Signature: t=1754…,v1=8a3f… { "event": "verification.completed", "reference": "SBA-7a-4482", "schema": "partner.v2" }
The identical request in the portal — including the ones nobody ordered by hand. Downloadable indefinitely, for the audit that shows up eight months later.
Every pull runs under a credentialed practitioner's own CAF number and their own fax line. No single credential to get flagged — the failure mode that took the last API-first vendor offline doesn't exist here.
Records of Account and Return Transcripts delivered in the form the SOP expects, with source and retrieval timestamp on every artifact. Audit-defensible, not screenshots.
Set monitor:true on a conditioned year and we re-poll until it lands, then auto-cancel. Billed only when a fresh pull returns something new — never for an empty check.
A lightweight lien-and-compliance check on a 1099 individual or single-member entity — for vetting brokers, not underwriting a loan. Priced below a full verification.
Replayable fixtures for every terminal state — clean, no-record, civil penalty, wrong-election, IRS auth failure. Test the unhappy paths before you're live.
Send Idempotency-Key and a retry never double-charges or double-pulls. Rate limits and usage are visible per key in the dashboard your team already has.
All requests authenticate with an x-api-key header against https://portal.moderntax.io. Rate limits and per-key usage are visible in your dashboard.
| Method | Endpoint | What it does |
|---|---|---|
| POST | /api/webhook/employment-intakeLive in production | Submit an employment & income verification. Takes request_token, employee_name, employee_ssn, and years[]. Returns request_id plus a usage object with requests used and remaining. |
The transcript ordering, authorization-upload, and usage endpoints are documented in the full API reference at moderntax.io/docs. They are not reproduced here so this page can’t drift out of sync with the canonical reference — check the docs, or email matt@moderntax.io and we’ll send the current spec with your sandbox keys.
One flat per-entity price covers the Return Transcript, the Record of Account, entity-transcript detection, and compliance screening — there's no line-item ladder per document type. Where you land depends on committed monthly volume, and we'll quote it on a short call.
| What you get at every price point | Unit rate |
|---|---|
| Per verified entity (TIN) Return Transcript + Record of Account, all requested years · entity-transcript / election-status detection included · compliance flag screening · unlimited team seats · REST API, webhooks and portal access on integrated plans. Rejections are never billed. Nothing re-pulls without you asking. Volume commitments move the rate down from here. | from $39.99/ entity |
A definitive IRS result bills — including "no record of return filed," which is a real underwriting finding. Rejections (bad EIN, name mismatch, signer not on record) and abandoned pulls never bill, and we return the specific field to fix.
Tell us your expected monthly entity volume and whether you're pulling for your own book or reselling under your own brand. We come back with a firm per-entity rate the same day — no procurement cycle to get a number. Quotes already in flight are honored exactly as written.
Tell us your schema preference and volume band and we'll provision sandbox keys plus a staging webhook the same day — no procurement cycle to start testing.