Guides by outcome

Check a filed California return

Reconcile recomputes a California return from the facts you assert and compares it line by line with the figures that were filed. It changes nothing and never decides who is right; it shows a person where to look.

What you send

  • sourceProfile: the facts you assert, in the same shape as a California state request.
  • filed: the filed return's figures. Any of stateAGI, stateTaxableIncome, totalTax, totalPayments, balanceDue, overpayment.
  • Optionally, sourceDocuments (up to 50) for document-level triage.

Filed figures are never inputs

The filed values are only compared against. They never feed the computation, so a filed figure cannot make the engine agree with it.

Run a reconcile

The filed California AGI is higher than the wages provided:
Request
curl https://tax-mcp.com/api/mcp/tax-compute/reconcile \
  -H "Authorization: Bearer $TAX_MCP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "sourceProfile": {
      "state": "ca",
      "year": 2025,
      "filingStatus": "single",
      "canBeClaimedAsDependent": false,
      "noForeignOrTerritoryExclusionAffirmed": true,
      "wages": 80000,
      "medicareWages": 80000,
      "caWithholding": 5000
    },
    "filed": { "stateAGI": 95000 }
  }'
Response 200 · NEEDS_REVIEW
{
  "computed": {
    "computed": true,
    "state": "ca",
    "year": 2025,
    "filingStatus": "single",
    "stateAGI": 80000,
    "stateDeductions": 5706,
    "stateTaxableIncome": 74294,
    "incomeTaxBeforeCredits": 3349,
    "exemptionCredits": 153,
    "incomeTax": 3196,
    "additionalTaxes": [],
    "totalTax": 3196,
    "lines": [
      { "lineId": "540:13", "label": "Federal AGI", "amount": 80000, "agiRole": "agi_base" },
      {
        "lineId": "540:17",
        "label": "CA adjusted gross income",
        "amount": 80000,
        "agiRole": "agi_total"
      },
      {
        "lineId": "540:18",
        "label": "CA standard deduction",
        "amount": 5706,
        "agiRole": "below_agi",
        "cite": "<primary-source cite — see full response>"
      },
      {
        "lineId": "540:19",
        "label": "CA taxable income",
        "amount": 74294,
        "agiRole": "below_agi"
      },
      {
        "lineId": "540:31",
        "label": "CA tax (2025 California Tax Table)",
        "amount": 3349,
        "agiRole": "below_agi",
        "cite": "<primary-source cite — see full response>"
      },
      {
        "lineId": "540:32",
        "label": "CA exemption credits",
        "amount": 153,
        "agiRole": "below_agi",
        "cite": "<primary-source cite — see full response>"
      },
      {
        "lineId": "540:33",
        "label": "CA tax after exemption credits",
        "amount": 3196,
        "agiRole": "below_agi"
      },
      {
        "lineId": "540:64",
        "label": "Total CA tax",
        "amount": 3196,
        "agiRole": "below_agi"
      }
    ],
    "flags": [
      "CA-AGI-assumed-equal-to-federal-AGI (wages-only; no Schedule CA 540 adjustments). A filer with CA-specific adjustments (HSA add-back, US-Treasury/out-of-state-muni interest, SS exclusion) needs Schedule CA 540.",
      "CA-AMT-not-computed (Schedule P, R&TC §17062). A full-year resident with no AMT preference items owes regular CA tax; a filer with preference items (ISO, accelerated depreciation, etc.) must complete Schedule P.",
      "CA-exemption-credits-computed-with personal/blind/senior=1 ($153 each), dependents=0 ($475 each); blind/senior/dependents default to 0 when not supplied — supply them if applicable.",
      "CA payments = withholding $5,000 + estimated $0 + extension $0 + prior-year-overpayment-applied $0 = $5,000. These coexist, but must NOT double-count — caEstimatedPayments must NOT also include the prior-year overpayment (that double-counts and over-states the refund)."
    ],
    "totalPayments": 5000,
    "balanceDue": 0,
    "overpayment": 1804
  },
  "filed": { "stateAGI": 95000 },
  "diff": [
    {
      "line": "CA AGI (540:17)",
      "engine": 80000,
      "filed": 95000,
      "delta": 15000,
      "cls": "DIFFERS",
      "note": "source set appears INCOMPLETE vs the filed oracle — this line's difference is expected when the provided documents are a subset (not a confirmed engine-vs-preparer disagreement; see the top-level needs_review status)"
    },
    {
      "line": "CA taxable income (540:19)",
      "engine": 74294,
      "filed": null,
      "delta": null,
      "cls": "NO-FILED",
      "note": "filed line not parsed — diff declined"
    },
    {
      "line": "Total CA tax (540:64)",
      "engine": 3196,
      "filed": null,
      "delta": null,
      "cls": "NO-FILED",
      "note": "filed line not parsed — diff declined"
    },
    {
      "line": "Total payments (540:78)",
      "engine": 5000,
      "filed": null,
      "delta": null,
      "cls": "NO-FILED",
      "note": "filed line not parsed — diff declined"
    },
    {
      "line": "Balance due (540:111)",
      "engine": 0,
      "filed": null,
      "delta": null,
      "cls": "NO-FILED",
      "note": "filed line not parsed — diff declined"
    },
    {
      "line": "Overpayment (540:115)",
      "engine": 1804,
      "filed": null,
      "delta": null,
      "cls": "NO-FILED",
      "note": "filed line not parsed — diff declined"
    }
  ],
  "summary": { "MATCH": 0, "ENGINE-DECLINED": 0, "DIFFERS": 1, "NO-FILED": 5 },
  "status": "needs_review",
  "docTriage": [],
  "flags": [
    "Computed from the PROVIDED SOURCE DOCUMENTS only — this is a completeness check, NOT the filer's final CA tax. Divergence vs the filed return most likely means the source set is INCOMPLETE (income on the filed return not represented in the provided documents). A human must review before relying on any number."
  ],
  "billed": true,
  "retry_safe": true,
  "next_action": "review_inputs",
  "provenance": { "engine": "deterministic", "jurisdiction": "ca_reconcile" },
  "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": {
    "computed": true,
    "state": "ca",
    "year": 2025,
    "filingStatus": "single",
    "stateAGI": 80000,
    "stateDeductions": 5706,
    "stateTaxableIncome": 74294,
    "incomeTaxBeforeCredits": 3349,
    "exemptionCredits": 153,
    "incomeTax": 3196,
    "additionalTaxes": [],
    "totalTax": 3196,
    "lines": [
      { "lineId": "540:13", "label": "Federal AGI", "amount": 80000, "agiRole": "agi_base" },
      {
        "lineId": "540:17",
        "label": "CA adjusted gross income",
        "amount": 80000,
        "agiRole": "agi_total"
      },
      {
        "lineId": "540:18",
        "label": "CA standard deduction",
        "amount": 5706,
        "agiRole": "below_agi",
        "cite": {
          "jurisdiction": "ca",
          "cellKey": "std_deduction.2025.single",
          "authority": "CA FTB 2025 Standard Deduction — R&TC §17073.5 (CPI-indexed)"
        }
      },
      {
        "lineId": "540:19",
        "label": "CA taxable income",
        "amount": 74294,
        "agiRole": "below_agi"
      },
      {
        "lineId": "540:31",
        "label": "CA tax (2025 California Tax Table)",
        "amount": 3349,
        "agiRole": "below_agi",
        "cite": {
          "jurisdiction": "ca",
          "cellKey": "brackets.2025.single",
          "authority": "CA FTB 2025 Form 540 booklet 2025 California Tax Table (rate schedule at band midpoint; required when taxable income ≤ $100,000)"
        }
      },
      {
        "lineId": "540:32",
        "label": "CA exemption credits",
        "amount": 153,
        "agiRole": "below_agi",
        "cite": {
          "jurisdiction": "ca",
          "cellKey": "exemption_credit.2025.personal",
          "authority": "CA FTB 2025 Form 540 lines 7–10 Exemption Credits — R&TC §17054 ($153 personal/blind/senior, $475 dependent)"
        }
      },
      {
        "lineId": "540:33",
        "label": "CA tax after exemption credits",
        "amount": 3196,
        "agiRole": "below_agi"
      },
      {
        "lineId": "540:64",
        "label": "Total CA tax",
        "amount": 3196,
        "agiRole": "below_agi"
      }
    ],
    "flags": [
      "CA-AGI-assumed-equal-to-federal-AGI (wages-only; no Schedule CA 540 adjustments). A filer with CA-specific adjustments (HSA add-back, US-Treasury/out-of-state-muni interest, SS exclusion) needs Schedule CA 540.",
      "CA-AMT-not-computed (Schedule P, R&TC §17062). A full-year resident with no AMT preference items owes regular CA tax; a filer with preference items (ISO, accelerated depreciation, etc.) must complete Schedule P.",
      "CA-exemption-credits-computed-with personal/blind/senior=1 ($153 each), dependents=0 ($475 each); blind/senior/dependents default to 0 when not supplied — supply them if applicable.",
      "CA payments = withholding $5,000 + estimated $0 + extension $0 + prior-year-overpayment-applied $0 = $5,000. These coexist, but must NOT double-count — caEstimatedPayments must NOT also include the prior-year overpayment (that double-counts and over-states the refund)."
    ],
    "totalPayments": 5000,
    "balanceDue": 0,
    "overpayment": 1804
  },
  "filed": { "stateAGI": 95000 },
  "diff": [
    {
      "line": "CA AGI (540:17)",
      "engine": 80000,
      "filed": 95000,
      "delta": 15000,
      "cls": "DIFFERS",
      "note": "source set appears INCOMPLETE vs the filed oracle — this line's difference is expected when the provided documents are a subset (not a confirmed engine-vs-preparer disagreement; see the top-level needs_review status)"
    },
    {
      "line": "CA taxable income (540:19)",
      "engine": 74294,
      "filed": null,
      "delta": null,
      "cls": "NO-FILED",
      "note": "filed line not parsed — diff declined"
    },
    {
      "line": "Total CA tax (540:64)",
      "engine": 3196,
      "filed": null,
      "delta": null,
      "cls": "NO-FILED",
      "note": "filed line not parsed — diff declined"
    },
    {
      "line": "Total payments (540:78)",
      "engine": 5000,
      "filed": null,
      "delta": null,
      "cls": "NO-FILED",
      "note": "filed line not parsed — diff declined"
    },
    {
      "line": "Balance due (540:111)",
      "engine": 0,
      "filed": null,
      "delta": null,
      "cls": "NO-FILED",
      "note": "filed line not parsed — diff declined"
    },
    {
      "line": "Overpayment (540:115)",
      "engine": 1804,
      "filed": null,
      "delta": null,
      "cls": "NO-FILED",
      "note": "filed line not parsed — diff declined"
    }
  ],
  "summary": { "MATCH": 0, "ENGINE-DECLINED": 0, "DIFFERS": 1, "NO-FILED": 5 },
  "status": "needs_review",
  "docTriage": [],
  "flags": [
    "Computed from the PROVIDED SOURCE DOCUMENTS only — this is a completeness check, NOT the filer's final CA tax. Divergence vs the filed return most likely means the source set is INCOMPLETE (income on the filed return not represented in the provided documents). A human must review before relying on any number."
  ],
  "billed": true,
  "retry_safe": true,
  "next_action": "review_inputs",
  "provenance": { "engine": "deterministic", "jurisdiction": "ca_reconcile" },
  "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."
  }
}

Read the result

  • status is one of match, mismatch, unsupported, needs_review. Only match has next_action: "none"; every other status goes to a person.
  • Each diff row has the engine value, the filed value, the difference, and a class: MATCH (within $2), DIFFERS, ENGINE-DECLINED (the engine could not compute that line; it is never filled in from the filed value), or NO-FILED (no filed value to compare).
  • A DIFFERS row usually means the source facts are incomplete, for example income on the filed return that is not in what you sent. The engine flags it; a person decides.

See also: /tax-compute/reconcile and Show declines in your product.

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.

State, city, residency, allocation
CapabilityStatus
Non-mutating CA reconcile vs a filed returnReconciles the engine's CA result against a filed CA 540 without modifying the filed return.✅ shipped & certified
Product-builder API, contract & trust surfaces
CapabilityStatus
Reconcile review states (match / mismatch / unsupported / needs_review)Reconcile results report one of four review states: match, mismatch, unsupported, or needs_review.✅ shipped & certified