Form 1040 as a draft PDF
The Form 1040 lines of one original 2023-2025 return, filled in on that year's official IRS form, marked as a draft not for filing.
The return-lines Form 1040 on the year's official IRS PDF, as a draft not for filing, 2023-2025.
Same request and decline as /return-lines. The computed lines fill the IRS Form 1040 (read-only but for the page-1 boxes above the filing status, such as names and SSNs) and its schedules, flattened. An appended page lists lines assumed 0, lines not computed, forms not included and flags. 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
The same body as /return-lines, and the same lines: the PDF shows exactly the amounts /return-lines returns for that body.
The PDF
A computed return answers 200 with content-type: application/pdf: the year's IRS Form 1040 with every computedline filled in, in whole dollars, and the filing status, age 65, blindness, dependent and spouse-itemizes boxes your request decides checked. Every other line is left empty. Every box is read-only except the text boxes above the filing status on page 1 (such as names, SSNs and the address), so a line can't be changed without recomputing the totals that depend on it; to change one, change the request and call again. Each form page is stamped "DRAFT — NOT FOR FILING".
Schedules 1, 2, 3, D and 8812 follow the Form 1040 pages when the return needs them (the response's schedules from /return-lines), on the year's IRS forms, with every computed line filled. They are printed flat onto their pages, so nothing on them is fillable, including their name and SSN lines.
An appended page lists the lines assumed to be 0, the lines not computed, the schedules and forms the filled lines are carried from (not included), the boxes left unchecked and the computation's flags. The X-Tax-Mcp-Form-Sha256header is the sha256 of the blank IRS Form 1040 used (the appended page also lists each schedule's) and X-Tax-Mcp-Request-Hash identifies the request. The same request renders the same bytes for as long as the blank form and the renderer stay the same.
Example: a decline
A return /return-lines declines comes back as the same JSON decline, so check the content type before reading the body.
curl https://tax-mcp.com/api/mcp/tax-compute/draft-pdf \
-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,
"pensionDistributionTaxable": 5000
},
"payments": {
"form1099Withholding": 0,
"estimatedTaxPayments": 0,
"extensionPayment": 0,
"appliedToNextYearEstimatedTax": 0,
"estimatedTaxPenalty": 0
},
"paymentsAffirmed": true
}'{
"computed": false,
"code": "retirement_line_unknown",
"reason": "pensionDistributionTaxable is positive: send retirementDistributionLine (4b for an IRA, SEP or SIMPLE distribution, 5b for a pension or annuity), or iraDistributionTaxable for the IRA part of both",
"billed": true,
"retry_safe": false,
"next_action": "review_inputs"
}Full response, including line derivations
{
"computed": false,
"code": "retirement_line_unknown",
"reason": "pensionDistributionTaxable is positive: send retirementDistributionLine (4b for an IRA, SEP or SIMPLE distribution, 5b for a pension or annuity), or iraDistributionTaxable for the IRA part of both",
"billed": true,
"retry_safe": false,
"next_action": "review_inputs"
}Responses
| Status | Meaning |
|---|---|
| 200 | application/pdf when the return computed, with X-Tax-Mcp-Form-Sha256 (the blank IRS form) and X-Tax-Mcp-Request-Hash headers; otherwise the /return-lines decline as JSON. |
| 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 | As every route, plus `draft_pdf_renderer_changed`: a retry after the blank form or the renderer changed, which would not be the same PDF. Send that one with a new Idempotency-Key. 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) |
With an Idempotency-Key, a retry returns the same PDF. If the form or the renderer changed between the first call and the retry, the retry is a 409 with draft_pdf_renderer_changed: send it with a new key.
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 |
|---|---|
| A draft Form 1040 PDF on the IRS form, 2023-2025The return-lines Form 1040 on the official IRS PDF, marked as a draft not for filing, with a page listing what it leaves out. |