API reference

Check e-file readiness (Form 8879)

Computes Form 8879 (Rev. January 2021) Part I for one original 2023-2025 return and lists what blocks signing and transmitting it. Also the MCP tool tax_compute_efile_readiness, which refuses PINs.

POSThttps://tax-mcp.com/api/mcp/tax-compute/efile-readiness

Form 8879 (Rev. January 2021) Part I amounts and an e-file readiness check for one original federal return, 2023-2025.

The return is the federal compute of `profile`. PINs and prior-year values are checked for presence and format only and never returned. One billable unit.

Headers

HeaderRequiredDescription
AuthorizationYesBearer <API key>
Content-TypeYesapplication/json
Idempotency-KeyNo (recommended)
Optional. A unique key per logical request (one key per operation). Retrying with the SAME key + SAME request body replays the byte-identical first response (with header `Idempotent-Replayed: true`)…

Optional. A unique key per logical request (one key per operation). Retrying with the SAME key + SAME request body replays the byte-identical first response (with header `Idempotent-Replayed: true`) and bills exactly ONCE. The SAME key with a DIFFERENT body → 409 `idempotency_key_reused`. A concurrent in-flight duplicate → 409 `idempotency_key_in_progress` (retry). Keys are scoped per account and replay for 24h. Errors (4xx/5xx) are NOT cached — a retry after an error is a fresh request.

Request body

FieldDescription
profileFederalProfilerequiredThe return, exactly as accepted by POST /tax-compute/federal. Lines 1 and 2 are its AGI and total tax.
paymentsobjectrequired
Form 1040 lines the federal compute doesn't take, whole dollars:

Form 1040 lines the federal compute doesn't take, whole dollars: form1099Withholding (25b), estimatedTaxPayments (26), extensionPayment (Schedule 3 line 10), appliedToNextYearEstimatedTax (36) and estimatedTaxPenalty (38; 0 if you leave it blank for the IRS to bill).

paymentsAffirmedboolean
Must be true for lines 4 and 5 (otherwise the payments_not_affirmed blocker), attesting:

Must be true for lines 4 and 5 (otherwise the payments_not_affirmed blocker), attesting: Form 1040 line 25c is only the Additional Medicare Tax withheld that the engine figures from the W-2s; form1099Withholding is the line 25b amount: federal income tax withheld on Forms 1099; estimatedTaxPayments is the line 26 amount: the estimated tax paid for the year, including any prior-year overpayment applied to it; line 27 (2025: line 27a) has no earned income credit; line 29 has no American opportunity credit; for 2025, line 30 has no refundable adoption credit; Schedule 3 has no payment or refundable credit other than the net premium tax credit the engine computes and extensionPayment, the line 10 amount paid with a request for an extension to file.

signatureobjectrequired
method (practitioner_pin or self_select_pin) and, for each signer, who enters the PIN (taxpayerPinEntry, spousePinEntry on a joint return).

method (practitioner_pin or self_select_pin) and, for each signer, who enters the PIN (taxpayerPinEntry, spousePinEntry on a joint return). Send a PIN when the ERO enters it; eroEfinPin with practitioner_pin or whenever the ERO enters a PIN; prior-year AGI or PIN and dateOfBirthProvided with self_select_pin. The date of birth itself isn't accepted.

signedAmounts{ line1 … line5 }A Form 8879 already signed for this return. A line that moved by more than $50 (AGI) or $14 (the others) blocks with form_8879_amounts_changed.

Every field of profile is in the federal reference. PINs, the EFIN/PIN and prior-year values are checked for presence and format only. No response carries them, and with an Idempotency-Key the stored request hash covers only whether each is present and well formed, never the values.

Example

Request
curl https://tax-mcp.com/api/mcp/tax-compute/efile-readiness \
  -H "Authorization: Bearer $TAX_MCP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "profile": {
      "year": 2024,
      "filingStatus": "single",
      "canBeClaimedAsDependent": false,
      "noForeignOrTerritoryExclusionAffirmed": true,
      "wages": 60000,
      "medicareWages": 60000,
      "federalWithholding": 7000
    },
    "payments": {
      "form1099Withholding": 300,
      "estimatedTaxPayments": 500,
      "extensionPayment": 0,
      "appliedToNextYearEstimatedTax": 0,
      "estimatedTaxPenalty": 0
    },
    "paymentsAffirmed": true,
    "signature": {
      "method": "practitioner_pin",
      "taxpayerPinEntry": "ero",
      "taxpayerPin": "12345",
      "eroEfinPin": "12345654321"
    }
  }'
