API reference

Reconcile a California return

Recomputes a California return from the facts you assert and diffs it against the filed figures. Non-mutating: it never changes or files anything.

POSThttps://tax-mcp.com/api/mcp/tax-compute/reconcile

Independently compute a CA 540 from source docs and reconcile vs a filed return.

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
sourceProfileobjectrequiredThe facts you assert, in the California request shape (see the state reference). The engine computes from these alone.
sourceDocumentsarray of objectOptional, up to 50 source documents for triage. When they carry income facts, do not also set non-wage income or stateIncomeConformsToFederal on sourceProfile; that ambiguity is a 400.
filedobjectrequiredThe filed return's figures, compared against and never used as inputs. Any of the fields below; each is optional.

filed

FieldDescription
stateAGInumber | nullFiled amount for this Form 540 line, in whole dollars.
stateTaxableIncomenumber | nullFiled amount for this Form 540 line, in whole dollars.
totalTaxnumber | nullFiled amount for this Form 540 line, in whole dollars.
totalPaymentsnumber | nullFiled amount for this Form 540 line, in whole dollars.
balanceDuenumber | nullFiled amount for this Form 540 line, in whole dollars.
overpaymentnumber | nullFiled amount for this Form 540 line, in whole dollars.

Example

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."
  }
}

Responses

StatusMeaning
200
Reconciliation result (non-mutating;

Reconciliation result (non-mutating; decline-aware). `status`: match | mismatch | unsupported | needs_review. `diff` is a per-line DiffRow[]: { line (1040/540 line label), engine (the engine-computed value, or "DECLINED" where the engine declined that line), filed (the filed-return value, or null if unparseable), delta (filed − engine when both numeric, else null), cls, note? }. `cls` enum: MATCH (|delta| ≤ $2 tolerance) | ENGINE-DECLINED (engine could not compute that line — never cross-filled from the filed value) | DIFFERS (both numeric, beyond tolerance — a human adjudicates; the engine never assigns blame) | NO-FILED (the filed line could not be parsed — diff declined, not guessed). `docTriage` classifies each source document; a filed/client-copy return in the source set is excluded (docKind:'output' → output_excluded) and forces needs_review — an output document is a reconciliation oracle, never a compute input (§6694).

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)

How to present the diff is covered in Check a filed CA return.