ModernTaxAPI Reference
Partner API · v1

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.

x-api-key auth · no OAuth dance Self-serve sandbox, 250 requests SOC 2 readiness in progress

Overview

A typical automated integration — how a reseller such as a lending platform runs it end to end.

1

Submit

Send one or more entities to POST /api/intake/transcript.

2

Authorize

Each entity needs a signed IRS Form 8821 — upload a pre-signed PDF you collected yourself, or let ModernTax collect the signature.

3

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.

Headers
x-api-key: mt_live_txn_yourco_xxxxxxxxxxxx
Content-Type: application/json    # or multipart/form-data where noted
How keys are handled

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

Base
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.

GET/api/sandbox/sample-8821

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
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"
200 OK
{ "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" } }
styleResult
valid (default)accepted
no_audit_trailrejected: esign_audit_trail
wrong_designeerejected: designee_is_moderntax
signer_is_businessrejected: signer_named
wrong_tinrejected: taxpayer_tin_matches
stalerejected: 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 4Outcome
0001Clean: every year filed, $0 balance
0002Tax lien: balance due and a federal tax lien filed (TC 582)
0003Balance due with penalties and interest, no lien
0004Latest year has no return filed
0005Wrong form: no record for the form ordered
0006failed, irs_tin_name_mismatch, not billed
0007failed, irs_signer_not_authorized, not billed
0008failed, irs_8821_rejected, not billed
any otherClean

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:

POST/api/sandbox/advance
cURL
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"}'
Staging limits

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

POST/api/intake/transcript

Creates a request with one or more entities and queues them for IRS retrieval.

Authorization is separate unless you attach it inline

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
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.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"
      }
    }
  ]
}
FieldReqNotes
request_tokenyesYour unique id for the request. Reusing one returns 409.
loan_numbernoFalls back to request_token. Used on invoices.
entities[].entity_nameyesLegal name on file with the IRS.
entities[].tid / tid_kindyesEIN (XX-XXXXXXX) or SSN (XXX-XX-XXXX); "EIN"/"SSN".
entities[].yearsyes4-digit years, 1990–2028.
entities[].form_typeno1040, 1065, 1120, 1120S, 941. Inferred from tid_kind if omitted.
entities[].fiscal_year_end_monthyes*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_amountnoProposed 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_purposenoacquisition, 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_8821noInline 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

201 Created
{
  "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 }
}
A bad designee never fails your request

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

POST/api/intake/8821-pdf

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 · multipart
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"
Fields · multipart/form-data
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
200 OK
{ "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" } }
422 · designee_caf_mismatch

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.

RuleBlocks when
is_form_8821The document is not IRS Form 8821 (Tax Information Authorization).
taxpayer_tin_matchesThe TIN on the form differs from tid on the order.
designee_is_moderntaxLine 2 names a designee that is not ModernTax. Use the ModernTax template unchanged.
esign_audit_trailYour 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_namedsigner_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_trailsigner_name does not appear on the form or its audit trail.
signed_at_validsigned_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

POST/api/intake/8821

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.

Response
{ "request_id":"uuid","entities_created":12,"signature_requests_sent":12,"status":"8821_sent" }

Poll for results

GET/api/intake/transcript?token=<request_token>

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.

200 OK · legacy shape
{
  "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

GET/api/intake/transcript?token=<request_token>&schema=minimal|underwriting|raw

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.

schema=minimal

Just tell me if it's clean — filed years, unfiled years, flags, and file URLs.

schema=underwriting

The lines a credit memo needs — financials, liabilities, repayment posture, headline.

schema=raw

You parse it yourself — artifact list with per-file sha256.

cURL
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.

Shared envelope
{
  "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

Entity object
{ "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:

Entity object
{ …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

Entity object
{ "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

GET/api/v1/transcripts/{entityId}/structured

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.

GET/api/v1/transcripts/{entityId}/cross-reference

Companion endpoint: compares declared values against IRS-of-record values.

200 OK
{ "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.

Example · synthetic values
"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

FieldTypeNotes
filing_statusstringcurrent | delinquent | unfiled | unknown. See the rule below.
last_filed_yearnumber | nullNewest year for which the IRS shows a return posted. null when none is shown.
balance_dueboolean | nulltrue 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_amountnumber | nullThe 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_availablebooleanWhether any transcript is on file for the entity.
as_ofstring | nullISO 8601 upload time of the newest transcript used. null when no transcript can be dated.
periods[]arrayOne row per form + tax period the verdict was built from.
periods[].yearstringTax year, e.g. "2024".
periods[].periodstring"2024" for annual returns, "2024 Q3" for quarterly returns (941).
periods[].form_typestringForm as the IRS labels it: 1120-S, 1065, 1040, 941, …
periods[].filedboolean | nulltrue = return on file; false = the IRS has no record of a required return; null = no determination for this period.
periods[].statusstringfiled (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[].balancenumber | nullIRS balance plus accruals for this period, counted once. null when not determinable.
periods[].orderedbooleanfalse = 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.

Poll latency

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

POST/api/intake/monitoring
Request
{ "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.

Two things to know

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

Request headers we send
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:

Node
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.

v2 · incremental file delivery
{ "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:

v2 · complete signal
{ "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).

v3 · structured records
{ "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.

POST/api/webhook/employment-intakeLive
GET/api/webhook/employment-result?token=<request_token>

Poll returns parsed employment_data instead of transcripts. Ask for the employment schema when provisioning.

Errors

StatusMeaning
400Validation error (bad TID, non-PDF upload, file > 10 MB, missing required field, invalid schema value — body lists the valid values).
401Missing or invalid x-api-key.
402Account not enrolled in billing — a payment method or billing setup is required before ordering.
404request_token or entity not found for your account.
409Duplicate request_token, or an entity already has a monitoring subscription.
422designee_caf_mismatch on /api/intake/8821-pdf — the uploaded 8821 names a non-ModernTax designee CAF; body includes designee_cafs.
429Account 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

GET/api/public/statusNo auth

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, or raw org-wide; an explicit schema= 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.

POSThttps://portal.moderntax.io/api/mcp
  • Transport: Streamable HTTP, stateless. POST one JSON-RPC message (or a batch of up to 20) and get one JSON reply. No session and no SSE stream (GET returns 405). Protocol versions 2025-06-18, 2025-03-26, 2024-11-05.
  • Auth: your API key, as Authorization: Bearer <key> or x-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) and cross_reference (borrower figures vs. the IRS-filed return). Replies return tin_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 at https://staging.portal.moderntax.io/api/mcp runs 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
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.

Questions or a key

matt@moderntax.io · ModernTax, Inc. — this reference is kept in sync with the deployed API.