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.
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
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer <API key> |
| Content-Type | Yes | application/json |
| Idempotency-Key | No (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
| Field | Description |
|---|---|
| profileFederalProfilerequired | The 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
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"
}
}'{
"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
| Status | Meaning |
|---|---|
| 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 |
| 400 | Invalid body / JSON / failed validation |
| 401 | Missing / unknown / revoked key (no enumeration) |
| 403 | Account suspended — contact billing (distinct from 401: the key is valid) |
| 409 | Idempotency-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. |
| 500 | Sanitized server error computing the return |
| 503 | Metering 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.
| Capability | Status |
|---|---|
| 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. |