Response 200 · COMPUTED
{
  "computed": true,
  "year": 2024,
  "filingStatus": "single",
  "ready": true,
  "form8879Required": true,
  "blockers": [],
  "reviewItems": [
    "The signed Form 8879 must be received before the return is transmitted",
    "An Identity Protection PIN issued to either filer must be entered on the return"
  ],
  "form8879": {
    "revision": "Rev. January 2021",
    "taxYear": 2024,
    "lines": [
      {
        "line": "1",
        "label": "Adjusted gross income",
        "amount": 60000,
        "form1040Line": "11"
      },
      { "line": "2", "label": "Total tax", "amount": 5219, "form1040Line": "24" },
      {
        "line": "3",
        "label": "Federal income tax withheld from Form(s) W-2 and Form(s) 1099",
        "amount": 7300,
        "form1040Line": "25a + 25b"
      },
      {
        "line": "4",
        "label": "Amount you want refunded to you",
        "amount": 2581,
        "form1040Line": "35a"
      },
      { "line": "5", "label": "Amount you owe", "amount": 0, "form1040Line": "37" }
    ]
  },
  "form1040Payments": {
    "line25a": 7000,
    "line25b": 300,
    "line25c": 0,
    "line26": 500,
    "line32": 0,
    "line33": 7800,
    "line38": 0,
    "line34": 2581,
    "line35a": 2581,
    "line36": 0,
    "line37": 0
  },
  "federalReturn": {
    "computed": true,
    "year": 2024,
    "filingStatus": "single",
    "taxableIncome": 45400,
    "incomeTax": 5219,
    "totalTax": 5219,
    "lines": [
      { "lineId": "1040:15", "label": "Taxable income", "amount": 45400 },
      {
        "lineId": "1040:16",
        "label": "Income tax",
        "amount": 5219,
        "derivation": "<3 derivation steps — see full response>"
      },
      { "lineId": "1040:24", "label": "Total tax", "amount": 5219 }
    ],
    "flags": [],
    "owedOrRefund": -1781
  },
  "billed": true,
  "retry_safe": true,
  "next_action": "none",
  "provenance": {
    "engine": "deterministic",
    "jurisdiction": "efile-readiness",
    "tax_year": 2024
  },
  "legal_notice": {
    "ref": "https://tax-mcp.com/terms#compute-notice",
    "version": "v1",
    "text": "<computation-support notice — see full response>"
  }
}
Full response, including line derivations
{
  "computed": true,
  "year": 2024,
  "filingStatus": "single",
  "ready": true,
  "form8879Required": true,
  "blockers": [],
  "reviewItems": [
    "The signed Form 8879 must be received before the return is transmitted",
    "An Identity Protection PIN issued to either filer must be entered on the return"
  ],
  "form8879": {
    "revision": "Rev. January 2021",
    "taxYear": 2024,
    "lines": [
      {
        "line": "1",
        "label": "Adjusted gross income",
        "amount": 60000,
        "form1040Line": "11"
      },
      { "line": "2", "label": "Total tax", "amount": 5219, "form1040Line": "24" },
      {
        "line": "3",
        "label": "Federal income tax withheld from Form(s) W-2 and Form(s) 1099",
        "amount": 7300,
        "form1040Line": "25a + 25b"
      },
      {
        "line": "4",
        "label": "Amount you want refunded to you",
        "amount": 2581,
        "form1040Line": "35a"
      },
      { "line": "5", "label": "Amount you owe", "amount": 0, "form1040Line": "37" }
    ]
  },
  "form1040Payments": {
    "line25a": 7000,
    "line25b": 300,
    "line25c": 0,
    "line26": 500,
    "line32": 0,
    "line33": 7800,
    "line38": 0,
    "line34": 2581,
    "line35a": 2581,
    "line36": 0,
    "line37": 0
  },
  "federalReturn": {
    "computed": true,
    "year": 2024,
    "filingStatus": "single",
    "taxableIncome": 45400,
    "incomeTax": 5219,
    "totalTax": 5219,
    "lines": [
      {
        "lineId": "1040:15",
        "label": "Taxable income",
        "amount": 45400,
        "derivation": []
      },
      {
        "lineId": "1040:16",
        "label": "Income tax",
        "amount": 5219,
        "derivation": [
          {
            "lineId": "1040:16",
            "label": "Tax Table method (IRS-mandated below $100,000 taxable income)",
            "inputs": [
              { "name": "taxableIncome", "value": 45400 }
            ],
            "rule": {
              "description": "Form 1040 instructions require the published Tax Table — a lookup on the midpoint of a narrow taxable-income band — for taxable income under $100,000; the exact bracket formula (Tax Computation Worksheet) applies only at $100,000 or more.",
              "authority": "Form 1040 instructions — Tax Table"
            },
            "computation": "taxable income $45,400 → Tax Table band midpoint $45,425",
            "result": 0
          },
          {
            "lineId": "1040:16",
            "label": "Ordinary income tax — 10% bracket",
            "inputs": [
              { "name": "taxableIncomeInBracket", "value": 11600 }
            ],
            "rule": {
              "description": "marginal rate × taxable income falling within this bracket",
              "authority": "IRC §1(j)",
              "constantRef": {
                "table": "BRACKETS_BY_YEAR",
                "key": "2024/single",
                "value": "10% (up to $11,600)",
                "revProc": "Rev. Proc. 2023-34"
              }
            },
            "computation": "0.1 × $11,600 = $1,160",
            "result": 1160
          },
          {
            "lineId": "1040:16",
            "label": "Ordinary income tax — 12% bracket",
            "inputs": [
              { "name": "taxableIncomeInBracket", "value": 33825 }
            ],
            "rule": {
              "description": "marginal rate × taxable income falling within this bracket",
              "authority": "IRC §1(j)",
              "constantRef": {
                "table": "BRACKETS_BY_YEAR",
                "key": "2024/single",
                "value": "12% (up to $47,150)",
                "revProc": "Rev. Proc. 2023-34"
              }
            },
            "computation": "0.12 × $33,825 = $4,059",
            "result": 4059
          }
        ]
      },
      {
        "lineId": "1040:24",
        "label": "Total tax",
        "amount": 5219,
        "derivation": []
      }
    ],
    "flags": [],
    "owedOrRefund": -1781
  },
  "billed": true,
  "retry_safe": true,
  "next_action": "none",
  "provenance": {
    "engine": "deterministic",
    "jurisdiction": "efile-readiness",
    "tax_year": 2024
  },
  "legal_notice": {
    "ref": "https://tax-mcp.com/terms#compute-notice",
    "version": "v1",
    "text": "Computation support only. Not tax, legal, accounting, or financial advice. Customer is responsible for review, filing positions, and use only within the documented supported envelope."
  }
}

