API reference

Read a broker 1099-B export

Send one document and get its 1099-B lots back as unconfirmed evidence. The engine keeps nothing.

POSThttps://tax-mcp-intake-929575446942.us-central1.run.app/api/mcp/intake/read

Read one tax document into an untrusted envelope; nothing is kept.

Reads the 1099-B section of a row-tagged broker CSV export in one layout, whole or not at all (read:false with codes and rows). Every value is unconfirmed evidence for a preparer to check; nothing here is a tax input until the caller confirms it. Internal-plan keys only. The document is not stored, and Idempotency-Key is refused (400) because reads are never kept for replay.

This endpoint is on its own host, https://tax-mcp-intake-929575446942.us-central1.run.app, not tax-mcp.com. Only internal-plan keys can call it for now.

What it reads

One layout: the 1099-B section of a row-tagged broker CSV export, where the first column names the form on every row and the 1099-B header is exactly the accepted column list. Other sections in the file are listed in unread by form name; a 1256 section is also flagged on the 1099-B envelope as section_1256_unread. A lot carrying a tax character this API doesn't read yet refuses the file (lot_character_not_read). PDF, XLSX and ZIP files are refused with 415 for now.

Nothing here is a tax input yet

Every value is what the document printed. To use a value in a computation, check it and send it yourself to a compute route, for example as capGainAggregates on the federal route. The response never fills form8949Box and never contains an affirmation; those are yours to give.

A file is read whole or not at all. When any row isn't a clean lot, the file is refused: read is false, no lots are served, and needsReview names each reason with its rows. When read is true, each lot is a row as printed. That is not a reconciled set: a read can still omit or duplicate lots, so every read carries lots_unreconciled. Check the lots against the document before you sum them; an omitted gain under-taxes. Read unreadeither way: other forms' sections and statement lines are listed there.

Corrected forms and duplicates

Intake reads one document per call and keeps nothing, so matching documents is yours. Two reads with the same fingerprintare the same document text, apart from line endings, spacing and blank lines (a rotation of the service's hashing key changes every fingerprint). correctedis always null: a banner's wording isn't proof a document is a reissue. When a file is read, needsReview lists corrected_printed if a banner contains the word CORRECTED; a refused file lists only its refusal codes.

Set an original aside only when all of these hold: you matched the reissue to it by payer and the whole account number printed on both documents, there is one reissue, and it restates every lot. Never match on accountLast4, the account's last 4 characters, which two accounts can share. In every other case (no whole account printed, the original not on file, more than one reissue, a reissue that restates only some lots) set nothing aside and review the documents by hand: dropping one can omit income, and keeping both counts restated lots twice.

Headers

HeaderRequiredDescription
AuthorizationYesBearer <API key>
Content-TypeYestext/csv
X-Tax-YearNoExpected tax year; a document printing another year is refused (tax_year_mismatch).
X-Document-RefNoEchoed back as documentRef.

Sending Idempotency-Key returns 400 on purpose: document reads are never stored, so there is nothing to replay.

Request body

FieldDescription
(body)text/csv, up to 10,000,000 bytesrequiredThe export file's bytes, unchanged.

Example

Request
curl https://tax-mcp-intake-929575446942.us-central1.run.app/api/mcp/intake/read \
  -H "Authorization: Bearer $TAX_MCP_API_KEY" \
  -H "Content-Type: text/csv" \
  -H "X-Tax-Year: 2025" \
  -H "X-Document-Ref: client-42-broker-1" \
  --data-binary @1099-export.csv
Response (200)
{
  "version": "intake-envelope-v1",
  "documentRef": "client-42-broker-1",
  "read": true,
  "envelopes": [
    {
      "formType": "1099-B",
      "taxYear": 2025,
      "corrected": null,
      "identity": {
        "payerName": null,
        "payerTinLast4": null,
        "accountLast4": ["1234"],
        "fingerprint": "8f0af34a33ddb26d1f04dffa6881af2d19e8ee8063e08ac6cc6ace18834267a3"
      },
      "lots": [
        {
          "row": 2,
          "description": "EXAMPLE CORP",
          "proceeds": 1250,
          "costBasis": 1000,
          "washSaleDisallowed": null,
          "acquiredDate": "20250103",
          "soldDate": "20250610",
          "termPrinted": "short",
          "nonCoveredPrinted": null,
          "basisNotShownPrinted": null,
          "form8949CodePrinted": "A",
          "form8949Box": null
        },
        {
          "row": 3,
          "description": "SAMPLE FUND",
          "proceeds": 2100,
          "costBasis": 2400,
          "washSaleDisallowed": 150,
          "acquiredDate": "20230212",
          "soldDate": "20250815",
          "termPrinted": "long",
          "nonCoveredPrinted": null,
          "basisNotShownPrinted": null,
          "form8949CodePrinted": "D",
          "form8949Box": null
        }
      ],
      "needsReview": [
        { "code": "lots_unreconciled" }
      ]
    }
  ],
  "unread": [
    { "section": "1099-DIV", "code": "section_not_served", "rows": 2 }
  ],
  "billed": false,
  "retry_safe": true,
  "next_action": "review_inputs"
}

Responses

StatusMeaning
200IntakeEnvelope: lots as printed, never a complete set (read:false with a code when refused)
400Invalid body / JSON / failed validation
401Missing / unknown / revoked key (no enumeration)
403intake_not_enabled: this key's plan can't call intake
413document_too_large or too_many_rows
415unsupported_media_type, unsupported_format, not_utf8 or content_encoding_not_supported
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_failure or service_unavailable (retry after backoff), or intake_misconfigured

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.

Source intake (Phase 4) — document → untrusted evidence → JSON envelopes
CapabilityStatus
1099-B lots from one broker CSV layoutReads 1099-B lots from one broker CSV layout, as printed. Has known gaps.Known gap: A read can omit or repeat a lot; reconcile before summing◐ certifying