Verification your platform can call.
Programmatic IRS compliance verification for the ModernTax Compliance Platform: submit an entity, obtain Form 8821 authorization, and receive the pulled transcripts plus a structured compliance read — by polling or by webhook.
Overview
A typical automated integration — how a reseller such as a lending platform runs it end to end.
Submit
Send one or more entities to POST /api/intake/transcript.
Authorize
Each entity needs a signed IRS Form 8821 — upload a pre-signed PDF you collected yourself, or let ModernTax collect the signature.
Receive results
Poll GET /api/intake/transcript?token= with an optional schema= shape, or have us POST to your webhook.
Every endpoint in this reference authenticates with an x-api-key header. The portal also exposes cookie-authenticated admin, expert, and processor endpoints; those are internal and not part of this contract.
Authentication
All requests require an x-api-key header. Live keys have the form mt_live_txn_<slug>_<12hex>.
Manage keys — rotation, webhook config, default response schema, usage — self-serve in the developer portal at portal.moderntax.io/developer. To try the API first, grab a free sandbox key; for a live key, contact matt@moderntax.io.
x-api-key: mt_live_txn_yourco_xxxxxxxxxxxx
Content-Type: application/json # or multipart/form-data where noted
Keys are stored as SHA-256 hashes and constant-time verified on every request. A missing or invalid key returns 401 via the same code path, so errors never reveal whether a partial match exists.
Base URL
https://portal.moderntax.io
Sandbox
Two sandboxes, both free and on synthetic data. Endpoints and response shapes are production-identical; nothing reaches the IRS and nothing is billed.
A. Read-only key — instant
Self-serve at portal.moderntax.io/sandbox: enter a work email and company name and you get a {company}-sandbox API key with pre-built synthetic results to poll. Capped at 250 requests. No sales call required.
B. Full order flow — staging
At https://staging.portal.moderntax.io you can run the whole integration: generate a dummy signed 8821, place orders, watch them move through the statuses and read results. Every 8821 is checked against the signed-8821 rules, and a simulated IRS returns the outcome picked by your test TIN. Ask matt@moderntax.io for a staging key.
A dummy signed 8821: the ModernTax template filled for the taxpayer you name, with a DocuSign-style Certificate of Completion. The JSON response's signed_8821 drops straight into entities[].signed_8821; add &format=pdf for the file. style picks which rule it passes or breaks.
curl "https://staging.portal.moderntax.io/api/sandbox/sample-8821?entity_name=Sandbox+Coffee+LLC&tid=00-1230002&form_type=1120S&years=2023,2024,2025&signer_name=Jordan+Example" \
-H "x-api-key: mt_live_txn_yourco_sandbox_xxxxxxxxxxxx"
{ "style": "valid",
"expect": { "verdict": "accepted", "failed_rule": null },
"signed_8821": { "pdf_base64": "JVBERi0x…", "signer_name": "Jordan Example",
"signer_email": "signer@example.com", "signed_at": "2026-10-26T17:55:00Z", "signature_vendor": "docusign" } }
| style | Result |
|---|---|
| valid (default) | accepted |
| no_audit_trail | rejected: esign_audit_trail |
| wrong_designee | rejected: designee_is_moderntax |
| signer_is_business | rejected: signer_named |
| wrong_tin | rejected: taxpayer_tin_matches |
| stale | rejected: signed_at_valid (signed 150 days ago) |
Test TINs. The last four digits of tid pick what the simulated IRS returns. Use 00- / 000- prefixes so nothing is a real taxpayer.
| Last 4 | Outcome |
|---|---|
| 0001 | Clean: every year filed, $0 balance |
| 0002 | Tax lien: balance due and a federal tax lien filed (TC 582) |
| 0003 | Balance due with penalties and interest, no lien |
| 0004 | Latest year has no return filed |
| 0005 | Wrong form: no record for the form ordered |
| 0006 | failed, irs_tin_name_mismatch, not billed |
| 0007 | failed, irs_signer_not_authorized, not billed |
| 0008 | failed, irs_8821_rejected, not billed |
| any other | Clean |
Once the 8821 is attached the entity moves irs_queue → processing (30 s) → completed / failed (90 s), advancing as you poll. Sandbox entities also carry sandbox: { scenario, error? }; an error has code, message, fix and billable: false. To skip the wait:
curl -X POST https://staging.portal.moderntax.io/api/sandbox/advance \
-H "x-api-key: mt_live_txn_yourco_sandbox_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"request_token":"test-001"}'
Webhooks are not delivered from staging (outbound calls are blocked there), so poll for results. Monitoring re-pulls are not simulated.
Submit a transcript request
Creates a request with one or more entities and queues them for IRS retrieval.
Each entity needs a signed 8821 before results can be delivered: attach one inline via entities[].signed_8821, upload one to /api/intake/8821-pdf, or let ModernTax collect the signature via /api/intake/8821.
Request
curl -X POST https://portal.moderntax.io/api/intake/transcript \
-H "x-api-key: mt_live_txn_yourco_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d @request.json
{
"request_token": "your-loan-12345", // unique per account; idempotency key
"loan_number": "your-loan-12345", // optional; used in invoice itemization
"entities": [
{
"entity_name": "ACME Holdings LLC",
"tid": "12-3456789",
"tid_kind": "EIN", // "EIN" or "SSN"
"form_type": "1120S", // optional; inferred from tid_kind if omitted
"years": ["2022","2023","2024"],
"address": "123 Main St", "city": "Austin", "state": "TX", "zip_code": "78701",
"loan_officer_name": "Jane Rep", // optional
"loan_officer_email": "jane@lender.com",
"fiscal_year_end_month": 12, // REQUIRED for 1120 / 1120S / 1065; 12 = calendar year
"loan_amount": 3250000, // optional; proposed loan in dollars (QoE screening)
"loan_purpose": "acquisition", // optional; see the field table
"signed_8821": { // optional: attach a pre-signed 8821 inline
"pdf_base64": "<base64 PDF, max 10 MB decoded>",
"persona_inquiry_id": "inq_abc123", // optional signature evidence —
"persona_verification_token": "…", // all evidence fields optional
"signer_name": "Jane Founder",
"signer_email": "jane@acme.com",
"signed_at": "2026-08-12T18:04:00Z", // ISO 8601
"signer_ip": "203.0.113.9",
"signature_vendor": "persona"
}
}
]
}
| Field | Req | Notes |
|---|---|---|
| request_token | yes | Your unique id for the request. Reusing one returns 409. |
| loan_number | no | Falls back to request_token. Used on invoices. |
| entities[].entity_name | yes | Legal name on file with the IRS. |
| entities[].tid / tid_kind | yes | EIN (XX-XXXXXXX) or SSN (XXX-XX-XXXX); "EIN"/"SSN". |
| entities[].years | yes | 4-digit years, 1990–2028. |
| entities[].form_type | no | 1040, 1065, 1120, 1120S, 941. Inferred from tid_kind if omitted. |
| entities[].fiscal_year_end_month | yes* | Month the entity’s fiscal year ends, 1–12; 12 = calendar year. Required for 1120, 1120S and 1065 (explicit or inferred from an EIN) — omitting it returns 400. Ignored for 1040 and 941, which are always calendar. The IRS keys the account by period ending, so a fiscal-year filer pulled on 12/31 comes back “No Record Found”. |
| entities[].loan_amount | no | Proposed loan in dollars, used to screen the borrower for a Quality of Earnings review. A number, or a string such as "3,250,000", "3.25M" or "750k". Anything that isn’t a positive amount returns 400. Can also be sent once at the top level of the body; a value on the entity wins. |
| entities[].loan_purpose | no | acquisition, refinance, working_capital, expansion, real_estate, equipment or other. Close variants are mapped (“change of ownership” → acquisition, “refi” → refinance); anything unrecognised is stored as other. Also accepted at the top level. An acquisition of $3M or more is flagged as requiring a QoE under SBA SOP 50 10 8.1. |
| entities[].signed_8821 | no | Inline pre-signed 8821: pdf_base64 (≤10 MB decoded) plus optional evidence fields (persona_inquiry_id, persona_verification_token, signer_name, signer_email, signed_at, signer_ip, signature_vendor). |
Response 201
{
"success": true,
"request_id": "uuid",
"request_token": "your-loan-12345",
"loan_number": "your-loan-12345",
"status": "irs_queue",
"entities": [
{ "entity_id": "uuid", "entity_name": "ACME Holdings LLC",
"form_type": "1120S", "years": ["2022","2023","2024"], "status": "irs_queue",
"signed_8821": "attached" } // only when entities[].signed_8821 was sent:
// attached | unreadable_attached | rejected_designee_mismatch
],
"usage": { "used": 47, "remaining": 953, "limit": 1000 }
}
An inline 8821 whose designee CAF isn't a ModernTax designee never fails the request — the entity is created without the form (signed_8821: "rejected_designee_mismatch") and you can re-upload via /api/intake/8821-pdf.
Errors: 401 (auth), 402 (account not enrolled in billing — see Pricing), 409 (duplicate request_token).
Authorization — IRS Form 8821
The IRS requires a signed Form 8821 authorizing ModernTax as designee before transcripts can be pulled. There are two integration models.
A. Upload a pre-signed 8821 — you collect the signature
For partners who obtain the taxpayer's signature through their own workflow (DocuSign, wet-sign, Persona-verified e-sign). The entity advances straight to 8821_signed. This is the model a fully-automated reseller uses. Optional evidence fields record how the signature was collected; they're stored with the entity and returned as signature_evidence on poll responses.
curl -X POST https://portal.moderntax.io/api/intake/8821-pdf \
-H "x-api-key: mt_live_txn_yourco_xxxxxxxxxxxx" \
-F "file=@signed-8821.pdf" \
-F "request_token=your-loan-12345" \
-F "entity_id=uuid" \
-F "persona_inquiry_id=inq_abc123" \
-F "signer_name=Jane Founder" \
-F "signed_at=2026-08-12T18:04:00Z"
file: <signed PDF, application/pdf, max 10 MB> (required)
request_token: your-loan-12345 (required)
entity_id: uuid # or entity_name if the request has one entity
years: "2022,2023,2024" # optional override
form_type: "1120S" # optional override
# optional signature evidence
persona_inquiry_id: inq_abc123
persona_verification_token: <token>
signer_name: Jane Founder
signer_email: jane@acme.com
signed_at: 2026-08-12T18:04:00Z # ISO 8601
signer_ip: 203.0.113.9
signature_vendor: persona
{ "success": true,
"designee_check": "ok", // "ok" | "unreadable" (PDF accepted either way)
"signature_evidence_stored": true, // true when any evidence field was sent
"entity": { "id":"uuid","name":"ACME Holdings LLC","status":"8821_signed",
"signed_8821_url":"https://…1h-expiry…","years":["2022","2023","2024"],"form_type":"1120S" } }
If the uploaded 8821 names a designee CAF that is not a ModernTax designee, the endpoint returns 422 { "code": "designee_caf_mismatch", "designee_cafs": ["…"] } and the PDF is not attached — fix the form and re-upload.
Signed-8821 rules
We never request signatures and never need a wet signature. An e-signed 8821 is usable when it proves who signed and when, so these checks run on every 8821 you send (inline or uploaded). Each rule has a stable id. In the staging sandbox a failed blocking rule returns 422 { "error": "Signed 8821 rejected", "failed_rules": [...] } and nothing is created; an accepted 8821 comes back with signature_check listing every rule. In production the designee check above applies today and the full rule set is rolling out.
| Rule | Blocks when |
|---|---|
| is_form_8821 | The document is not IRS Form 8821 (Tax Information Authorization). |
| taxpayer_tin_matches | The TIN on the form differs from tid on the order. |
| designee_is_moderntax | Line 2 names a designee that is not ModernTax. Use the ModernTax template unchanged. |
| esign_audit_trail | Your signing vendor's completion certificate / audit trail (signer, email, timestamps, IP) is not included as pages of the same PDF. A typed or drawn signature on its own is not enough. |
| signer_named | signer_name is missing or is a business. It must be the person who signed: an officer, member, partner or the individual taxpayer. |
| signer_in_audit_trail | signer_name does not appear on the form or its audit trail. |
| signed_at_valid | signed_at is missing, in the future, or more than 120 days old (the IRS window for receiving an 8821). |
Warnings (accepted and reported back): pdf_text_readable (an image-only scan, so the text checks could not run) and signature_vendor_named. Recognised audit trails: DocuSign Certificate of Completion, Dropbox Sign (HelloSign) audit trail, PandaDoc signing certificate, Adobe Acrobat Sign audit report, and generic e-signature certificates.
B. Let ModernTax collect the signature
Submit entities with signer details (CSV/XLSX file or JSON { entities: [...] }) and ModernTax generates a pre-filled 8821, e-mails the signer for signature, then proceeds automatically.
CSV columns: entity_name, tid, tid_kind, email, signer_first_name, signer_last_name, years, address, city, state, zip, form_type.
{ "request_id":"uuid","entities_created":12,"signature_requests_sent":12,"status":"8821_sent" }
Poll for results
Returns every entity's current status, 1-hour signed transcript URLs, and a compliance read. Without a schema query parameter (and no portal-pinned default) the legacy shape below is returned unchanged.
{
"request_id": "your-loan-12345",
"status": "completed", // collapses to "completed" | "pending"
"request_status": "completed", // raw: submitted | 8821_sent | 8821_signed | irs_queue | processing | completed | failed
"completed_at": "2026-05-09T10:32:11Z",
"entities": [{
"entity_id":"uuid","entity_name":"ACME Holdings LLC","tid":"12-3456789","form_type":"1120S",
"years":["2022","2023","2024"],"status":"completed",
"signed_8821_url":"https://…1h-expiry…","signature_created_at":"2026-05-08T…",
"signature_evidence": { // present when evidence was supplied at upload
"persona_inquiry_id":"inq_abc123","signer_name":"Jane Founder","signer_email":"jane@acme.com",
"signed_at":"2026-08-12T18:04:00Z","signature_vendor":"persona",
"recorded_at":"2026-08-12T18:05:02Z","source":"api_8821_pdf"
}, // signer_ip is stored but never returned
"transcript_urls":["https://…/2022-record-of-account.pdf", "…"],
"transcript_html_urls":["https://…"],
"compliance": {
"severity":"WARNING", // CRITICAL | WARNING | CLEAN (max across forms)
"flags":[{"type":"BALANCE_DUE","severity":"WARNING","message":"Account balance: $4,287.21"}],
"financials":{"grossReceipts":1240000,"totalTax":42000,"accountBalance":4287.21,"accruedInterest":0,"accruedPenalty":0},
"recent_transactions":[{"code":"150","explanation":"Tax return filed","date":"2024-04-12","amount":"42000"}] // ≤10, newest first
},
"tax_compliance": { … }, // filed-up / owes-the-IRS verdict — see Tax compliance object
"qoe_qualification": { // only on accounts with QoE screening; null until a loan is sent or a check is run
"loan_amount":3250000,"loan_purpose":"acquisition",
"verdict":"required", // required | qualifies | needs_info | not_eligible; null until checked
"recommended":true,
"headline":"QoE required: SBA SOP 50 10 8.1 applies to a $3,250,000 acquisition loan.",
"next_steps":[],
"checks":[{"key":"two_years","label":"Two filed years on transcript","status":"pass","detail":"…"}], // status: pass | warn | fail | na
"dscr_proxy":1.62, // latest net income vs. an assumed 10.5% / 10-year payment
"fee_estimate":{"low":12500,"high":18000}, // indicative only; nothing is billed
"checked_at":"2026-11-02T22:10:00Z"
}
}]
}
qoe_qualification appears only in this legacy shape, not under schema=. The check reads the IRS transcripts on file, so the verdict is most useful once the order has completed.
Response schemas
schema is a query parameter on the results poll — it is not a field on the create-request body. You can also pin an org-wide default ("default response schema") in the developer portal; an explicit query parameter overrides the pin. No parameter and no pin returns the legacy shape unchanged. An invalid value returns 400 listing the valid values.
Just tell me if it's clean — filed years, unfiled years, flags, and file URLs.
The lines a credit memo needs — financials, liabilities, repayment posture, headline.
You parse it yourself — artifact list with per-file sha256.
curl "https://portal.moderntax.io/api/intake/transcript?token=your-loan-12345&schema=underwriting" \
-H "x-api-key: mt_live_txn_yourco_xxxxxxxxxxxx"
All three shapes share one envelope; only the per-entity objects differ. PDF and HTML URLs are 1-hour signed. Every entity object, in every shape, also carries a tax_compliance object.
{
"request_id": "uuid",
"reference": "your-loan-12345",
"schema": "minimal", // echoes the shape served
"status": "completed",
"request_status": "completed",
"created_at": "2026-08-10T14:02:00Z",
"completed_at": "2026-08-11T10:32:11Z",
"entities": [ … ] // shape per schema, below
}
schema=minimal — just tell me if it's clean
{ "id":"uuid", "name":"ACME Holdings LLC", "form":"1120S",
"years":["2022","2023","2024"], "status":"completed",
"years_filed":["2022","2023","2024"], "years_unfiled":[],
"flags":[{"type":"BALANCE_DUE","severity":"WARNING","message":"Account balance: $4,287.21"}],
"pdf":["https://…1h-expiry…"], "html":["https://…1h-expiry…"] }
schema=underwriting — the lines a credit memo needs
Everything in minimal, plus:
{ …minimal fields…,
"financials":[{ "year":"2023","form":"1120S","gross_receipts":1240000,"total_income":1262400,
"total_deductions":1108000,"total_tax":42000,"account_balance":4287.21,
"accrued_interest":112.04,"accrued_penalty":0,"account_balance_plus_accruals":4399.25 }],
"tax_liabilities":{ "total_assessed":42000,"total_paid":37712.79,"total_balance":4287.21,"total_accrued":112.04 },
"repayment_plan":{ "has_installment_agreement":false,"has_offer_in_compromise":false,
"has_currently_not_collectible":false,"details":null,
"recommendation":"Balance due with no active agreement — condition the loan on proof of payment or an installment agreement." },
"overall_severity":"WARNING",
"headline":"Filed all 3 requested years; $4,287.21 balance due on 2023." }
schema=raw — you parse it yourself
{ "id":"uuid", "name":"ACME Holdings LLC", "form":"1120S",
"years":["2022","2023","2024"], "status":"completed",
"retrieved_at":"2026-08-11T10:32:11Z",
"artifacts":[
{ "kind":"pdf", "file":"2023-record-of-account.pdf", "url":"https://…1h-expiry…", "sha256":"9f2c…a41b" },
{ "kind":"html", "file":"2023-record-of-account.html","url":"https://…1h-expiry…", "sha256":"3d81…7c02" },
{ "kind":"signed_8821", "file":"signed-8821.pdf", "url":"https://…1h-expiry…", "sha256":"77aa…09c3" }
] }
sha256 is computed at serve time; it may be null for legacy externally-stored artifacts.
Structured JSON
Machine-readable parse of a completed entity — filings, per-year compliance, and an income baseline — for resellers who consume data rather than files. Same x-api-key auth.
Companion endpoint: compares declared values against IRS-of-record values.
{ "entity": {…}, "filings": [{ "year":"2023","form":"1120S","filed":true,… }],
"compliance": {…}, "income_baseline": {…},
"tax_compliance": {…} } // top level — see Tax compliance object
tax_compliance is a top-level key on this response; its shape is documented under Tax compliance object.
Tax compliance object
A small, machine-readable verdict built from the IRS transcripts on file for one entity: is the taxpayer filed up, do they owe the IRS, and as of when. It is the same read as the summary card on the request page and the Tax Liability Summary PDF, so all three agree.
It appears on every entity in GET /api/intake/transcript (the legacy shape and every schema= shape), at the top level of GET /api/v1/transcripts/{entityId}/structured, and in the entities[] array of the complete webhook. It is additive: no existing field was renamed, moved or retyped.
"tax_compliance": {
"filing_status": "current", // current | delinquent | unfiled | unknown
"last_filed_year": 2024,
"balance_due": true, // null = not determinable
"balance_due_amount": 2026.49, // IRS "Account balance plus accruals"; not a payoff amount
"transcript_available": true,
"as_of": "2026-09-15T18:22:01.000Z",
"periods": [
{ "year":"2023", "period":"2023", "form_type":"1120-S", "filed":true, "status":"filed", "balance":0, "ordered":true },
{ "year":"2024", "period":"2024", "form_type":"1120-S", "filed":true, "status":"filed", "balance":1943.16, "ordered":true },
{ "year":"2024", "period":"2024 Q3", "form_type":"941", "filed":true, "status":"filed", "balance":83.33, "ordered":false }
]
}
In this example the ordered 1120-S years are both filed, so filing_status is current even though a balance is owed. The 941 quarter came from a discovery pull outside the order (ordered: false): it does not affect filing_status, but its balance is included in balance_due_amount, so the per-period balances add up to the total.
Fields
| Field | Type | Notes |
|---|---|---|
| filing_status | string | current | delinquent | unfiled | unknown. See the rule below. |
| last_filed_year | number | null | Newest year for which the IRS shows a return posted. null when none is shown. |
| balance_due | boolean | null | true when the IRS shows money owed. null = not determinable: no Account Transcript or Record of Account is on file (a Return Transcript carries no balance). |
| balance_due_amount | number | null | The IRS “Account balance plus accruals”, counted once per form + tax period, in dollars. Re-pulls, duplicate documents and a Return Transcript next to a Record of Account do not double it. It is not a payoff amount. null whenever balance_due is null. |
| transcript_available | boolean | Whether any transcript is on file for the entity. |
| as_of | string | null | ISO 8601 upload time of the newest transcript used. null when no transcript can be dated. |
| periods[] | array | One row per form + tax period the verdict was built from. |
| periods[].year | string | Tax year, e.g. "2024". |
| periods[].period | string | "2024" for annual returns, "2024 Q3" for quarterly returns (941). |
| periods[].form_type | string | Form as the IRS labels it: 1120-S, 1065, 1040, 941, … |
| periods[].filed | boolean | null | true = return on file; false = the IRS has no record of a required return; null = no determination for this period. |
| periods[].status | string | filed (the IRS shows the return) | unfiled (“no record of return filed”) | filed_pending_posting (no record yet, but the preparer supplied an IRS e-file acceptance; counted as filed) | not_required (no filing requirement that year) | not_yet_due (an income-tax year that has not closed) | pending (ordered, no transcript yet). |
| periods[].balance | number | null | IRS balance plus accruals for this period, counted once. null when not determinable. |
| periods[].ordered | boolean | false = the period is not part of your order (for example a payroll balance found on a discovery pull). |
How filing_status is decided
Only the periods in the form family you ordered (1120-S and 1120 count as one family) and the years you ordered are considered, and only periods the IRS actually answered count — that is, periods[].filed is true or false. Pending, not-yet-due and not-required periods are ignored.
current— every answered period is filed, including a preparer’s e-file acceptance that the IRS has not posted yet.delinquent— at least one answered period is filed and at least one required period is not.unfiled— every answered period came back “no record of return filed”.unknown— no period has an answer yet (no transcripts, PDFs only, or nothing in the ordered form and years came back), or every answer is “no record” but the empty result may come from the request itself (the wrong form series or fiscal period). We do not call a taxpayer a non-filer on a pull that may have asked the wrong question.
A balance owed never changes filing_status. It is reported in balance_due and balance_due_amount, so a taxpayer who has filed every year but owes the IRS is current with balance_due: true. Periods from discovery pulls outside the order (ordered: false) never decide the verdict, but any balance they show is counted in balance_due_amount.
To build this object the poll reads the entity’s transcripts on each request, so a poll on a completed order can take a little longer than before.
Enroll in monitoring
{ "request_token":"your-loan-12345", "entity_name":"ACME Holdings LLC",
"frequency":"annual", // weekly | monthly | quarterly | annual | custom
"custom_interval_days":365, // required if frequency=="custom"
"skip_initial_pull":true, "expires_at":"2031-05-09", "next_pull_date":"2027-04-15" }
Returns the created subscription. If skip_initial_pull=false (default) an immediate_pull is queued. An entity with an active or paused subscription returns 409 with the existing one.
Webhooks — push result delivery
Configure your webhook self-serve in the developer portal: set the delivery URL and a signing secret, and send yourself signed test deliveries.
The signing secret is shown once — store it immediately. There is no per-request callback_url field.
Delivery fires when an entity's transcripts are completed. There is no separate event for intermediate steps like 8821 signed or IRS queued — poll for those.
Headers
Content-Type: application/json
User-Agent: ModernTax-Webhook/1.0
X-ModernTax-Signature: <hex HMAC-SHA256 of the raw body, keyed with your webhook secret>
Verifying the signature
Compute the HMAC over the raw request body (before any JSON parsing) and compare constant-time:
const crypto = require('crypto');
function verifyModernTax(rawBody, signatureHeader, secret) {
const expected = crypto.createHmac('sha256', secret)
.update(rawBody) // Buffer or exact raw string
.digest('hex');
const given = Buffer.from(signatureHeader || '', 'utf8');
const want = Buffer.from(expected, 'utf8');
return given.length === want.length && crypto.timingSafeEqual(given, want);
}
Payload
Two contracts are delivered; your account is configured for one.
{ "request_token":"your-loan-12345", "status":"complete", // partial | complete | error
"files":[{ "file_id":"uuid","type":"record_of_account","year":"2023",
"entity_name":"ACME Holdings LLC","html":"<…>","created_at":"…" }] }
On the v2 contract, each file arrives in a partial delivery and the request ends with a lightweight complete signal (empty files). That signal now also carries an entities[] array with each entity’s tax_compliance object:
{ "request_token":"your-loan-12345", "status":"complete", "files":[],
"entities":[{ "entity_id":"uuid", "form_type":"1120S", "years":["2023","2024"],
"status":"completed", "tax_compliance":{ … } }] }
entities is additive and best-effort: if it can’t be built, the complete signal is still sent without it. Make sure your receiver ignores keys it doesn’t recognise — a 4xx response marks the delivery dead with no retry (see Retries).
{ "request_token":"your-loan-12345","status":"complete",
"record_id":"uuid", // deterministic — use for idempotency/dedupe
"record_type":"financial_verification",
// entity_profile | form_discovery | employment_compliance |
// financial_verification | risk_signals | credit_recommendation
"generated_at":"…","entity":{…},"data":{…} }
Retries
On failure ModernTax retries up to 5 attempts with backoff 10s, 30s, 90s, 5m, 15m. A 4xx response (except 413 and 429) marks the delivery dead immediately — no further retries.
Employment & income verification
A separate product for W-2 and 1099 verification. Same x-api-key scheme.
Poll returns parsed employment_data instead of transcripts. Ask for the employment schema when provisioning.
Errors
| Status | Meaning |
|---|---|
| 400 | Validation error (bad TID, non-PDF upload, file > 10 MB, missing required field, invalid schema value — body lists the valid values). |
| 401 | Missing or invalid x-api-key. |
| 402 | Account not enrolled in billing — a payment method or billing setup is required before ordering. |
| 404 | request_token or entity not found for your account. |
| 409 | Duplicate request_token, or an entity already has a monitoring subscription. |
| 422 | designee_caf_mismatch on /api/intake/8821-pdf — the uploaded 8821 names a non-ModernTax designee CAF; body includes designee_cafs. |
| 429 | Account request quota reached (body includes usage). |
Rate limits
A cumulative request quota is enforced per account when configured. Exceeding it returns 429 with { "error": "...", "usage": { "used", "limit" } }. Quotas are set with your plan — contact sales to raise one.
System status
Returns { "status": "ok" } when healthy — safe to poll for monitoring.
Developer portal
portal.moderntax.io/developer is self-serve management for your API account.
- API keys — rotate keys without a support ticket.
- Webhooks — set the delivery URL and signing secret (secret shown once) and fire signed test deliveries at your endpoint.
- Default response schema — pin
minimal,underwriting, orraworg-wide; an explicitschema=query parameter still overrides. - Usage — request counts against your quota.
Pricing & quotas
API access runs on a custom volume plan. Request a quote for the platform subscription, included usage and per-entity pricing. Your quote or signed agreement defines covered services, billing and cancellation terms.
Add-ons such as monitoring and entity pre-validation are scoped with your plan. Pricing is shared after a demo and set in your master services agreement; email sales@moderntax.io to book one.
MCP server (AI agents)
The same API as Model Context Protocol tools, so an AI agent can verify a business, order transcripts and read the results with no custom integration.
- Transport: Streamable HTTP, stateless.
POSTone JSON-RPC message (or a batch of up to 20) and get one JSON reply. No session and no SSE stream (GETreturns 405). Protocol versions2025-06-18,2025-03-26,2024-11-05. - Auth: your API key, as
Authorization: Bearer <key>orx-api-key. Each key sees only its own organisation's orders. - Tools:
verify_entity(what is on file for a TIN),order_transcripts(a billable order, with the same rules as Submit a request),get_order_status,get_transcript_data(the structured JSON) andcross_reference(borrower figures vs. the IRS-filed return). Replies returntin_last4, never a full TIN. - Sandbox keys: a read-only key from portal.moderntax.io/sandbox connects in production with the read-only tools (no
order_transcripts). A staging key athttps://staging.portal.moderntax.io/api/mcpruns the full flow, including ordering against the simulated IRS and the test TINs. - Live keys: MCP access is enabled per account. Ask matt@moderntax.io.
curl https://portal.moderntax.io/api/mcp \
-H "Authorization: Bearer $MODERNTAX_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
OpenAPI spec & llms.txt
A machine-readable OpenAPI 3.1 description of this API is at portal.moderntax.io/openapi.json. A plain-text summary for language models is at moderntax.io/llms.txt. Security contact: /.well-known/security.txt.
Security & compliance
- SOC 2 readiness in progress; security documentation available under NDA.
- Encrypted in transit (TLS 1.2+) and at rest (AES-256; encrypted SSN and credential columns).
- API keys SHA-256 hashed, constant-time verified.
- Per-tenant storage isolation via Postgres Row-Level Security on the storage bucket.
- Every partner request and result fetch is audit-logged with client identity, timestamp, and token.
- Signed transcript and 8821 URLs expire in 1 hour.
For security documentation or vendor questionnaires: security@moderntax.io. Full page: portal.moderntax.io/security.
Versioning
This document describes the v1 surface — the /api/intake/* endpoints and /api/v1/transcripts/*. Breaking changes land under a new version path; existing endpoints remain stable.
matt@moderntax.io · ModernTax, Inc. — this reference is kept in sync with the deployed API.