Responses

StatusMeaning
200
{ computed, year, filingStatus, ready, form8879Required, blockers[{code, detail}], reviewItems, form8879{revision, taxYear, lines[{line, label, amount, form1040Line}]}, form1040Payments, changedLines,…

{ computed, year, filingStatus, ready, form8879Required, blockers[{code, detail}], reviewItems, form8879{revision, taxYear, lines[{line, label, amount, form1040Line}]}, form1040Payments, changedLines, federalReturn } or a decline with code return_declined | engine_line_mismatch. ready is true when no blocker is found; it doesn't check SSNs, bank data, an IP PIN, MeF business rules or receipt of the signed 8879. Blocker codes: return_declined | payments_not_affirmed | applied_exceeds_overpayment | taxpayer_pin_missing | taxpayer_pin_malformed | spouse_pin_missing | spouse_pin_malformed | ero_efin_pin_missing | ero_efin_pin_malformed | taxpayer_prior_year_missing | taxpayer_prior_year_pin_malformed | taxpayer_date_of_birth_missing | spouse_prior_year_missing | spouse_prior_year_pin_malformed | spouse_date_of_birth_missing | form_8879_amounts_changed

400Invalid body / JSON / failed validation
401Missing / unknown / revoked key (no enumeration)
403Account suspended — contact billing (distinct from 401: the key is valid)
409Idempotency-Key reused with a different body (`idempotency_key_reused`), or a concurrent in-flight duplicate (`idempotency_key_in_progress`). Retry; NOT billed.
429
Monthly quota exhausted (account-wide;

Monthly quota exhausted (account-wide; `quota_exceeded`, next_action `upgrade_plan_or_wait_next_period`, retry_safe false) or per-minute rate exceeded (`rate_limit_exceeded`, next_action `retry_after_backoff`, retry_safe true). Not billed.

500Sanitized server error computing the return
503Metering outage — fail-closed (the call is NOT silently served free)

ready is true when blockers is empty. It covers only the checks listed here, not SSNs, bank data, an IP PIN, MeF business rules or receipt of the signed Form 8879. form8879 carries lines 1-5 with the Form 1040 line each comes from, and form1040Payments carries lines 25a-38. form8879Required is false only when every signer enters their own PIN under the Self-Select PIN method. reviewItemslists what a preparer confirms before signing: the federal compute's VERIFY flags, the IP PIN, and the prior-year AGI source. A federal decline comes back as return_declined with the federal code in returnDecline.

Roadmap status for this page

Generated from the roadmap (updated 2026-10-30). Shipped & certified means live and independently checked against primary tax sources; certifying means live, with those checks still in progress.

Lifecycle — projection, estimates, amendments
CapabilityStatus
Form 8879 amounts and an e-file readiness check, 2023-2025Form 8879 Part I amounts for an original 2023-2025 return, and what blocks signing it: PIN and prior-year AGI format, payments, moved amounts.◐ certifying