--- title: "Get Workpaper (via tax-engine)" method: GET path: "/internal/api/clients/{client_id}/workpaper" tags: ["CLIENT", "Workpaper"] --- # Get Workpaper (via tax-engine) `GET /internal/api/clients/{client_id}/workpaper` ## Request - Base URL: `https://api.signalshq.io` (the document declares no server; this is the origin it was published from) - URL: `https://api.signalshq.io/internal/api/clients/{client_id}/workpaper` - Auth: OAuth 2 - Password - Token URL: `/auth/login` Returns workpaper (status, job, indeterminate_forms, forms) for the given client and tax year. Call after status is COMPLETED. Proxies to tax-engine. ## Path parameters - `client_id` string, uuid, required: Client ID ## Query parameters - `tax_year` integer, required: Tax year (1900-2100) ## Response `200` Successful Response - WorkpaperResponse: GET workpaper response contract. Single shape: level 1 + job + indeterminate_forms + forms. Frontend uses status (display enum) and job; form_tabs removed. - `tax_year` integer, required: Tax year (request context) - `client_id` string, uuid, nullable: Client id (echo from path) - `tax_return_id` string, uuid, nullable: Return id when return exists; null otherwise - `return_status` 'DRAFT' | 'REVIEW' | 'FILED' | 'ACCEPTED': Tax return lifecycle. DB: core_schema.tax_return_status_enum. - `status` 'NO_RETURN' | 'EVALUATING' | 'STALE' | 'READY' | 'ERROR', required: Single display status for GET workpaper (UI branch). Backend-computed; frontend uses this only. - `job` JobResponse: Evaluation job details (replaces regeneration at level 1). Uses DB-backed enums. - `id` string, uuid, nullable: Current or latest evaluation job id - `status` 'IDLE' | 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED', required: Regeneration status for API (includes IDLE when no job). Same as job enum + IDLE. - `last_outcome` 'COMPLETE' | 'PARTIAL' | 'ERROR': Workpaper/form outcome. DB: core_schema.workpaper_status_outcome_enum. - `completed_at` string, date-time, nullable: When the job finished - `error_message` string, nullable: When status=FAILED, error details - `updated_at` string, date-time, nullable: When workpaper was last successfully updated - `indeterminate_forms_count` integer, required: Length of indeterminate_forms - `eligible_forms_count` integer, required: Length of forms - `correlation_id` string, nullable: Request correlation id when provided - `workpaper_pdf_storage_key` string, nullable: Storage key for full workpaper PDF; use with GET .../workpaper/pdf?storage_key= to get presigned URL. - `return_diagnostics_count` integer: Length of return_diagnostics - `indeterminate_forms` IndeterminateForm[]: Forms not yet determined - `form_code` string, required: e.g. SCH_1, 1040 - `display_label` string, required: e.g. Schedule 1 - `form_eligibility_status` string: Always INDETERMINATE here - `dependencies` Dependencies: What a form or line depends on (questions, documents, form lines). - `questions` QuestionRef[]: Questionnaire items - `code` string, required: Question code (e.g. q__filing_status) - `description` string, nullable: Question text from questionnaire definition (e.g. 'What is your filing status?'). Use for UI labels. - `suggestion` string, nullable: User-facing suggestion (e.g. 'Please provide this information in the questionnaire.') - `reason` string, nullable: Why this is needed (e.g. QUESTION_NOT_ANSWERED) - `phase_code` string, nullable: Questionnaire phase (e.g. Deductions, Income, Basic Info). - `instance_number` integer, nullable: 1-based instance number when the question is repeatable (e.g. 1 for dependents.{i}.first_name instance 1) - `documents` DocumentRef[]: Document types - `document_type` string, required: Document type code (e.g. FORM_1099_INT, W_2) - `display_label` string, nullable: Human-readable label (e.g. 1099-INT) - `field_name` string, nullable: Field/attribute identifier when dependency is field-specific (e.g. BOX_1). - `suggestion` string, nullable: User-facing suggestion - `reason` string, nullable: Optional reason - `tax_year` integer, nullable: Tax year filter when relevant - `entity_scope` 'primary' | 'spouse': Entity scope for document refs (primary vs spouse). - `jurisdiction` string, nullable: e.g. federal - `form_lines` FormLineRef[]: Form lines - `form_code` string, required: Form code (e.g. SCH_B, 1040) - `line_number` string, required: Line identifier (e.g. 1, 2b) - `display_label` string, nullable: Human-readable label (e.g. Schedule B, Line 1) - `instance_number` integer, nullable: Instance this line was read from, when it is NOT the instance being calculated -- a Form 8863 Part I total adding each student's Part III page. Null means the calculating instance. Render it beside the label so several rows for the same line read as different pages rather than as a double count. - `suggestion` string, nullable: User-facing suggestion - `reason` string, nullable: Optional reason - `missing_inputs` MissingInputs: What is missing (same shape as Dependencies) plus a user-facing reason. - `questions` QuestionRef[]: Questions not answered - `code` string, required: Question code (e.g. q__filing_status) - `description` string, nullable: Question text from questionnaire definition (e.g. 'What is your filing status?'). Use for UI labels. - `suggestion` string, nullable: User-facing suggestion (e.g. 'Please provide this information in the questionnaire.') - `reason` string, nullable: Why this is needed (e.g. QUESTION_NOT_ANSWERED) - `phase_code` string, nullable: Questionnaire phase (e.g. Deductions, Income, Basic Info). - `instance_number` integer, nullable: 1-based instance number when the question is repeatable (e.g. 1 for dependents.{i}.first_name instance 1) - `documents` DocumentRef[]: Documents missing or suggested - `document_type` string, required: Document type code (e.g. FORM_1099_INT, W_2) - `display_label` string, nullable: Human-readable label (e.g. 1099-INT) - `field_name` string, nullable: Field/attribute identifier when dependency is field-specific (e.g. BOX_1). - `suggestion` string, nullable: User-facing suggestion - `reason` string, nullable: Optional reason - `tax_year` integer, nullable: Tax year filter when relevant - `entity_scope` 'primary' | 'spouse': Entity scope for document refs (primary vs spouse). - `jurisdiction` string, nullable: e.g. federal - `form_lines` FormLineRef[]: Form lines we need but don't have - `form_code` string, required: Form code (e.g. SCH_B, 1040) - `line_number` string, required: Line identifier (e.g. 1, 2b) - `display_label` string, nullable: Human-readable label (e.g. Schedule B, Line 1) - `instance_number` integer, nullable: Instance this line was read from, when it is NOT the instance being calculated -- a Form 8863 Part I total adding each student's Part III page. Null means the calculating instance. Render it beside the label so several rows for the same line read as different pages rather than as a double count. - `suggestion` string, nullable: User-facing suggestion - `reason` string, nullable: Optional reason - `reason` string, nullable: One-line user-facing reason (e.g. 'Answer the questions below to calculate this line.'). Set whenever any item is missing. - `reason` string, nullable: User-facing one-line reason (e.g. 'Answer the questions below to determine if this form applies.'). - `eligibility_audit` EligibilityAuditTrail: Why a form was or was not considered eligible. - `summary` string, nullable - `computed_values` EligibilityAuditMetric[] - `key` string, required: Stable metric key - `label` string, required: Human-readable label - `value` union - string - integer - number - boolean - `documents` EligibilityAuditDocument[] - `document_type` string, required: Document type code - `field_name` string, nullable: Field/attribute when relevant - `display_label` string, nullable: Human-readable label - `role` string, required: accepted | used | possible_overlap | excluded - `amount_total` union - string - integer - number - `note` string, nullable - `review_notes` string[] - `priority` integer, nullable: Lower = resolve first - `recommended_first_action` RecommendedFirstAction: Single recommended action for indeterminate form (do this first). - `type` string, required: question | document | form_line - `code` string, nullable: When type=question - `document_type` string, nullable: When type=document - `form_code` string, nullable: When type=form_line - `line_number` string, nullable: When type=form_line - `display_label` string, nullable: Human-readable label - `suggestion` string, nullable: User-facing suggestion - `forms` FormInstance[]: Eligible forms only (form_eligibility_status=ELIGIBLE) - `form_code` string, required: e.g. 1040, SCH_2 - `instance_number` integer, required: 1-based; >1 for multiple instances (e.g. Schedule C) - `display_order` integer, required: Display order of form in list - `display_label` string, required: e.g. Form 1040, Schedule 2 - `form_eligibility_status` string: Always ELIGIBLE in forms[] - `status` 'CALCULATED' | 'PARTIAL' | 'NOT_CALCULATED' | 'ERROR', required: Form-level calculation status for FormInstance in GET workpaper. - `lines` LineDetail[]: Per-line data (ordered by display_order) - `line_number` string, required: e.g. 1, 7, 9a - `pdf_field_name` string, nullable: AcroForm fully qualified field name for this line (PDF widget id for client viewers). - `display_order` integer, required: Display order (lower = earlier) - `data_type` 'CURRENCY' | 'NUMBER' | 'STRING' | 'DATE' | 'PERCENTAGE' | 'BOOLEAN': Data type for line value display/validation. - `field_type` 'checkbox' | 'currency' | 'date' | 'text' | 'name' | 'ssn' | 'routing_number' | 'account_number' | 'other': Wire/API PDF form field type (LineDetail.field_type). Controls how the field is rendered and edited by the frontend. Lowercase values are retained for API compatibility — the DB column ``tax_form_line_definitions.field_type`` was narrowed to a 4-label Postgres enum in migration V5.0.29 (see :class:`FieldTypeEnum`); the broader lowercase taxonomy here is normalised at the adapter boundary. - `bounding_box` BoundingBox: PDF coordinates for line overlay (e.g. in points, top-left origin). - `top` number, required: Y coordinate of top edge (origin top-left, points) - `left` number, required: X coordinate of left edge (points) - `width` number, required: Width of the line region (points) - `height` number, required: Height of the line region (points) - `page_number` integer: Zero-based page index (0 = first page). Required for multi-page forms. - `line_label` string, nullable: Human-readable line label - `value` union: Calculated or entered value - string - integer - number - boolean - `status` 'PENDING' | 'CALCULATED' | 'ERROR' | 'BLANK' | 'MANUAL' | 'CACHED' | 'SUCCESS', required: Per-line calculation status. DB: core_schema.line_calculation_status_enum. - `transmitted` boolean, nullable: Whether this line is part of the TRANSMITTED page set for the form, as distinct from being computed and retained in the workpaper. Null means the form has no per-part routing and the whole form's filing decision applies. Form 2210 is the case this exists for: its four pieces route independently — page 1 goes with box A or E, Part III and Schedule AI go with box B, C or D, and the Penalty Worksheet is captioned 'Keep for Your Records' and is never transmitted at all. - `form_part` string, nullable: Which independently-routed piece of the form this line belongs to (e.g. page_1, part_iii, schedule_ai, penalty_worksheet). Null on a form whose pieces are not separately routed. - `formula` string, nullable: Expression e.g. 0.2 * SCH_C_LINE_31 - `calculation_explanation` string, nullable: One-sentence summary of how this line was derived (e.g. '20% of Schedule C Line 31 ($25,000) = $5,000.'). - `calculation_breakdown` CalculationStep[], nullable: Equation steps for CPA (e.g. label + value + operator between steps). - `label` string, nullable: Human-readable label (e.g. 20%, Schedule C Line 31) - `value` union: Numeric or display value for this step - string - integer - number - `operator` string, nullable: Between this step and next: *, +, =, etc. - `step_type` string, nullable: Trace step type: input, intermediate, decision, election, bracket, phaseout, limit, override, result, review, skip - `source` object, nullable: TraceSource dict — clickable reference to origin - `expr` string, nullable: Arithmetic expression (e.g. '$85,000 − $14,600') - `reason` string, nullable: Reason for a decision - `decision_result` boolean, nullable: Decision outcome: True/False - `chosen` string, nullable: Election: what was chosen - `alternative` string, nullable: Election: what the alternative was - `savings` string, nullable: Election: quantified impact of the choice - `authority` string, nullable: IRC/legal citation (e.g. 'IRC 63(a)') - `rate` string, nullable: Tax bracket rate (e.g. '15%') - `bracket_lower` number, nullable: Tax bracket lower bound - `bracket_upper` number, nullable: Tax bracket upper bound - `raw_amount` number, nullable: Pre-limit/phaseout amount - `limit_amount` number, nullable: Statutory limit amount - `threshold` number, nullable: Phaseout threshold - `reduction` number, nullable: Phaseout reduction amount - `original_value` string, nullable: Override: computed value before override - `overridden_value` string, nullable: Override: preparer's value - `override_reason` string, nullable: Override: preparer's reason - `code` string, nullable: Review step only: stable machine identifier, e.g. 'SCH_A_5B_ESCROW_OVERLAP'. Needed to dedupe or suppress from the breakdown alone. - `severity` string, nullable: Review step only: 'high' | 'medium' | 'low'. Advisory — see LineDetail.review_severity. - `resolution_hint` string, nullable: Review step only: the concrete action a preparer takes to clear the flag. - `is_auto` boolean: True if auto-captured by proxy, not manually annotated - `needs_review` boolean: True when the engine could not resolve something on this line and a preparer must decide. Derived from review steps in the calculation breakdown; read review_severity for urgency and review_flags for the reason, the authority, and the action that clears it. - `review_severity` string, nullable: Highest severity among this line's review flags: 'high' | 'medium' | 'low'. None when needs_review is False. 'high' means the engine believes the line is probably wrong as computed, or that it carries exam exposure. NOTE: this field is advisory — the engine emits it, but nothing in the current contract persists a clearance or gates export on one. Do not describe it to users as a control until a disposition record exists. - `review_flags` ReviewFlag[], nullable: One entry per review flag on this line, for a review queue that does not parse the breakdown. - `code` string, required: Stable machine identifier, e.g. 'SCH_A_5B_ESCROW_OVERLAP'. - `severity` 'high' | 'medium' | 'low', required: Matches ReviewStep.severity. - `label` string, required: Short headline for the flag. - `reason` string, nullable: Why the engine could not resolve it. - `resolution_hint` string, nullable: The concrete action a preparer takes to clear the flag. - `authority` string, nullable: IRC/Reg citation supporting the concern. - `dependencies` Dependencies: What a form or line depends on (questions, documents, form lines). - `questions` QuestionRef[]: Questionnaire items - `code` string, required: Question code (e.g. q__filing_status) - `description` string, nullable: Question text from questionnaire definition (e.g. 'What is your filing status?'). Use for UI labels. - `suggestion` string, nullable: User-facing suggestion (e.g. 'Please provide this information in the questionnaire.') - `reason` string, nullable: Why this is needed (e.g. QUESTION_NOT_ANSWERED) - `phase_code` string, nullable: Questionnaire phase (e.g. Deductions, Income, Basic Info). - `instance_number` integer, nullable: 1-based instance number when the question is repeatable (e.g. 1 for dependents.{i}.first_name instance 1) - `documents` DocumentRef[]: Document types - `document_type` string, required: Document type code (e.g. FORM_1099_INT, W_2) - `display_label` string, nullable: Human-readable label (e.g. 1099-INT) - `field_name` string, nullable: Field/attribute identifier when dependency is field-specific (e.g. BOX_1). - `suggestion` string, nullable: User-facing suggestion - `reason` string, nullable: Optional reason - `tax_year` integer, nullable: Tax year filter when relevant - `entity_scope` 'primary' | 'spouse': Entity scope for document refs (primary vs spouse). - `jurisdiction` string, nullable: e.g. federal - `form_lines` FormLineRef[]: Form lines - `form_code` string, required: Form code (e.g. SCH_B, 1040) - `line_number` string, required: Line identifier (e.g. 1, 2b) - `display_label` string, nullable: Human-readable label (e.g. Schedule B, Line 1) - `instance_number` integer, nullable: Instance this line was read from, when it is NOT the instance being calculated -- a Form 8863 Part I total adding each student's Part III page. Null means the calculating instance. Render it beside the label so several rows for the same line read as different pages rather than as a double count. - `suggestion` string, nullable: User-facing suggestion - `reason` string, nullable: Optional reason - `missing_inputs` MissingInputs: What is missing (same shape as Dependencies) plus a user-facing reason. - `questions` QuestionRef[]: Questions not answered - `code` string, required: Question code (e.g. q__filing_status) - `description` string, nullable: Question text from questionnaire definition (e.g. 'What is your filing status?'). Use for UI labels. - `suggestion` string, nullable: User-facing suggestion (e.g. 'Please provide this information in the questionnaire.') - `reason` string, nullable: Why this is needed (e.g. QUESTION_NOT_ANSWERED) - `phase_code` string, nullable: Questionnaire phase (e.g. Deductions, Income, Basic Info). - `instance_number` integer, nullable: 1-based instance number when the question is repeatable (e.g. 1 for dependents.{i}.first_name instance 1) - `documents` DocumentRef[]: Documents missing or suggested - `document_type` string, required: Document type code (e.g. FORM_1099_INT, W_2) - `display_label` string, nullable: Human-readable label (e.g. 1099-INT) - `field_name` string, nullable: Field/attribute identifier when dependency is field-specific (e.g. BOX_1). - `suggestion` string, nullable: User-facing suggestion - `reason` string, nullable: Optional reason - `tax_year` integer, nullable: Tax year filter when relevant - `entity_scope` 'primary' | 'spouse': Entity scope for document refs (primary vs spouse). - `jurisdiction` string, nullable: e.g. federal - `form_lines` FormLineRef[]: Form lines we need but don't have - `form_code` string, required: Form code (e.g. SCH_B, 1040) - `line_number` string, required: Line identifier (e.g. 1, 2b) - `display_label` string, nullable: Human-readable label (e.g. Schedule B, Line 1) - `instance_number` integer, nullable: Instance this line was read from, when it is NOT the instance being calculated -- a Form 8863 Part I total adding each student's Part III page. Null means the calculating instance. Render it beside the label so several rows for the same line read as different pages rather than as a double count. - `suggestion` string, nullable: User-facing suggestion - `reason` string, nullable: Optional reason - `reason` string, nullable: One-line user-facing reason (e.g. 'Answer the questions below to calculate this line.'). Set whenever any item is missing. - `inputs_used` InputsUsed: What was used to compute a line (questions, documents, form lines). - `questions` QuestionInputUsed[]: Questionnaire answers used - `code` string, required: Question code (template form, e.g. dependents.{i}.first_name) - `instance_id` string, uuid, nullable: Questionnaire instance/response id when available - `instance_number` integer, nullable: 1-based instance number when the question is repeatable - `description` string, nullable: Question text from questionnaire (e.g. 'What is your filing status?'). Use for UI. - `data_type` string, nullable: STRING, NUMBER, DATE, BOOLEAN, ENUM - `value_used` union: Value from questionnaire - string - integer - number - boolean - `phase_code` string, nullable: Questionnaire phase for this question (e.g. Deductions, Income). - `documents` DocumentInputUsed[]: Documents used - `document_type` string, required: Document type code - `document_id` string, uuid, nullable: Document record id when available - `document_name` string, nullable: Display name from DMS when integrated; reserved until then. - `attribute_identifier` string, nullable: Box/field (e.g. BOX_1) - `contributing_value` union: Actual value from this document when present; null when the input was blank (see blank_reason). - string - integer - number - `blank_reason` string, nullable: When this document input was blank (N/A), the reason code. Omit when contributing_value is set. - `blank_display_message` string, nullable: User-facing message for blank_reason. Use for tooltip when contributing_value is null. - `document_status` 'APPROVED' | 'PENDING_REVIEW' | 'NEEDS_REVIEW' | 'REJECTED': Document status for inputs_used (DMS workflow). - `tax_year` integer, nullable: Tax year of document when relevant - `entity_scope` 'primary' | 'spouse': Entity scope for document refs (primary vs spouse). - `form_lines` FormLineInputUsed[]: Form lines used - `form_code` string, required: Form code (e.g. SCH_B, 1040) - `line_number` string, required: Line identifier - `display_label` string, nullable: Human-readable label - `instance_number` integer, nullable: Instance this line was read from, when it is NOT the instance being calculated -- a Form 8863 Part I total adding each student's Part III page. Null means the calculating instance. Render it beside the label so several rows for the same line read as different pages rather than as a double count. - `contributing_value` union: Actual value used when the form line had a value; null when the input was blank (see blank_reason). - string - integer - number - `blank_reason` string, nullable: When this input was blank (N/A), the reason code (e.g. no_dependents_for_ctc). Omit when contributing_value is set. - `blank_display_message` string, nullable: User-facing message for blank_reason (e.g. 'No dependents for CTC'). Use for tooltip or secondary text when contributing_value is null. - `inputs_read` InputsUsed: What was used to compute a line (questions, documents, form lines). - `questions` QuestionInputUsed[]: Questionnaire answers used - `code` string, required: Question code (template form, e.g. dependents.{i}.first_name) - `instance_id` string, uuid, nullable: Questionnaire instance/response id when available - `instance_number` integer, nullable: 1-based instance number when the question is repeatable - `description` string, nullable: Question text from questionnaire (e.g. 'What is your filing status?'). Use for UI. - `data_type` string, nullable: STRING, NUMBER, DATE, BOOLEAN, ENUM - `value_used` union: Value from questionnaire - string - integer - number - boolean - `phase_code` string, nullable: Questionnaire phase for this question (e.g. Deductions, Income). - `documents` DocumentInputUsed[]: Documents used - `document_type` string, required: Document type code - `document_id` string, uuid, nullable: Document record id when available - `document_name` string, nullable: Display name from DMS when integrated; reserved until then. - `attribute_identifier` string, nullable: Box/field (e.g. BOX_1) - `contributing_value` union: Actual value from this document when present; null when the input was blank (see blank_reason). - string - integer - number - `blank_reason` string, nullable: When this document input was blank (N/A), the reason code. Omit when contributing_value is set. - `blank_display_message` string, nullable: User-facing message for blank_reason. Use for tooltip when contributing_value is null. - `document_status` 'APPROVED' | 'PENDING_REVIEW' | 'NEEDS_REVIEW' | 'REJECTED': Document status for inputs_used (DMS workflow). - `tax_year` integer, nullable: Tax year of document when relevant - `entity_scope` 'primary' | 'spouse': Entity scope for document refs (primary vs spouse). - `form_lines` FormLineInputUsed[]: Form lines used - `form_code` string, required: Form code (e.g. SCH_B, 1040) - `line_number` string, required: Line identifier - `display_label` string, nullable: Human-readable label - `instance_number` integer, nullable: Instance this line was read from, when it is NOT the instance being calculated -- a Form 8863 Part I total adding each student's Part III page. Null means the calculating instance. Render it beside the label so several rows for the same line read as different pages rather than as a double count. - `contributing_value` union: Actual value used when the form line had a value; null when the input was blank (see blank_reason). - string - integer - number - `blank_reason` string, nullable: When this input was blank (N/A), the reason code (e.g. no_dependents_for_ctc). Omit when contributing_value is set. - `blank_display_message` string, nullable: User-facing message for blank_reason (e.g. 'No dependents for CTC'). Use for tooltip or secondary text when contributing_value is null. - `last_calculated_at` string, date-time, nullable: When this line was last (re)calculated. - `last_calculated_by` string, uuid, nullable: User id who triggered the calculation; null if system/unknown. - `error_message` string, nullable: When status=ERROR, reason for failure - `blank_display_message` string, nullable: When status=BLANK, short user-friendly reason for UI (e.g. 'No wages') - `is_reconstructed` boolean: True when this line was synthesized from definitions/audit because no computed row was persisted. - `trace_completeness` string, nullable: Trace quality: 'full' (manual annotations), 'auto' (proxy-only inputs/result), or None (no trace). - `trace_version` integer: Trace schema version for forward compatibility. - `has_workpaper_pdf` boolean: True when a per-form workpaper PDF has been generated and stored (artifact storage). - `workpaper_pdf_storage_key` string, nullable: Storage key for this form's workpaper PDF; use with GET .../workpaper/pdf?storage_key= to get presigned URL. - `eligibility_audit` EligibilityAuditTrail: Why a form was or was not considered eligible. - `summary` string, nullable - `computed_values` EligibilityAuditMetric[] - `key` string, required: Stable metric key - `label` string, required: Human-readable label - `value` union - string - integer - number - boolean - `documents` EligibilityAuditDocument[] - `document_type` string, required: Document type code - `field_name` string, nullable: Field/attribute when relevant - `display_label` string, nullable: Human-readable label - `role` string, required: accepted | used | possible_overlap | excluded - `amount_total` union - string - integer - number - `note` string, nullable - `review_notes` string[] - `transmitted_parts` string[]: The independently-routed pieces of this form that ARE transmitted. Empty on a form with no per-part routing, where the form-level filing decision covers everything. - `workpaper_only_parts` string[]: Pieces computed and retained in the workpaper but NOT transmitted. A Form 2210 filed for a box A waiver carries page 1 here and Part III in this list: the taxpayer 'isn''t required to figure your penalty', so transmitting Part III would assert a penalty Form 1040 line 38 deliberately leaves blank — the F1040-053 mismatch. - `return_diagnostics` ReturnDiagnostic[]: Findings about the return as a whole, most severe first. Unlike LineDetail.review_flags these are not owned by any line — they are how the engine reports a form that should exist but does not, which by construction has no line to flag. Recomputed on every read. - `code` string, required: Stable machine identifier, e.g. 'FOREIGN_PFIC_EVIDENCE_WITHOUT_GATE'. - `severity` 'high' | 'medium' | 'low', required: high: a required form is likely missing, or a statute-suspending information return is implicated. medium: a form is in scope but cannot be completed. low: advisory. - `label` string, required: Short headline, e.g. 'Form 8621 may be required'. - `reason` string, required: What the engine observed and why it matters. - `resolution_hint` string, required: The concrete action a preparer takes to clear the diagnostic. - `authority` string, nullable: IRC/Reg citation supporting the concern. - `implicated_forms` string[]: Form codes this diagnostic concerns, e.g. ['FORM_8621']. May name a form the engine does not model (e.g. 'FORM_5471', 'FINCEN_114') — that is the point: the diagnostic is how an out-of-scope obligation becomes visible instead of silently absent. - `evidence` string[]: Human-readable facts the engine actually observed, e.g. 'Schedule K-3 Part VII reports 2 PFICs'. Lets a preparer confirm or dismiss the diagnostic without re-deriving it. ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/signalshq/apis/signals-api.md) - [All operations](https://skmtc.dev/signalshq/apis/signals-api/llms.txt) - [OpenAPI document](https://skmtc.dev/signalshq/apis/signals-api/revisions/2c22af3b5576?raw)