Read a broker 1099-B export
Send one document and get its 1099-B lots back as unconfirmed evidence. The engine keeps nothing.
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.
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
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer <API key> |
| Content-Type | Yes | text/csv |
| X-Tax-Year | No | Expected tax year; a document printing another year is refused (tax_year_mismatch). |
| X-Document-Ref | No | Echoed back as documentRef. |
Sending Idempotency-Key returns 400 on purpose: document reads are never stored, so there is nothing to replay.
Request body
| Field | Description |
|---|---|
| (body)text/csv, up to 10,000,000 bytesrequired | The export file's bytes, unchanged. |
Example
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{
"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
| Status | Meaning |
|---|---|
| 200 | IntakeEnvelope: lots as printed, never a complete set (read:false with a code when refused) |
| 400 | Invalid body / JSON / failed validation |
| 401 | Missing / unknown / revoked key (no enumeration) |
| 403 | intake_not_enabled: this key's plan can't call intake |
| 413 | document_too_large or too_many_rows |
| 415 | unsupported_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. |
| 500 | Sanitized server error computing the return |
| 503 | metering_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.
| Capability | Status |
|---|---|
| 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 |