{"openapi":"3.1.0","info":{"title":"Signals API","description":"\n        Welcome to the Signals API.\n\n        This API allows businesses to manage invoices, including creating, retrieving, and processing invoices.\n\n        ## Key Features\n        - Create, read, and update invoices.\n        - Attach line items with detailed descriptions and prices.\n        - Easily calculate total amounts based on line items.\n\n        ## Authentication\n        This API supports API key-based authentication to access sensitive invoice data.\n\n        ## Example Use Cases\n        - A user can retrieve all invoices for a given business.\n        - A business owner can update the status of a specific invoice.\n        - Detailed itemized lists can be attached to each invoice for clarity.\n\n        ## How to Start\n        1. Create an API key by signing up.\n        2. Use the API key to authenticate requests.\n        3. Make requests using the provided endpoints.\n\n        ## Contact\n        For questions or support, please contact us at support@signalshq.io.\n\n        ## Version\n        - API Version: 1.0.0\n        ","version":"1.0.0"},"paths":{"/internal/api/document/types":{"get":{"tags":["DOCUMENT"],"summary":"Lists supported document types for extraction with attributes","description":"Returns all active document types that support extraction, including each type's attribute definitions.","operationId":"list_supported_document_types_internal_api_document_types_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"include_only_supported","in":"query","required":false,"schema":{"type":"boolean","description":"If true, returns only attributes marked as supported.","default":true,"title":"Include Only Supported"},"description":"If true, returns only attributes marked as supported."},{"name":"include_only_shown_on_ui","in":"query","required":false,"schema":{"type":"boolean","description":"If true, returns only attributes marked to be shown on UI.","default":true,"title":"Include Only Shown On Ui"},"description":"If true, returns only attributes marked to be shown on UI."},{"name":"include_inactive","in":"query","required":false,"schema":{"type":"boolean","description":"If true, also returns extraction-DISABLED types (is_active=False) so the reclassify picker can show 'extraction not enabled' types. Default false = active only.","default":false,"title":"Include Inactive"},"description":"If true, also returns extraction-DISABLED types (is_active=False) so the reclassify picker can show 'extraction not enabled' types. Default false = active only."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportedDocumentTypesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/document/schedule-c-mappings":{"get":{"tags":["DOCUMENT"],"summary":"Get Schedule C mappings for Profit and Loss Statement","description":"Returns all supported attributes for the Profit and Loss Statement document type. These attributes represent the Schedule C line items that can be mapped from financial statements.","operationId":"get_schedule_c_mappings_internal_api_document_schedule_c_mappings_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleCMappingsResponse"}}}}},"security":[{"CustomOAuth2PasswordBearer":[]}]}},"/internal/api/document/{document_id}/response":{"post":{"tags":["DOCUMENT"],"summary":"Get extraction response for a document (original structure - backward compatibility)","description":"Returns extracted attributes for the specified document as a flat list (old structure for backward compatibility). For the new year-grouped structure, use the /v2/{document_id}/response endpoint. Each attribute includes key, display_name, datatype, confidence_score, bounding_regions, status, and optionally document_key (for LLM extractions). The document must belong to the authenticated user's tenant and the specified client.","operationId":"get_document_extraction_response_internal_api_document__document_id__response_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Document ID","title":"Document Id"},"description":"Document ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentExtractionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentExtractionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/document/v2/{document_id}/response":{"post":{"tags":["DOCUMENT"],"summary":"Get extraction response for a document grouped by year (V2)","description":"V2 endpoint: Returns extracted attributes for the specified document, grouped and sorted by year. Attributes are grouped using the year column stored in the database. Each year group contains attributes with key, display_name, datatype, confidence_score, bounding_regions, status, and optionally document_key (for LLM extractions). Years are sorted in descending order. The document must belong to the authenticated user's tenant and the specified client.","operationId":"get_document_extraction_response_v2_internal_api_document_v2__document_id__response_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Document ID","title":"Document Id"},"description":"Document ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentExtractionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentExtractionResponseV2"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/document/1099c/{document_id}/response":{"post":{"tags":["DOCUMENT"],"summary":"Get 1099-Consolidated extraction response in 5-tab tree format","description":"Returns the same year-grouped extraction data as the v2 endpoint, but reshaped for the 1099-Consolidated UI: a common header (TaxYear, Payer.*, Recipient.*) plus 5 tabs (1099-INT, 1099-DIV, 1099-OID, 1099-MISC, 1099-B) inside each year. The 1099-B tab is nested as Part I/II > Box A-F > leaves. 1099-DA (Form 8949 codes G-L) is intentionally excluded from this endpoint. Returns HTTP 400 if the document is not classified as 1099-Consolidated; use the /v2/{document_id}/response endpoint for other document types.","operationId":"get_document_extraction_response_1099c_internal_api_document_1099c__document_id__response_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Document ID","title":"Document Id"},"description":"Document ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentExtractionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document1099CExtractionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/document/{document_id}/k1/response":{"post":{"tags":["DOCUMENT"],"summary":"Get K1 extraction response in normalized envelope shape","description":"Returns K1 extraction result structured as the K1xStandard normalized envelope. Top-level keys per subtype (standard_1065, schedule_k3, etc.), each containing sections with flattened attributes.","operationId":"get_k1_extraction_response_internal_api_document__document_id__k1_response_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Document ID","title":"Document Id"},"description":"Document ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentExtractionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/K1NormalizedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/document/attribute/{attribute_id}/validate":{"patch":{"tags":["DOCUMENT"],"summary":"Validate an extracted attribute","operationId":"validate_extracted_attribute_endpoint_internal_api_document_attribute__attribute_id__validate_patch","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"attribute_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Extracted attribute ID","title":"Attribute Id"},"description":"Extracted attribute ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttributeValidationRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttributeValidationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/document/{document_id}/workflow":{"post":{"tags":["DOCUMENT"],"summary":"Approve, reject, or reopen an extracted document","description":"Consolidated endpoint for approving, rejecting, or reopening extracted documents. Use the 'action' query parameter to specify the action: 'approve', 'reject', or 'reopen'. For rejection and reopening, a reason must be provided in the request body.","operationId":"document_action_endpoint_internal_api_document__document_id__workflow_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Document ID","title":"Document Id"},"description":"Document ID"},{"name":"action","in":"query","required":true,"schema":{"$ref":"#/components/schemas/DocumentWorkflowAction","description":"Action to perform: 'approve', 'reject', or 'reopen'"},"description":"Action to perform: 'approve', 'reject', or 'reopen'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/DocumentApprovalRequest"},{"$ref":"#/components/schemas/DocumentRejectionRequest"},{"$ref":"#/components/schemas/DocumentReopenRequest"}],"title":"Action Request"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/DocumentApprovalResponse"},{"$ref":"#/components/schemas/DocumentRejectionResponse"},{"$ref":"#/components/schemas/DocumentReopenResponse"}],"title":"Response Document Action Endpoint Internal Api Document  Document Id  Workflow Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/document/workflow/{workflow_id}":{"post":{"tags":["DOCUMENT"],"summary":"Get workflow status","operationId":"get_workflow_status_endpoint_internal_api_document_workflow__workflow_id__post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Workflow ID","title":"Workflow Id"},"description":"Workflow ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentExtractionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/document/bulk-status":{"post":{"tags":["DOCUMENT"],"summary":"Get bulk document extraction status","description":"Returns the latest extraction status for multiple documents with pagination support. Useful for polling the status of multiple document extractions in a single request. Returns status information including current state, error messages, and timestamps. Documents not found in the extraction table will be listed in the 'not_found' array. Supports standard pagination parameters for consistent API structure.","operationId":"get_bulk_document_extraction_status_internal_api_document_bulk_status_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (1-based)","default":1,"title":"Page"},"description":"Page number (1-based)"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page (max 100)","default":20,"title":"Page Size"},"description":"Number of items per page (max 100)"},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Field to sort by (created_at, status)","default":"created_at","title":"Sort By"},"description":"Field to sort by (created_at, status)"},{"name":"sort_order","in":"query","required":false,"schema":{"$ref":"#/components/schemas/SortOrder","description":"Sort order","default":"desc"},"description":"Sort order"},{"name":"search_query","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search term","title":"Search Query"},"description":"Search term"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDocumentStatusRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedBulkDocumentStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/document/extract":{"post":{"tags":["DOCUMENT"],"summary":"Bulk extract (or reextract with type) documents","description":"Creates a Celery group of tasks for each document ID to extract tax documents. Returns immediately with task creation status. Use the /bulk-status endpoint to poll for extraction progress. Optional document_type_id: when provided, extraction runs with that document type and reruns are allowed (skips 'already extracted' check).","operationId":"bulk_extract_documents_endpoint_internal_api_document_extract_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDocumentExtractionRequest"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDocumentExtractionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"CustomOAuth2PasswordBearer":[]}]}},"/internal/api/document/{document_id}/reclassify":{"post":{"tags":["DOCUMENT"],"summary":"Reclassify a document's type and re-extract","description":"Manually override a document's type when classification failed or mis-classified, and trigger re-extraction with the corrected type. Validates the target type, blocks multi-form documents, records provenance, and re-extracts. Ops-only in Phase 1. Pass force=true to re-run extraction on the type the document ALREADY has — the way to move a document off the older extraction system once its doctype is on the new flow.","operationId":"reclassify_document_endpoint_internal_api_document__document_id__reclassify_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Document ID to reclassify","title":"Document Id"},"description":"Document ID to reclassify"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReclassifyDocumentRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReclassifyDocumentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/document/{document_id}/party":{"patch":{"tags":["DOCUMENT"],"summary":"Set whose document this is (taxpayer / spouse / joint)","description":"Records the CPA's decision about which person on a joint return a document belongs to. A manual edit LOCKS the value: no later system write — resolver or backfill — may overwrite it. Rejects a role the document's type does not permit (a W-2 has one employee; an IRA has exactly one owner under IRC 408(a)), and rejects the v2-reserved roles. Joint returns only.","operationId":"set_document_party_endpoint_internal_api_document__document_id__party_patch","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Document to attribute","title":"Document Id"},"description":"Document to attribute"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetDocumentPartyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetDocumentPartyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/document/party/bulk":{"patch":{"tags":["DOCUMENT"],"summary":"Set the party on several documents at once","description":"Assigns one party across a selection. The allowed roles are the INTERSECTION across the selected document types, so picking a W-2 alongside a 1099-INT drops Joint from the menu rather than failing on one row. Returns per-document applied/skipped with reasons so the UI can disclose what it did NOT do — silently assigning 9 of 12 is a correctness bug the CPA cannot see.","operationId":"set_document_party_bulk_endpoint_internal_api_document_party_bulk_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetDocumentPartyBulkRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetDocumentPartyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"CustomOAuth2PasswordBearer":[]}]}},"/internal/api/document/party/undo":{"patch":{"tags":["DOCUMENT"],"summary":"Undo a bulk owner assignment","description":"Restores each document's PRIOR owner. Recorded as UNDO, which is deliberately non-locking: an undo restores a state, it does not make a decision. Sending these back through the normal endpoint would lock documents at 'undecided' forever and promote auto-set suggestions into human decisions.","operationId":"undo_document_party_endpoint_internal_api_document_party_undo_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UndoDocumentPartyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetDocumentPartyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"CustomOAuth2PasswordBearer":[]}]}},"/internal/api/document/{document_id}/confirm-split":{"post":{"tags":["DOCUMENT"],"summary":"Confirm a multi-document bundle's page-range breakup and extract each form","description":"Slices a MULTI_DOCUMENT bundle into one child document per CPA-confirmed form (page range), then triggers extraction for each child. Validates full page coverage / no overlaps / fan-out cap, rejects K-1 bundles (409), and is idempotent on double-confirm.","operationId":"confirm_split_endpoint_internal_api_document__document_id__confirm_split_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Bundle (parent) document ID to split","title":"Document Id"},"description":"Bundle (parent) document ID to split"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmSplitRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmSplitResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/document/{document_id}/children":{"get":{"tags":["DOCUMENT"],"summary":"List a multi-document bundle's split children","description":"Returns the child documents materialized from a confirmed bundle (for BundleReview).","operationId":"list_bundle_children_endpoint_internal_api_document__document_id__children_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Bundle (parent) document ID","title":"Document Id"},"description":"Bundle (parent) document ID"},{"name":"client_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Client the bundle belongs to","title":"Client Id"},"description":"Client the bundle belongs to"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmSplitResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/document/{document_id}/initiate-split":{"post":{"tags":["DOCUMENT"],"summary":"Manually open ANY document for split — the CPA fail-safe override","description":"Flips a document into AWAITING_SPLIT on demand so the CPA can split it regardless of how the classifier labeled it (single form, 'Other', 'Unsupported', or a failed classification). Rejects a SPLIT_CHILD; idempotent if already awaiting split.","operationId":"initiate_split_endpoint_internal_api_document__document_id__initiate_split_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The document to open for split","title":"Document Id"},"description":"The document to open for split"},{"name":"client_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Client the document belongs to","title":"Client Id"},"description":"Client the document belongs to"}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Initiate Split Endpoint Internal Api Document  Document Id  Initiate Split Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/document/{document_id}/cancel-split":{"post":{"tags":["DOCUMENT"],"summary":"Abandon an un-confirmed split — revert the bundle to a normal document","description":"Reverts an AWAITING_SPLIT bundle (split started but never confirmed) back to a STANDALONE document, clearing the dormant 'Finish splitting' state. Rejects a CONFIRMED bundle (delete or re-split it instead); idempotent if the document is not awaiting split.","operationId":"cancel_split_endpoint_internal_api_document__document_id__cancel_split_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The bundle whose un-confirmed split to cancel","title":"Document Id"},"description":"The bundle whose un-confirmed split to cancel"},{"name":"client_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Client the document belongs to","title":"Client Id"},"description":"Client the document belongs to"}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Cancel Split Endpoint Internal Api Document  Document Id  Cancel Split Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/document/{document_id}/keep-as-one":{"post":{"tags":["DOCUMENT"],"summary":"Keep a detected multi-form document as ONE consolidated 1099 instead of splitting","description":"Classifies the document as a 1099 Consolidated Statement and extracts it whole — the CPA escape hatch for a brokerage consolidated they'd rather review as a single statement. Rejects a split child or an already-confirmed bundle.","operationId":"keep_as_one_endpoint_internal_api_document__document_id__keep_as_one_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The document to keep as one consolidated 1099","title":"Document Id"},"description":"The document to keep as one consolidated 1099"},{"name":"client_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Client the document belongs to","title":"Client Id"},"description":"Client the document belongs to"}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Keep As One Endpoint Internal Api Document  Document Id  Keep As One Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/document/{document_id}/tie-out":{"get":{"tags":["DOCUMENT"],"summary":"Reconcile a split bundle — per-form sum-of-children vs the statement total","description":"For a confirmed split bundle, returns a per-1099-family tie-out: the sum of the children's control-line box values, reconciled against the statement total where one exists (1099-B proceeds). `has_statement_total=false` means it's a neutral sum-of-children readback, not a variance check — so a CPA can confirm a consolidated 1099 split ties out.","operationId":"bundle_tie_out_endpoint_internal_api_document__document_id__tie_out_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The confirmed split bundle to reconcile","title":"Document Id"},"description":"The confirmed split bundle to reconcile"},{"name":"client_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Client the document belongs to","title":"Client Id"},"description":"Client the document belongs to"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BundleTieOutResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/document/{document_id}/retry":{"post":{"tags":["DOCUMENT"],"summary":"Retry extraction for a failed/stuck document","description":"Re-run extraction for a document whose extraction FAILED or got stuck (no review workflow / no editable fields). Creates a NEW extraction job for the document and re-extracts with its canonical type (or re-classifies if it was never classified). Idempotent under concurrency: a genuinely in-flight job is not duplicated, and a job left non-terminal by a killed worker stops blocking once it ages out. Does NOT change the document's type or supersede a prior review.\n\n**Read the response body, not just the status.** This returns 202 whether or not work was enqueued; `status: SKIPPED` with the pre-existing `extraction_job_id` means the guard considered a job already in flight and nothing was queued.\n\n`force=true` bypasses that guard outright — for a document an operator knows is dead but which has not yet aged out. Safe under concurrency: the extract task's execution claim makes a second dispatch skip rather than double-extract.","operationId":"retry_extraction_endpoint_internal_api_document__document_id__retry_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Document ID to retry extraction for","title":"Document Id"},"description":"Document ID to retry extraction for"},{"name":"force","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass the in-flight guard and always create a new job. Use when a document is stuck behind a job whose worker died and the normal retry returns SKIPPED.","default":false,"title":"Force"},"description":"Bypass the in-flight guard and always create a new job. Use when a document is stuck behind a job whose worker died and the normal retry returns SKIPPED."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentExtractionRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReextractWithDocumentTypeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/document/attribute/{attribute_id}":{"patch":{"tags":["DOCUMENT"],"summary":"Edit extracted attribute value","description":"Edit an extracted attribute value with datatype validation and audit tracking. The endpoint validates the new value against the attribute's datatype (if provided) and creates an audit record for the change. Version is incremented when the value or supported_attribute_id changes. Both new_value and supported_attribute_id are optional, but at least one must be provided. Optionally, provide supported_attribute_id to update the attribute mapping in the tenant_client_extracted_attributes table.","operationId":"edit_extracted_attribute_internal_api_document_attribute__attribute_id__patch","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"attribute_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Extracted attribute ID","title":"Attribute Id"},"description":"Extracted attribute ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttributeEditRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttributeEditResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/auth/signup":{"post":{"tags":["USERS"],"summary":"Signup","operationId":"signup_internal_api_auth_signup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserSignupRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserSignUpResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/auth/verify-email":{"post":{"tags":["USERS"],"summary":"Verify email with OTP after signup","description":"Verify the user's email with the OTP sent during signup.\n\n    The system will:\n    1. Validate the OTP\n    2. Check OTP expiration\n    3. Activate the user account\n    4. Activate trial subscription\n    5. Return access token","operationId":"verify_email_internal_api_auth_verify_email_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyEmailRequest"}}},"required":true},"responses":{"200":{"description":"Email verified successfully with access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyEmailResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/auth/send-verification-otp":{"post":{"tags":["USERS"],"summary":"Send email verification OTP","description":"Send the verification OTP to the user's email.\n\n    Use this endpoint when:\n    - User didn't receive the OTP during signup\n    - OTP has expired\n    - User needs a new verification code","operationId":"send_verification_otp_internal_api_auth_send_verification_otp_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendVerificationRequest"}}},"required":true},"responses":{"200":{"description":"Verification code sent successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendVerificationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/auth/login":{"post":{"tags":["USERS"],"summary":"Authenticate user and get access token","description":"Authenticate a user and return an access token.\n\n    The system will:\n    1. Validate credentials\n    2. Generate JWT token\n    3. Return user details and token","operationId":"login_internal_api_auth_login_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserLoginRequest"}}},"required":true},"responses":{"200":{"description":"User authenticated successfully with access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserLoginResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/auth/v2/signup":{"post":{"tags":["USERS"],"summary":"Sign up user with email verification (V2)","description":"Create a new user account with email verification requirement.\n\n    The system will:\n    1. Validate input and create user\n    2. Create tenant for the user\n    3. Send verification OTP to email\n    4. Return user details (no access token yet)\n\n    User must verify email with OTP before accessing the account.","operationId":"signup_with_verification_internal_api_auth_v2_signup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserSignupRequest"}}},"required":true},"responses":{"201":{"description":"User created - verification required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserSignUpResponseV2"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/auth/v2/login":{"post":{"tags":["USERS"],"summary":"Authenticate user with email verification check (V2)","description":"Authenticate a user with email verification requirement.\n\n    The system will:\n    1. Validate credentials\n    2. Check if email is verified\n    3. Generate JWT token if verified\n    4. Return user details and token\n\n    Returns 403 error if email is not verified.","operationId":"login_with_verification_internal_api_auth_v2_login_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserLoginRequest"}}},"required":true},"responses":{"200":{"description":"User authenticated successfully with access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserLoginResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/auth/forgot-password":{"post":{"tags":["USERS"],"summary":"Request password reset OTP","description":"Initiate the password reset process by sending an OTP to the user's email.\n\n    The system will:\n    1. Validate the email address\n    2. Generate a secure OTP\n    3. Send the OTP via email\n    4. Return a success message (regardless of email existence)","operationId":"forgot_password_internal_api_auth_forgot_password_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForgotPasswordRequest"}}},"required":true},"responses":{"200":{"description":"If the email exists, an OTP will be sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForgotPasswordResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/auth/verify-otp":{"post":{"tags":["USERS"],"summary":"Verify password reset OTP","description":"Verify the OTP sent to the user's email and get a temporary token for password reset.\n\n    The system will:\n    1. Validate the OTP\n    2. Check OTP expiration\n    3. Return a temporary token for password reset","operationId":"verify_otp_internal_api_auth_verify_otp_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyOTPRequest"}}},"required":true},"responses":{"200":{"description":"OTP verification status with temporary token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyOTPResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/auth/reset-password":{"post":{"tags":["USERS"],"summary":"Reset user password","description":"Reset the user's password using a temporary token.\n\n    The system will:\n    1. Validate the temporary token\n    2. Update the user's password\n    3. Invalidate the token","operationId":"reset_password_internal_api_auth_reset_password_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetPasswordRequest"}}},"required":true},"responses":{"200":{"description":"Password has been reset successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetPasswordResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/research/chat":{"post":{"tags":["TAX RESEARCH CHAT"],"summary":"Process a tax research query","description":"Handle a tax research query from the user and return the updated conversation ID.\n\nThis endpoint is specific to tax research conversations and handles:\n- Processing tax-related queries\n- Creating new tax research conversations\n- Adding messages to existing tax research conversations\n- Generating AI responses for tax questions\n\nNote: For listing conversations or getting conversation details,\nuse the generic chat endpoints:\n- GET /chat/conversations?conversation_type=TAX_RESEARCH\n- GET /chat/conversations/{conversation_id}","operationId":"research_chat_internal_api_research_chat_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchChatRequest"}}},"required":true},"responses":{"201":{"description":"Response containing the conversation ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchChatResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"CustomOAuth2PasswordBearer":[]}]}},"/internal/api/chat/conversations":{"get":{"tags":["CHAT"],"summary":"Get paginated list of conversations","description":"Retrieve conversations with message previews, pagination, and sorting support across all types.","operationId":"get_conversations_internal_api_chat_conversations_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (1-based)","default":1,"title":"Page"},"description":"Page number (1-based)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of conversations per page","default":20,"title":"Limit"},"description":"Number of conversations per page"},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","description":"Sort field: updated_at, created_at","default":"updated_at","title":"Sort By"},"description":"Sort field: updated_at, created_at"},{"name":"order","in":"query","required":false,"schema":{"type":"string","description":"Sort order: asc, desc","default":"desc","title":"Order"},"description":"Sort order: asc, desc"},{"name":"conversation_type","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ConversationType","description":"Filter by conversation type","default":"TAX_RESEARCH"},"description":"Filter by conversation type"},{"name":"is_bookmarked","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by bookmark: true/false/omit=all","title":"Is Bookmarked"},"description":"Filter by bookmark: true/false/omit=all"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/chat/conversations/{conversation_id}":{"get":{"tags":["CHAT"],"summary":"Get conversation metadata","description":"Retrieve core conversation metadata (no messages or previews). Use /conversations for previews, /{id}/messages for full messages.","operationId":"get_conversation_metadata_internal_api_chat_conversations__conversation_id__get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The conversation ID","title":"Conversation Id"},"description":"The conversation ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationMetadataResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/chat/conversations/{conversation_id}/bookmark":{"post":{"tags":["CHAT"],"summary":"Bookmark or unbookmark a conversation","description":"Toggle bookmark status for a conversation. Users can bookmark important conversations for future reference or unbookmark previously bookmarked conversations.","operationId":"bookmark_conversation_internal_api_chat_conversations__conversation_id__bookmark_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Conversation Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationBookmarkRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationBookmarkResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/chat/conversations/{conversation_id}/messages":{"get":{"tags":["CHAT"],"summary":"Get conversation messages","description":"Retrieve paginated messages for a specific conversation.","operationId":"get_conversation_messages_internal_api_chat_conversations__conversation_id__messages_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The conversation ID","title":"Conversation Id"},"description":"The conversation ID"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number for messages (1-based)","default":1,"title":"Page"},"description":"Page number for messages (1-based)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of messages per page","default":50,"title":"Limit"},"description":"Number of messages per page"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationMessagesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/chat/conversation/message/{message_id}/rate":{"post":{"tags":["MESSAGE"],"summary":"Rate a chat message","description":"Submit a rating (UP/DOWN) with optional comment for a system message. Users can update their existing ratings.","operationId":"rate_message_internal_api_chat_conversation_message__message_id__rate_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"message_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Message Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageRatingRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageRatingResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/chat/conversation/message/{message_id}":{"get":{"tags":["MESSAGE"],"summary":"Get message details with conversation context","description":"Retrieve detailed information about a specific message including conversation context.","operationId":"get_message_details_internal_api_chat_conversation_message__message_id__get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"message_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The message ID","title":"Message Id"},"description":"The message ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDetailResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/states":{"get":{"tags":["CLIENT"],"summary":"Get US States","description":"Retrieve all US states.","operationId":"get_states_internal_api_clients_states_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatesResponse"}}}}},"security":[{"CustomOAuth2PasswordBearer":[]}]}},"/internal/api/clients/state/cities":{"get":{"tags":["CLIENT"],"summary":"Get Cities by States","description":"Retrieve all cities for a specific state using the state's two-letter code with pagination, sorting, and search capabilities.","operationId":"get_cities_by_state_internal_api_clients_state_cities_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"state_code","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":2,"description":"2 letter state code","title":"State Code"},"description":"2 letter state code"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (1-based)","default":1,"title":"Page"},"description":"Page number (1-based)"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":2000,"minimum":1,"description":"Number of items per page (max 2000)","default":20,"title":"Page Size"},"description":"Number of items per page (max 2000)"},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Field to sort by (name only)","default":"name","title":"Sort By"},"description":"Field to sort by (name only)"},{"name":"sort_order","in":"query","required":false,"schema":{"$ref":"#/components/schemas/SortOrder","description":"Sort order","default":"asc"},"description":"Sort order"},{"name":"search_query","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search term","title":"Search Query"},"description":"Search term"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitiesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_identifier}/addresses":{"get":{"tags":["CLIENT"],"summary":"Get Client Addresses","description":"Retrieve primary and mailing addresses for a specific client.","operationId":"get_client_addresses_internal_api_clients__client_identifier__addresses_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientAddressesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["CLIENT"],"summary":"Update Client Addresses","description":"Set or update primary and mailing addresses for a client.","operationId":"update_client_addresses_internal_api_clients__client_identifier__addresses_put","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientAddressesUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientAddressesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_identifier}/spouse":{"get":{"tags":["CLIENT"],"summary":"Get Client Spouse","description":"Retrieve spouse information for a specific client.","operationId":"get_spouse_internal_api_clients__client_identifier__spouse_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/SpouseResponse"},{"type":"null"}],"title":"Response Get Spouse Internal Api Clients  Client Identifier  Spouse Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["CLIENT"],"summary":"Create Spouse","description":"Create a new spouse for a client. Returns 400 Bad Request if spouse already exists.","operationId":"create_spouse_internal_api_clients__client_identifier__spouse_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpouseCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpouseResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["CLIENT"],"summary":"Create or Update Spouse","description":"Create a new spouse or update existing spouse for a client. For updates, only provided fields will be updated (partial update behavior).","operationId":"create_or_update_spouse_internal_api_clients__client_identifier__spouse_put","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpouseUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpouseResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_identifier}/dependents":{"get":{"tags":["CLIENT"],"summary":"List Client Dependents","description":"Retrieve all dependents for a specific client.","operationId":"list_dependents_internal_api_clients__client_identifier__dependents_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DependentListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["CLIENT"],"summary":"Create New Dependent","description":"Create a new dependent for a client.","operationId":"create_dependent_internal_api_clients__client_identifier__dependents_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DependentCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DependentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_identifier}/dependents/{dependent_id}":{"get":{"tags":["CLIENT"],"summary":"Get Specific Dependent","description":"Retrieve a specific dependent by ID.","operationId":"get_dependent_internal_api_clients__client_identifier__dependents__dependent_id__get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}},{"name":"dependent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Dependent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DependentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["CLIENT"],"summary":"Update Dependent","description":"Update an existing dependent's information.","operationId":"update_dependent_internal_api_clients__client_identifier__dependents__dependent_id__patch","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}},{"name":"dependent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Dependent Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DependentUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DependentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["CLIENT"],"summary":"Delete Dependent","description":"Delete a dependent.","operationId":"delete_dependent_internal_api_clients__client_identifier__dependents__dependent_id__delete","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}},{"name":"dependent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Dependent Id"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/ssn/unmask":{"post":{"tags":["CLIENT"],"summary":"Unmask SSN (Unified)","description":"Decrypt and return the unmasked SSN for any entity type (CLIENT, SPOUSE, or DEPENDENT). Single endpoint for all SSN unmask operations.","operationId":"unmask_ssn_internal_api_clients_ssn_unmask_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SSNUnmaskRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SSNUnmaskResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"CustomOAuth2PasswordBearer":[]}]}},"/internal/api/clients/{client_identifier}/previous-year-return":{"get":{"tags":["CLIENT"],"summary":"Prior-year return state for a client and tax year","description":"The current prior-year-return analysis run for a client and tax year: which file it read, how it ended, and whether a new one may be started. Client-scoped rather than intake-request-scoped, so every surface where a CPA discovers a problem can render and act on it.","operationId":"get_previous_year_return_state_internal_api_clients__client_identifier__previous_year_return_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","description":"Engagement tax year","title":"Tax Year"},"description":"Engagement tax year"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviousYearReturnStateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_identifier}/previous-year-return/impact":{"get":{"tags":["CLIENT"],"summary":"What replacing this prior-year return would do","description":"The ledger a CPA reads before confirming a replace: how many answers would be re-read, which entities, which figures may not come back, and what is kept. Read-only — computing it changes nothing.","operationId":"get_previous_year_return_impact_internal_api_clients__client_identifier__previous_year_return_impact_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","description":"Engagement tax year","title":"Tax Year"},"description":"Engagement tax year"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImpactPreviewResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_identifier}/previous-year-return/replace":{"post":{"tags":["CLIENT"],"summary":"Replace the prior-year return and re-analyse it","description":"Retracts the answers the current analysis wrote, keeps everything a human touched, records what could not be resolved, and re-runs the analysis. Phase 2 re-runs the SAME file — replacing with a different file arrives with the pre-flight gate.","operationId":"replace_previous_year_return_internal_api_clients__client_identifier__previous_year_return_replace_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","description":"Engagement tax year","title":"Tax Year"},"description":"Engagement tax year"}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ReplacePreviousYearReturnRequest"},{"type":"null"}],"title":"Payload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplacePreviousYearReturnResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_identifier}/previous-year-return/replace-file":{"post":{"tags":["CLIENT"],"summary":"Replace the prior-year return with a different file","description":"Files the new return as the next version of the one on record, retracts the answers the old file produced, and re-analyses the new file. The checklist derived from the old file is KEPT unless `retire_checklist` asks otherwise; the re-analysis adds to it rather than duplicating it. The old file is superseded, never deleted.","operationId":"replace_previous_year_return_with_file_internal_api_clients__client_identifier__previous_year_return_replace_file_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","description":"Engagement tax year","title":"Tax Year"},"description":"Engagement tax year"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_replace_previous_year_return_with_file_internal_api_clients__client_identifier__previous_year_return_replace_file_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplacePreviousYearReturnResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_identifier}/previous-year-return/facts":{"get":{"tags":["CLIENT"],"summary":"What the analysis has found so far","description":"The run's findings in the order it found them, from a cursor. Readable WHILE the analysis is running — the answers themselves are written in one transaction and are invisible until it commits, so a feed derived from them would show nothing for fifteen minutes and then everything.","operationId":"get_previous_year_return_facts_internal_api_clients__client_identifier__previous_year_return_facts_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","description":"Engagement tax year","title":"Tax Year"},"description":"Engagement tax year"},{"name":"after_seq","in":"query","required":false,"schema":{"type":"integer","description":"The last sequence already held. The panel appends what comes back rather than re-rendering, which is what makes the feed read as something happening rather than a list refreshing.","default":0,"title":"After Seq"},"description":"The last sequence already held. The panel appends what comes back rather than re-rendering, which is what makes the feed read as something happening rather than a list refreshing."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PyrFactFeedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_identifier}/previous-year-return/facts/{seq}/confirm":{"post":{"tags":["CLIENT"],"summary":"Take responsibility for one thing the analysis read","description":"Marks a single finding as checked by a human. The panel's review queue lists what the extraction was unsure of — a figure it read with low confidence, an answer it guessed at, a refusal — and this is how a CPA clears one. The queue's counter is derived from these, so a confirmation survives a reload and is visible to the next person who opens the client-year.","operationId":"confirm_previous_year_return_fact_internal_api_clients__client_identifier__previous_year_return_facts__seq__confirm_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}},{"name":"seq","in":"path","required":true,"schema":{"type":"integer","title":"Seq"}},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","description":"Engagement tax year","title":"Tax Year"},"description":"Engagement tax year"}],"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PyrFactResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_identifier}/previous-year-return/history":{"get":{"tags":["CLIENT"],"summary":"What has happened to this prior-year return","description":"Every replace on this client-year, newest first: who did it, when, why, and how much it moved. A replace cannot be undone — the answers are gone the moment the retract commits — so this is the only record of what a given replace cleared.","operationId":"get_previous_year_return_history_internal_api_clients__client_identifier__previous_year_return_history_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","description":"Engagement tax year","title":"Tax Year"},"description":"Engagement tax year"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplaceHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_identifier}/year-over-year":{"get":{"tags":["CLIENT"],"summary":"Year-over-year headline comparison","description":"This year against the prior year, line by line, in the 1040's own order. The same digest the assistant narrates, so the two can never disagree.","operationId":"get_year_over_year_internal_api_clients__client_identifier__year_over_year_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","description":"The engagement year being prepared","title":"Tax Year"},"description":"The engagement year being prepared"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YoyDigestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_identifier}/year-over-year/overrides":{"post":{"tags":["CLIENT"],"summary":"Correct one prior-year figure","description":"Corrects the firm's READ of a filed return — not the return, which is a historical fact, and not the extraction, which stays on record as what the machine saw. Returns the recomputed comparison so the caller never has to patch a row itself.","operationId":"create_figure_override_internal_api_clients__client_identifier__year_over_year_overrides_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","description":"The engagement year being prepared","title":"Tax Year"},"description":"The engagement year being prepared"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFigureOverrideRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FigureOverrideResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["CLIENT"],"summary":"Every correction made to this client-year's prior figures","description":"Newest first, superseded and withdrawn rows included — 'somebody corrected this twice, and here is what they said the first time' is what a reviewer asks, and a live-only read cannot answer it.","operationId":"list_figure_overrides_internal_api_clients__client_identifier__year_over_year_overrides_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","description":"The engagement year being prepared","title":"Tax Year"},"description":"The engagement year being prepared"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FigureOverrideListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_identifier}/year-over-year/overrides/{override_id}":{"delete":{"tags":["CLIENT"],"summary":"Withdraw a correction","description":"Falls the line back to what the extraction read. The row stays on the record as something that was done and then undone.","operationId":"delete_figure_override_internal_api_clients__client_identifier__year_over_year_overrides__override_id__delete","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}},{"name":"override_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Override Id"}},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","description":"The engagement year being prepared","title":"Tax Year"},"description":"The engagement year being prepared"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FigureOverrideResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/intake-requests":{"post":{"tags":["CLIENT","Intake Requests"],"summary":"Create Intake Request","description":"Create a new intake request for a client. Generates a secure link and optionally sends email notification.","operationId":"create_document_upload_request_internal_api_clients__client_id__intake_requests_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUploadRequestCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUploadRequestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["CLIENT","Intake Requests"],"summary":"List Intake Requests","description":"List all intake requests for a client with optional status filtering.","operationId":"list_document_upload_requests_internal_api_clients__client_id__intake_requests_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"status_filter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status Filter"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DocumentUploadRequestSummaryResponse"},"title":"Response List Document Upload Requests Internal Api Clients  Client Id  Intake Requests Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/intake-requests/client-link":{"get":{"tags":["CLIENT","Intake Requests"],"summary":"Get Client Link","description":"Get the latest active client upload link for copying. Returns the upload URL and expiration information.","operationId":"get_client_link_internal_api_clients__client_id__intake_requests_client_link_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientLinkResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/intake-requests/{request_id}/save-and-send":{"post":{"tags":["CLIENT","Intake Requests"],"summary":"Save and Send","description":"If DRAFT: set status to EMAIL_SENT, move items to PENDING, and send the client upload link email. If already EMAIL_SENT/ACTIVE/COMPLETED: move any DRAFT items to PENDING and resend the email. Uses recipient_email from the intake request or client profile. No body required.","operationId":"save_and_send_internal_api_clients__client_id__intake_requests__request_id__save_and_send_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Request Id"}},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveAndSendRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveAndSendResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/intake-requests/resend-client-link":{"post":{"tags":["CLIENT","Intake Requests"],"summary":"Resend Client Link","description":"Resend the latest active client upload link email to the recipient. Sends the same email notification that was sent when the request was created. No request body.","operationId":"resend_client_link_internal_api_clients__client_id__intake_requests_resend_client_link_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendClientLinkResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/intake-requests/details":{"get":{"tags":["CLIENT","Intake Requests"],"summary":"Get Intake Request Details by Client","description":"Get the latest intake request details for a client for the given tax year. Returns full request details including tax_year. Returns 404 if no intake request exists.","operationId":"get_intake_request_details_for_client_internal_api_clients__client_id__intake_requests_details_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"tax_year","in":"query","required":true,"schema":{"type":"string","description":"Tax year for the intake request (e.g. 2024).","title":"Tax Year"},"description":"Tax year for the intake request (e.g. 2024)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUploadRequestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/intake-requests/{request_id}":{"get":{"tags":["CLIENT","Intake Requests"],"summary":"Get Intake Request","description":"Get detailed information about a specific intake request including items and status.","operationId":"get_document_upload_request_internal_api_clients__client_id__intake_requests__request_id__get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Request Id"}},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUploadRequestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["CLIENT","Intake Requests"],"summary":"Update Intake Request","description":"Update an intake request (revoke or extend expiration).","operationId":"update_document_upload_request_internal_api_clients__client_id__intake_requests__request_id__patch","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Request Id"}},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUploadRequestUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUploadRequestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/intake-requests/{request_id}/items":{"post":{"tags":["CLIENT","Intake Requests"],"summary":"Add Items to Intake Request","description":"Add document types/items to an existing intake request. Allowed for DRAFT, EMAIL_SENT, ACTIVE, or COMPLETED requests. Not allowed for EXPIRED or REVOKED.","operationId":"add_items_to_intake_request_internal_api_clients__client_id__intake_requests__request_id__items_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Request Id"}},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddItemsToIntakeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUploadRequestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/intake-requests/{request_id}/items/{item_id}":{"patch":{"tags":["CLIENT","Intake Requests"],"summary":"Update Intake Request Item (Document Type, Notes, Tags, Description)","description":"Partially update an intake request item. Only provided fields (document_type, notes, tags, description) are updated. Use for CPA to add or update.","operationId":"patch_intake_request_item_internal_api_clients__client_id__intake_requests__request_id__items__item_id__patch","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Request Id"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeRequestItemPatch"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUploadRequestItemResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["CLIENT","Intake Requests"],"summary":"Delete Intake Request Item","description":"Delete an intake request item. Allowed while the request is not completed (DRAFT, EMAIL_SENT, or ACTIVE). Not allowed for COMPLETED, EXPIRED, or REVOKED. Updates total_items and completed_items on the request.","operationId":"delete_intake_request_item_internal_api_clients__client_id__intake_requests__request_id__items__item_id__delete","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Request Id"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/intake-requests/{request_id}/upload":{"post":{"tags":["CLIENT","Intake Requests"],"summary":"Upload Document for Intake Request Item","description":"Upload a document for a specific intake request item (CPA dashboard). Allows CPAs to upload documents on behalf of clients.","operationId":"upload_document_for_intake_request_internal_api_clients__client_id__intake_requests__request_id__upload_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Request Id"}},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_document_for_intake_request_internal_api_clients__client_id__intake_requests__request_id__upload_post"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUploadResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/intake-requests/{request_id}/match-suggestions":{"get":{"tags":["CLIENT","Intake Requests"],"summary":"Get Match Suggestions (Internal)","description":"Get pending match suggestions for 'other' uploads that match pending targeted items. Requires JWT (Bearer). Path: GET /internal/api/clients/{client_id}/intake-requests/{request_id}/match-suggestions","operationId":"get_match_suggestions_internal_api_clients__client_id__intake_requests__request_id__match_suggestions_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Request Id"}},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MatchSuggestionResponse"},"title":"Response Get Match Suggestions Internal Api Clients  Client Id  Intake Requests  Request Id  Match Suggestions Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/intake-requests/{request_id}/confirm-match":{"post":{"tags":["CLIENT","Intake Requests"],"summary":"Confirm Match Suggestion (Internal)","description":"Confirm a match suggestion and move the upload from 'other' item to the matched targeted item. Requires JWT (Bearer) authentication. Path: POST /internal/api/clients/{client_id}/intake-requests/{request_id}/confirm-match","operationId":"confirm_match_internal_api_clients__client_id__intake_requests__request_id__confirm_match_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Request Id"}},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmMatchRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmMatchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/intake-requests/{request_id}/target-folder":{"patch":{"tags":["CLIENT","Intake Requests"],"summary":"Update Intake Request Target Folder","description":"Update where future uploads for this intake request are stored. Existing uploads are unchanged.","operationId":"update_intake_request_target_folder_internal_api_clients__client_id__intake_requests__request_id__target_folder_patch","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Request Id"}},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeRequestTargetFolderUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUploadRequestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/questionnaire/responses":{"post":{"tags":["CLIENT","Questionnaire V2","Questionnaire V2","Responses"],"summary":"Save Questionnaire Responses","description":"Save or update questionnaire responses. Automatically maps responses to questions and handles validation.","operationId":"save_responses_internal_api_clients__client_id__questionnaire_responses_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","maximum":2100,"minimum":1900,"description":"Tax year (1900-2100)","title":"Tax Year"},"description":"Tax year (1900-2100)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuestionnaireResponseBatchCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/questionnaire/questions-with-responses":{"get":{"tags":["CLIENT","Questionnaire"],"summary":"Get Questions with Responses (via tax-engine)","description":"Get questionnaire questions with responses in recursive structure via tax-engine.","operationId":"get_questions_with_responses_proxy_internal_api_clients__client_id__questionnaire_questions_with_responses_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","maximum":2100,"minimum":1900,"description":"Tax year (1900-2100)","title":"Tax Year"},"description":"Tax year (1900-2100)"},{"name":"phase_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional phase code filter","title":"Phase Code"},"description":"Optional phase code filter"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/questionnaire/responses/bulk":{"get":{"tags":["CLIENT","Questionnaire V2","Questionnaire V2","Responses"],"summary":"Get All Responses (Bulk)","description":"Get questionnaire responses as a flat map with type information. Optimized for frontend to evaluate show_if_expression locally. Optionally filter by question codes or phase code.","operationId":"get_responses_bulk_internal_api_clients__client_id__questionnaire_responses_bulk_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","maximum":2100,"minimum":1900,"description":"Tax year (1900-2100)","title":"Tax Year"},"description":"Tax year (1900-2100)"},{"name":"question_codes","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Optional list of question codes to filter. Can be repeated: ?question_codes=CODE1&question_codes=CODE2","title":"Question Codes"},"description":"Optional list of question codes to filter. Can be repeated: ?question_codes=CODE1&question_codes=CODE2"},{"name":"phase_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional phase code filter","title":"Phase Code"},"description":"Optional phase code filter"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/questionnaire/responses/instances":{"post":{"tags":["CLIENT","Questionnaire"],"summary":"Create Question Instance (via tax-engine)","description":"Create a new instance for a repeatable question group by proxying to tax-engine. Use this to create instances #2, #3, etc. Instance #1 is created automatically when the repeatable group question is answered positively.","operationId":"create_instance_proxy_internal_api_clients__client_id__questionnaire_responses_instances_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","maximum":2100,"minimum":1900,"description":"Tax year (1900-2100)","title":"Tax Year"},"description":"Tax year (1900-2100)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"Body"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/questionnaire/responses/instances/{instance_id}":{"delete":{"tags":["CLIENT","Questionnaire"],"summary":"Delete Question Instance (via tax-engine)","description":"Delete a questionnaire instance and its entire subtree -- nested child instances and every bound response -- by proxying to tax-engine. Addressed by instance UUID: instance numbers are sparse (delete leaves gaps), reused (create is max+1 over survivors), and cannot identify a nested instance at all. Every instance is deletable, including the first and the last; a group with zero instances is a valid state.","operationId":"delete_instance_proxy_internal_api_clients__client_id__questionnaire_responses_instances__instance_id__delete","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Instance ID to delete","title":"Instance Id"},"description":"Instance ID to delete"},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","maximum":2100,"minimum":1900,"description":"Tax year (1900-2100)","title":"Tax Year"},"description":"Tax year (1900-2100)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/questionnaire/phases":{"get":{"tags":["CLIENT","Questionnaire V2","Questionnaire V2","Phases"],"summary":"Get Questionnaire Phases","description":"Get all questionnaire phases with optional filtering. Phases are system-wide static data used to organize questions. Authentication is required.","operationId":"get_phases_internal_api_clients__client_id__questionnaire_phases_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"is_active","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Optional active status filter","title":"Is Active"},"description":"Optional active status filter"},{"name":"phase_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional phase type filter","title":"Phase Type"},"description":"Optional phase type filter"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/questionnaire/questions/with-responses":{"get":{"tags":["CLIENT","Questionnaire V2","Questionnaire V2","Questions"],"summary":"Get Questions with Responses","description":"Get questionnaire questions with responses in recursive structure. Everything is a question. Questions can have child_questions. Groups contain instances, instances contain fields.","operationId":"get_questions_with_responses_internal_api_clients__client_id__questionnaire_questions_with_responses_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","maximum":2100,"minimum":1900,"description":"Tax year (1900-2100)","title":"Tax Year"},"description":"Tax year (1900-2100)"},{"name":"phase_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional phase code filter","title":"Phase Code"},"description":"Optional phase code filter"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/folders/contents":{"get":{"tags":["CLIENT","Client Document Management","DMS Folders"],"summary":"Get folder contents","description":"Get folders and documents in a specific folder or root level (folders first, then documents) with extraction and workflow status","operationId":"get_folder_contents_internal_api_clients__client_id__dms_folders_contents_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"folder_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Folder ID (empty/null for root level)","title":"Folder Id"},"description":"Folder ID (empty/null for root level)"},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","description":"Sort field (name, created_at, updated_at, type)","default":"type","title":"Sort By"},"description":"Sort field (name, created_at, updated_at, type)"},{"name":"sort_order","in":"query","required":false,"schema":{"type":"string","description":"Sort order (asc, desc)","default":"asc","title":"Sort Order"},"description":"Sort order (asc, desc)"},{"name":"tax_year","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter by tax year (multiple values allowed)","title":"Tax Year"},"description":"Filter by tax year (multiple values allowed)"},{"name":"doc_year","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter by document year (multiple values allowed)","title":"Doc Year"},"description":"Filter by document year (multiple values allowed)"},{"name":"extraction","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by extraction status (true=only documents that have been processed)","title":"Extraction"},"description":"Filter by extraction status (true=only documents that have been processed)"},{"name":"doc_type","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter by legacy document type (e.g. W2, FORM_1099_INT)","title":"Doc Type"},"description":"Filter by legacy document type (e.g. W2, FORM_1099_INT)"},{"name":"document_type_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid"}},{"type":"null"}],"description":"Filter by canonical document_type_id (the new source-of-truth column; matches reclassified documents correctly where the legacy doc_type would not)","title":"Document Type Id"},"description":"Filter by canonical document_type_id (the new source-of-truth column; matches reclassified documents correctly where the legacy doc_type would not)"},{"name":"extraction_status","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter by extraction status (e.g. COMPLETED, FAILED, IN_PROGRESS)","title":"Extraction Status"},"description":"Filter by extraction status (e.g. COMPLETED, FAILED, IN_PROGRESS)"},{"name":"workflow_status","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter by workflow status (e.g. APPROVED, CREATED, IN_PROGRESS)","title":"Workflow Status"},"description":"Filter by workflow status (e.g. APPROVED, CREATED, IN_PROGRESS)"},{"name":"needs_attention","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"When true, return only items needing CPA action: failed/unsupported documents and multi-form bundles whose rollup is ACTION_NEEDED or ALL_FAILED (with their children).","title":"Needs Attention"},"description":"When true, return only items needing CPA action: failed/unsupported documents and multi-form bundles whose rollup is ACTION_NEEDED or ALL_FAILED (with their children)."},{"name":"folderview","in":"query","required":false,"schema":{"type":"boolean","description":"Include folders in response (false=flat list of documents only)","default":true,"title":"Folderview"},"description":"Include folders in response (false=flat list of documents only)"},{"name":"query","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search term to filter folders and documents by name, description, or filename","title":"Query"},"description":"Search term to filter folders and documents by name, description, or filename"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (1-based)","default":1,"title":"Page"},"description":"Page number (1-based)"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page","default":50,"title":"Page Size"},"description":"Number of items per page"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderContentsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/folders":{"post":{"tags":["CLIENT","Client Document Management","DMS Folders"],"summary":"Create folder","description":"Create a new folder","operationId":"create_folder_internal_api_clients__client_id__dms_folders_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/folders/{folder_id}":{"get":{"tags":["CLIENT","Client Document Management","DMS Folders"],"summary":"Get folder details","description":"Get detailed information about a specific folder","operationId":"get_folder_details_internal_api_clients__client_id__dms_folders__folder_id__get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"folder_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Folder ID (must be valid UUID)","title":"Folder Id"},"description":"Folder ID (must be valid UUID)"},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["CLIENT","Client Document Management","DMS Folders"],"summary":"Update folder","description":"Update folder information (full update)","operationId":"update_folder_internal_api_clients__client_id__dms_folders__folder_id__put","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"folder_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Folder Id"}},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["CLIENT","Client Document Management","DMS Folders"],"summary":"Partially update folder","description":"Partially update folder information (only provided fields)","operationId":"patch_folder_internal_api_clients__client_id__dms_folders__folder_id__patch","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"folder_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Folder Id"}},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["CLIENT","Client Document Management","DMS Folders"],"summary":"Delete folder","description":"Delete a folder (soft delete)","operationId":"delete_folder_internal_api_clients__client_id__dms_folders__folder_id__delete","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"folder_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Folder Id"}},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"reason","in":"query","required":true,"schema":{"type":"string","description":"Reason for deletion","title":"Reason"},"description":"Reason for deletion"},{"name":"cascade_delete","in":"query","required":false,"schema":{"type":"boolean","description":"Delete all contents","default":true,"title":"Cascade Delete"},"description":"Delete all contents"}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/folders/bulk-delete":{"post":{"tags":["CLIENT","Client Document Management","DMS Folders"],"summary":"Bulk delete multiple folders","description":"Delete multiple folders in a single operation with optional cascade deletion.\n\n    **Features:**\n    - Delete up to multiple folders at once\n    - Optional cascade deletion to remove all nested contents (subfolders and documents)\n    - Atomic operation with rollback on failure\n    - Detailed error reporting for each failed deletion\n\n    **Request:**\n    - `folder_ids`: List of folder UUIDs to delete\n    - `reason`: Reason for deletion (required for audit trail)\n    - `cascade_delete`: If true, deletes all contents recursively; if false, only deletes empty folders\n\n    **Response:**\n    - `success_count`: Number of successfully deleted folders\n    - `failure_count`: Number of folders that failed to delete\n    - `total_count`: Total number of folders in the request\n    - `errors`: List of error details for failed deletions (folder_id and error message)\n    - `details`: Additional metadata about the operation\n\n    **Notes:**\n    - Non-empty folders will fail to delete unless `cascade_delete=true`\n    - All deletions are soft deletes (can be recovered)\n    - Operation is performed within a database transaction","operationId":"bulk_delete_folders_internal_api_clients__client_id__dms_folders_bulk_delete_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkFolderDeleteRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkOperationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/folders/bulk-mixed-delete":{"post":{"tags":["CLIENT","Client Document Management","DMS Folders"],"summary":"Bulk delete folders and documents (mixed)","description":"Delete both folders and documents in a single atomic operation.\n\n    **Features:**\n    - Delete multiple folders and documents simultaneously\n    - Mixed selection support (folders + documents in one request)\n    - Automatic cascade deletion for folder contents\n    - Atomic operation with rollback on critical failures\n    - Comprehensive error reporting per item\n\n    **Request:**\n    - `folder_ids`: List of folder UUIDs to delete (optional)\n    - `document_ids`: List of document UUIDs to delete (optional)\n    - `reason`: Reason for deletion (required for audit trail)\n    - `cascade_delete`: If true, deletes all folder contents recursively (applies to folders only)\n\n    **Response:**\n    - `success_count`: Number of successfully deleted items (folders + documents)\n    - `failure_count`: Number of items that failed to delete\n    - `total_count`: Total number of items in the request\n    - `errors`: List of error details for failed deletions with item_id, item_type (folder/document), and error message\n    - `details`: Breakdown of folders vs documents deleted/failed\n\n    **Use Cases:**\n    - Delete selected items from folder contents view\n    - Clean up multiple items across different locations\n    - Batch delete operations from search results\n\n    **Notes:**\n    - At least one of `folder_ids` or `document_ids` must be provided\n    - Folders are processed before documents\n    - Non-empty folders will fail unless `cascade_delete=true`\n    - All deletions are soft deletes (can be recovered)\n    - Partial success is possible (some items deleted, others failed)","operationId":"bulk_mixed_delete_internal_api_clients__client_id__dms_folders_bulk_mixed_delete_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkMixedDeleteRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkOperationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/documents/upload":{"post":{"tags":["CLIENT","Client Document Management","DMS Documents"],"summary":"Upload Document","description":"Upload a document securely to the DMS with metadata and folder organization. Returns document info with download URL.","operationId":"upload_document_internal_api_clients__client_id__dms_documents_upload_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_document_internal_api_clients__client_id__dms_documents_upload_post"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/documents/{document_id}":{"get":{"tags":["CLIENT","Client Document Management","DMS Documents"],"summary":"Get document details","description":"Get detailed information about a specific document including extraction and workflow status","operationId":"get_document_details_internal_api_clients__client_id__dms_documents__document_id__get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Document ID","title":"Document Id"},"description":"Document ID"},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["CLIENT","Client Document Management","DMS Documents"],"summary":"Update document","description":"Update document information (full update)","operationId":"update_document_internal_api_clients__client_id__dms_documents__document_id__put","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Document Id"}},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["CLIENT","Client Document Management","DMS Documents"],"summary":"Partially update document","description":"Partially update document information (only provided fields)","operationId":"partially_update_document_internal_api_clients__client_id__dms_documents__document_id__patch","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Document Id"}},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["CLIENT","Client Document Management","DMS Documents"],"summary":"Delete document","description":"Delete a document (soft delete)","operationId":"delete_document_internal_api_clients__client_id__dms_documents__document_id__delete","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Document ID","title":"Document Id"},"description":"Document ID"},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"reason","in":"query","required":true,"schema":{"type":"string","description":"Reason for deletion","title":"Reason"},"description":"Reason for deletion"}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/documents/{document_id}/download":{"get":{"tags":["CLIENT","Client Document Management","DMS Documents"],"summary":"Download document","description":"Generate a secure, time-limited download URL","operationId":"download_document_internal_api_clients__client_id__dms_documents__document_id__download_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Document ID","title":"Document Id"},"description":"Document ID"},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadUrlResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/documents/{document_id}/download-proxy":{"get":{"tags":["CLIENT","Client Document Management","DMS Documents"],"summary":"Download document via proxy","description":"Download document through authenticated proxy with token validation","operationId":"download_document_proxy_internal_api_clients__client_id__dms_documents__document_id__download_proxy_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Document ID","title":"Document Id"},"description":"Document ID"},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"token","in":"query","required":true,"schema":{"type":"string","description":"Download token","title":"Token"},"description":"Download token"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/documents/bulk-move":{"post":{"tags":["CLIENT","Client Document Management","DMS Documents"],"summary":"Bulk move documents","description":"Move multiple documents to a different folder","operationId":"bulk_move_documents_internal_api_clients__client_id__dms_documents_bulk_move_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkMoveRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkOperationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/documents/bulk-delete":{"post":{"tags":["CLIENT","Client Document Management","DMS Documents"],"summary":"Bulk delete documents","description":"Delete multiple documents","operationId":"bulk_delete_documents_internal_api_clients__client_id__dms_documents_bulk_delete_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDeleteRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkOperationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/documents/{document_id}/versions":{"post":{"tags":["CLIENT","Client Document Management","DMS Documents"],"summary":"Upload New Version","description":"Upload a new version of an existing document. The new version will replace the current version and become the latest.","operationId":"upload_new_version_internal_api_clients__client_id__dms_documents__document_id__versions_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Existing document ID to replace","title":"Document Id"},"description":"Existing document ID to replace"},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_new_version_internal_api_clients__client_id__dms_documents__document_id__versions_post"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["CLIENT","Client Document Management","DMS Documents"],"summary":"Get Document Version History","description":"Get all versions of a document ordered by version number (newest first)","operationId":"get_document_versions_internal_api_clients__client_id__dms_documents__document_id__versions_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Document ID","title":"Document Id"},"description":"Document ID"},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"include_deleted","in":"query","required":false,"schema":{"type":"boolean","description":"Include deleted versions (default: false)","default":false,"title":"Include Deleted"},"description":"Include deleted versions (default: false)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentVersionListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["CLIENT","Client Document Management","DMS Documents"],"summary":"Delete All Versions","description":"Delete all versions of a document (cascade delete)","operationId":"delete_all_versions_internal_api_clients__client_id__dms_documents__document_id__versions_delete","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Document ID","title":"Document Id"},"description":"Document ID"},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"reason","in":"query","required":true,"schema":{"type":"string","description":"Reason for deletion","title":"Reason"},"description":"Reason for deletion"}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/documents/valid-document-types":{"get":{"tags":["CLIENT","Client Document Management","DMS Documents"],"summary":"Get valid document types","description":"Get list of valid document types for upload","operationId":"get_valid_document_types_endpoint_internal_api_clients__client_id__dms_documents_valid_document_types_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"type":"string"},"type":"array","title":"Response Get Valid Document Types Endpoint Internal Api Clients  Client Id  Dms Documents Valid Document Types Get"}}}}},"security":[{"CustomOAuth2PasswordBearer":[]}]}},"/internal/api/clients/{client_id}/dms/document-flags/by-document/{document_id}":{"get":{"tags":["CLIENT","Client Document Management","DMS Document Flags"],"summary":"List all cross-document flags (duplicate/superseded) on a document.","operationId":"list_document_flags_endpoint_internal_api_clients__client_id__dms_document_flags_by_document__document_id__get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Document ID","title":"Document Id"},"description":"Document ID"},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FlagResponse"},"title":"Response List Document Flags Endpoint Internal Api Clients  Client Id  Dms Document Flags By Document  Document Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/document-flags/{flag_id}/resolve":{"post":{"tags":["CLIENT","Client Document Management","DMS Document Flags"],"summary":"Resolve a flag: keep_both | keep_selected | reopen.","operationId":"resolve_document_flag_endpoint_internal_api_clients__client_id__dms_document_flags__flag_id__resolve_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"flag_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Flag ID","title":"Flag Id"},"description":"Flag ID"},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlagResolutionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlagResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/document-flags/readiness":{"get":{"tags":["CLIENT","Client Document Management","DMS Document Flags"],"summary":"\"Ready to Prepare?\" gate — role-stateful readiness for a client/tax-year.","operationId":"readiness_endpoint_internal_api_clients__client_id__dms_document_flags_readiness_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"tax_year","in":"query","required":true,"schema":{"type":"string","title":"Tax Year"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadinessResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/document-flags/evaluate-completeness":{"post":{"tags":["CLIENT","Client Document Management","DMS Document Flags"],"summary":"Run CLIENT-scoped detectors (missing-expected-document) for a client/tax-year on demand.","operationId":"evaluate_completeness_endpoint_internal_api_clients__client_id__dms_document_flags_evaluate_completeness_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"tax_year","in":"query","required":true,"schema":{"type":"string","title":"Tax Year"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluateCompletenessResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/document-flags/prior-year-delta":{"get":{"tags":["CLIENT","Client Document Management","DMS Document Flags"],"summary":"Year-over-year income-source delta (new / disappeared / matched) — account resolution.","operationId":"prior_year_delta_endpoint_internal_api_clients__client_id__dms_document_flags_prior_year_delta_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","title":"Tax Year"}},{"name":"prior_year","in":"query","required":true,"schema":{"type":"integer","title":"Prior Year"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriorYearDeltaResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/document-flags/{flag_id}":{"get":{"tags":["CLIENT","Client Document Management","DMS Document Flags"],"summary":"Fetch a single flag with its compare evidence (matched/differing fields).","operationId":"get_document_flag_endpoint_internal_api_clients__client_id__dms_document_flags__flag_id__get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"flag_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Flag ID","title":"Flag Id"},"description":"Flag ID"},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlagResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/audit":{"get":{"tags":["CLIENT","Client Document Management","DMS Audit"],"summary":"Get unified audit log","description":"Get comprehensive audit trail for all client and DMS operations with pagination and filtering","operationId":"get_unified_audit_log_internal_api_clients__client_id__dms_audit_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"action","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by action","title":"Action"},"description":"Filter by action"},{"name":"action_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by action type","title":"Action Type"},"description":"Filter by action type"},{"name":"entity_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by entity type","title":"Entity Type"},"description":"Filter by entity type"},{"name":"risk_level","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by risk level","title":"Risk Level"},"description":"Filter by risk level"},{"name":"user_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filter by user ID","title":"User Id"},"description":"Filter by user ID"},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter by start date","title":"Start Date"},"description":"Filter by start date"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter by end date","title":"End Date"},"description":"Filter by end date"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (1-based)","default":1,"title":"Page"},"description":"Page number (1-based)"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page (max 100)","default":20,"title":"Page Size"},"description":"Number of items per page (max 100)"},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ClientSortField"},{"type":"null"}],"description":"Field to sort by (created_at, name, email, readable_id)","default":"created_at","title":"Sort By"},"description":"Field to sort by (created_at, name, email, readable_id)"},{"name":"sort_order","in":"query","required":false,"schema":{"$ref":"#/components/schemas/SortOrder","description":"Sort order","default":"desc"},"description":"Sort order"},{"name":"search_query","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search term","title":"Search Query"},"description":"Search term"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditLogResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/audit/entity/{entity_type}/{entity_id}":{"get":{"tags":["CLIENT","Client Document Management","DMS Audit"],"summary":"Get entity audit trail","description":"Get audit trail for a specific entity (client, spouse, dependent, document, etc.)","operationId":"get_entity_audit_trail_internal_api_clients__client_id__dms_audit_entity__entity_type___entity_id__get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"entity_type","in":"path","required":true,"schema":{"type":"string","description":"Type of the entity (e.g., 'document', 'client')","title":"Entity Type"},"description":"Type of the entity (e.g., 'document', 'client')"},{"name":"entity_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Entity ID","title":"Entity Id"},"description":"Entity ID"},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/audit/high-risk":{"get":{"tags":["CLIENT","Client Document Management","DMS Audit"],"summary":"Get high-risk audit actions","description":"Retrieve audit logs flagged as high or critical risk for immediate review.","operationId":"get_high_risk_actions_internal_api_clients__client_id__dms_audit_high_risk_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","description":"Maximum number of entries to return","default":100,"title":"Limit"},"description":"Maximum number of entries to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/audit/stats":{"get":{"tags":["CLIENT","Client Document Management","DMS Audit"],"summary":"Get audit statistics","description":"Get aggregated statistics about audit logs for the client.","operationId":"get_audit_stats_internal_api_clients__client_id__dms_audit_stats_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/audit/actions":{"get":{"tags":["CLIENT","Client Document Management","DMS Audit"],"summary":"Get available audit action types","description":"Retrieve a list of all predefined audit action types, risk levels, and entity types.","operationId":"get_available_actions_internal_api_clients__client_id__dms_audit_actions_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/internal/api/clients/{client_id}/dms/tags":{"post":{"tags":["CLIENT","Client Document Management","DMS Tags"],"summary":"Create tag definition","description":"Create a new tag definition","operationId":"create_tag_definition_internal_api_clients__client_id__dms_tags_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagDefinitionCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagDefinitionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["CLIENT","Client Document Management","DMS Tags"],"summary":"Get tag definitions","description":"Get all tag definitions","operationId":"get_tag_definitions_internal_api_clients__client_id__dms_tags_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (must be >= 1)","default":1,"title":"Page"},"description":"Page number (must be >= 1)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"description":"Items per page (must be > 0)","default":50,"title":"Limit"},"description":"Items per page (must be > 0)"},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","description":"Sort field","default":"display_name","title":"Sort By"},"description":"Sort field"},{"name":"sort_order","in":"query","required":false,"schema":{"type":"string","description":"Sort order","default":"asc","title":"Sort Order"},"description":"Sort order"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search term","title":"Search"},"description":"Search term"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TagDefinitionResponse"},"title":"Response Get Tag Definitions Internal Api Clients  Client Id  Dms Tags Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/tags/{tag_id}":{"get":{"tags":["CLIENT","Client Document Management","DMS Tags"],"summary":"Get tag definition","description":"Get a specific tag definition","operationId":"get_tag_definition_internal_api_clients__client_id__dms_tags__tag_id__get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"tag_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Tag Id"}},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagDefinitionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["CLIENT","Client Document Management","DMS Tags"],"summary":"Update tag definition","description":"Update a tag definition","operationId":"update_tag_definition_internal_api_clients__client_id__dms_tags__tag_id__put","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"tag_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Tag Id"}},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagDefinitionUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagDefinitionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["CLIENT","Client Document Management","DMS Tags"],"summary":"Delete tag definition","description":"Delete (deactivate) a tag definition","operationId":"delete_tag_definition_internal_api_clients__client_id__dms_tags__tag_id__delete","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"tag_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Tag Id"}},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"reason","in":"query","required":true,"schema":{"type":"string","description":"Reason for deletion","title":"Reason"},"description":"Reason for deletion"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/document-checklist/process-from-document":{"post":{"tags":["CLIENT","Client Document Management","Document Checklist"],"summary":"Process Document Checklist from Document","description":"Trigger document checklist generation from a previous year return document. Proxies to tax-engine /api/v1/document-checklist/process-from-document.","operationId":"process_document_checklist_from_document_internal_api_clients__client_id__dms_document_checklist_process_from_document_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"document_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Document ID","title":"Document Id"},"description":"Document ID"},{"name":"tax_year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":1900},{"type":"null"}],"description":"Tax year (optional)","title":"Tax Year"},"description":"Tax year (optional)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/document-checklist":{"get":{"tags":["CLIENT","Client Document Management","Document Checklist"],"summary":"Get Active Document Checklist","description":"Get the active document checklist for a client and tax year. Returns items grouped by document_type with aggregated instance_names. Proxies to tax-engine /api/v1/document-checklist.","operationId":"get_checklist_internal_api_clients__client_id__dms_document_checklist_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","maximum":2100,"minimum":1900,"description":"Tax year (1900-2100)","title":"Tax Year"},"description":"Tax year (1900-2100)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/shares":{"post":{"tags":["CLIENT","Client Document Management","DMS Shares"],"summary":"Share a DMS resource with the current client","description":"Share a folder or document with the client identified by the URL path. The recipient email is resolved internally — never supplied by the caller. Idempotent: returns the existing share if one already exists.","operationId":"create_share_internal_api_clients__client_id__dms_shares_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DMSShareCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DMSShareResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["CLIENT","Client Document Management","DMS Shares"],"summary":"List active shares for a resource","description":"Return all active shares for a specific DMS resource. Requires resource_type and resource_id query parameters.","operationId":"list_shares_for_resource_internal_api_clients__client_id__dms_shares_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"resource_type","in":"query","required":true,"schema":{"$ref":"#/components/schemas/DMSShareResourceTypeEnum","description":"Resource type: FOLDER or DOCUMENT"},"description":"Resource type: FOLDER or DOCUMENT"},{"name":"resource_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Resource UUID","title":"Resource Id"},"description":"Resource UUID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DMSShareListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/dms/shares/{share_id}":{"delete":{"tags":["CLIENT","Client Document Management","DMS Shares"],"summary":"Revoke a share","description":"Deactivate a share so the client can no longer access the resource. Returns a warnings array when the document is still reachable via an ancestor folder share (the direct share has been removed but the CPA must also move or unshare the folder to fully revoke access).","operationId":"revoke_share_internal_api_clients__client_id__dms_shares__share_id__delete","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"share_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Share Id"}},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeShareResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/workpaper/status":{"get":{"tags":["CLIENT","Workpaper"],"summary":"Get workpaper evaluation status (poll by tax_return_id)","description":"Returns evaluation job status for the given tax_return_id. Poll until status is \"COMPLETED\" or \"FAILED\"; then call GET workpaper to fetch the workpaper. Returns \"IDLE\" if no job.","operationId":"get_workpaper_status","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"tax_return_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Tax return ID from evaluate/reevaluate response","title":"Tax Return Id"},"description":"Tax return ID from evaluate/reevaluate response"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkpaperStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/workpaper":{"get":{"tags":["CLIENT","Workpaper"],"summary":"Get Workpaper (via tax-engine)","description":"Returns workpaper (status, job, indeterminate_forms, forms) for the given client and tax year. Call after status is COMPLETED. Proxies to tax-engine.","operationId":"get_workpaper","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","maximum":2100,"minimum":1900,"description":"Tax year (1900-2100)","title":"Tax Year"},"description":"Tax year (1900-2100)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkpaperResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/workpaper/pdf":{"get":{"tags":["CLIENT","Workpaper"],"summary":"Get presigned URL for workpaper PDF by storage key","description":"Return a short-lived presigned URL for a workpaper PDF. Pass storage_key from GET workpaper (workpaper_pdf_storage_key for full PDF, or forms[].workpaper_pdf_storage_key for per-form). Client from path must match the key (workpaper-artifacts/client-{client_id}/...).","operationId":"get_workpaper_pdf","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"storage_key","in":"query","required":true,"schema":{"type":"string","description":"Storage key from workpaper response (full or per-form PDF)","title":"Storage Key"},"description":"Storage key from workpaper response (full or per-form PDF)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkpaperPdfUrlResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/workpaper/evaluate":{"post":{"tags":["CLIENT","Workpaper"],"summary":"Evaluate Workpaper (first-time, async)","description":"First-time evaluation: get-or-create draft tax return for this client and tax year. If one already exists, returns that same tax_return_id. Returns 202 + tax_return_id; frontend polls GET workpaper/status?tax_return_id= until COMPLETED or FAILED, then GET workpaper.","operationId":"evaluate_workpaper","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkpaperEvaluateBody"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkpaperAcceptedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/workpaper/reevaluate":{"post":{"tags":["CLIENT","Workpaper"],"summary":"Reevaluate Workpaper (re-run, async)","description":"Re-run evaluation on an existing draft. Pass tax_return_id from GET workpaper (or omit to look up by tax_year; 400 if none). Returns 202 + tax_return_id; poll GET workpaper/status for status.","operationId":"reevaluate_workpaper","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkpaperReevaluateBody"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkpaperAcceptedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/workpaper/mark-dirty":{"post":{"tags":["CLIENT","Workpaper"],"summary":"Mark workpaper dirty","description":"Sets workpaper_dirty for this client and tax year. GET workpaper will return status=STALE until the next successful evaluation. Call when document upload or questionnaire data changes.","operationId":"mark_workpaper_dirty","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkpaperMarkDirtyBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkpaperMarkDirtyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/custom-fields":{"get":{"tags":["CLIENT","Custom Field Values"],"summary":"Get Client Custom Fields","description":"Get all custom field values for a specific client. Returns a dictionary with field_key as keys and values as values.","operationId":"get_client_custom_fields_internal_api_clients__client_id__custom_fields_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Get Client Custom Fields Internal Api Clients  Client Id  Custom Fields Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["CLIENT","Custom Field Values"],"summary":"Update Client Custom Fields","description":"Update custom field values for a client. Only provided fields will be updated. Fields not in request remain unchanged.","operationId":"update_client_custom_fields_internal_api_clients__client_id__custom_fields_put","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"Custom Fields"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Update Client Custom Fields Internal Api Clients  Client Id  Custom Fields Put"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["CLIENT","Custom Field Values"],"summary":"Partial Update Client Custom Fields","description":"Partially update custom field values. Same as PUT but semantically clearer for partial updates.","operationId":"patch_client_custom_fields_internal_api_clients__client_id__custom_fields_patch","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"Custom Fields"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Patch Client Custom Fields Internal Api Clients  Client Id  Custom Fields Patch"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["CLIENT","Custom Field Values"],"summary":"Clear All Custom Fields","description":"Remove all custom field values for a client.","operationId":"clear_all_client_custom_fields_internal_api_clients__client_id__custom_fields_delete","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}/custom-fields/{field_key}":{"delete":{"tags":["CLIENT","Custom Field Values"],"summary":"Delete Custom Field Value","description":"Remove a specific custom field value for a client.","operationId":"delete_client_custom_field_internal_api_clients__client_id__custom_fields__field_key__delete","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"field_key","in":"path","required":true,"schema":{"type":"string","title":"Field Key"}},{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/tax-activities":{"get":{"tags":["CLIENT","Tax Activities"],"summary":"List a client's tax activities","description":"Schedule C businesses, Schedule E rentals, Schedule F farms (from questionnaire repeatable instances) plus the principal residence — for activity-link dropdowns.","operationId":"list_client_tax_activities","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","maximum":2100,"minimum":1900,"description":"Tax year (1900-2100)","title":"Tax Year"},"description":"Tax year (1900-2100)"},{"name":"activity_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional filter for whole-form links — one type or a comma-separated set (SCH_C / SCH_E / SCH_F / RESIDENCE). E.g. 'SCH_E,SCH_C' for a 1099-MISC or 'RESIDENCE,SCH_E,SCH_C' for a 1099-S. Empty/omitted returns all.","title":"Activity Type"},"description":"Optional filter for whole-form links — one type or a comma-separated set (SCH_C / SCH_E / SCH_F / RESIDENCE). E.g. 'SCH_E,SCH_C' for a 1099-MISC or 'RESIDENCE,SCH_E,SCH_C' for a 1099-S. Empty/omitted returns all."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TaxActivityOption"},"title":"Response List Client Tax Activities"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/bulk-import/csv":{"post":{"tags":["CLIENT","Bulk Import"],"summary":"Bulk Import Clients from CSV","description":"Import multiple clients from a CSV file. Supports custom fields and spouse data.","operationId":"bulk_import_from_csv_internal_api_clients_bulk_import_csv_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","description":"If true, validate data but don't create clients","default":false,"title":"Dry Run"},"description":"If true, validate data but don't create clients"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_bulk_import_from_csv_internal_api_clients_bulk_import_csv_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkImportResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/bulk-import/validate":{"post":{"tags":["CLIENT","Bulk Import"],"summary":"Validate CSV File","description":"Validate a CSV file without importing. Useful for checking data before actual import.","operationId":"validate_csv_file_internal_api_clients_bulk_import_validate_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_validate_csv_file_internal_api_clients_bulk_import_validate_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkImportResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"CustomOAuth2PasswordBearer":[]}]}},"/internal/api/clients/":{"post":{"tags":["CLIENT","Client Management"],"summary":"Create New Client","description":"Create a new client with comprehensive information including filing details, address, and contact info. Only full name is required - all other fields are optional.","operationId":"create_client_internal_api_clients__post","security":[{"CustomOAuth2PasswordBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["CLIENT","Client Management"],"summary":"List Clients","description":"Get a paginated list of clients with optional filtering and sorting.","operationId":"list_clients_internal_api_clients__get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/StatusEnum"},{"type":"null"}],"description":"Filter by status (ACTIVE, DRAFT, INACTIVE)","title":"Status"},"description":"Filter by status (ACTIVE, DRAFT, INACTIVE)"},{"name":"filing_type","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/FilingTypeEnum"},{"type":"null"}],"description":"Filter by filing type","title":"Filing Type"},"description":"Filter by filing type"},{"name":"filing_status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/FilingStatusEnum"},{"type":"null"}],"description":"Filter by filing status","title":"Filing Status"},"description":"Filter by filing status"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (1-based)","default":1,"title":"Page"},"description":"Page number (1-based)"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page (max 100)","default":20,"title":"Page Size"},"description":"Number of items per page (max 100)"},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ClientSortField"},{"type":"null"}],"description":"Field to sort by (created_at, name, email, readable_id)","default":"created_at","title":"Sort By"},"description":"Field to sort by (created_at, name, email, readable_id)"},{"name":"sort_order","in":"query","required":false,"schema":{"$ref":"#/components/schemas/SortOrder","description":"Sort order","default":"desc"},"description":"Sort order"},{"name":"search_query","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search term","title":"Search Query"},"description":"Search term"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientSearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/autocomplete":{"get":{"tags":["CLIENT","Client Management"],"summary":"Client Autocomplete","description":"Get a simplified list of clients for autocomplete with minimum 3 characters. Returns id, full_name, email, and readable_id.","operationId":"autocomplete_clients_internal_api_clients_autocomplete_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":3,"description":"Search query (minimum 3 characters)","title":"Query"},"description":"Search query (minimum 3 characters)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientAutocompleteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_id}":{"get":{"tags":["CLIENT","Client Management"],"summary":"Get Complete Client Profile","description":"Retrieve comprehensive client profile including Basic & Tax Information, Identification & Address details, and Family Information (spouse and dependents).","operationId":"get_client_by_id_internal_api_clients__client_id__get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Client Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["CLIENT","Client Management"],"summary":"Delete Client","description":"Soft delete a client by setting status to INACTIVE. Related entities (spouse, dependents) will be implicitly filtered out when querying.","operationId":"delete_client_internal_api_clients__client_id__delete","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Client Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/readable/{readable_id}":{"get":{"tags":["CLIENT","Client Management"],"summary":"Get Client by Readable ID","description":"Retrieve a specific client by their readable ID (e.g., CL-000001).","operationId":"get_client_by_readable_id_internal_api_clients_readable__readable_id__get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"readable_id","in":"path","required":true,"schema":{"type":"string","title":"Readable Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/external/{external_id}":{"get":{"tags":["CLIENT","Client Management"],"summary":"Get Client by External ID","description":"Retrieve a specific client by their external ID.","operationId":"get_client_by_external_id_internal_api_clients_external__external_id__get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string","title":"External Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/{client_identifier}":{"patch":{"tags":["CLIENT","Client Management"],"summary":"Update Complete Client Profile","description":"Comprehensive client profile update supporting all related information: Basic & Tax Information, SSN, Identification & Address details, Spouse information, and Dependents. Supports partial updates - only provided fields will be updated. Can create or update spouse and dependents in the same request.","operationId":"update_client_internal_api_clients__client_identifier__patch","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_identifier","in":"path","required":true,"schema":{"type":"string","title":"Client Identifier"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/clients/search":{"post":{"tags":["CLIENT","Client Management"],"summary":"Search Clients","description":"Search clients with filters and pagination.","operationId":"search_clients_internal_api_clients_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientSearchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientSearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"CustomOAuth2PasswordBearer":[]}]}},"/internal/api/cpa-chat/messages":{"post":{"tags":["CPA CHAT"],"summary":"Send a CPA chat message and run one agent turn.","operationId":"send_message_internal_api_cpa_chat_messages_post","security":[{"CustomOAuth2PasswordBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["CPA CHAT"],"summary":"Fetch the caller's message history for a (client, year) scope.","description":"Return the displayable message history for the caller's scope.\n\nTenant is derived from the JWT bearer token. Returns an empty list if no\nconversation exists yet. Internal tool_use / tool_result messages are\nfiltered out — only user inputs and the assistant's parsed narratives\nare emitted.","operationId":"get_message_history_internal_api_cpa_chat_messages_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"Client Id"}},{"name":"tax_year","in":"query","required":false,"schema":{"type":"integer","default":2025,"title":"Tax Year"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/cpa-chat/messages/stream":{"post":{"tags":["CPA CHAT"],"summary":"Send a CPA chat message and receive Server-Sent Events as the turn progresses.","description":"Stream the agent's thinking as Server-Sent Events.\n\nEvent types (each ``data:`` line is a JSON object with a ``type`` field):\n\n- ``iteration``     — top of each agent loop iteration: ``{iteration, max_iterations}``\n- ``progress``      — tool dispatch started: ``{tool, stage, tool_use_id}``\n- ``tool_complete`` — tool finished: ``{tool, status, elapsed_ms, tool_use_id}``\n- ``text_delta``    — assistant text token: ``{text}``\n- ``done``          — turn done; carries cumulative ``{usage}``\n- ``result``        — terminal payload (full ``SendMessageResponse`` shape)\n- ``error``         — turn failed; carries ``{message}``\n\nThe browser opens an EventSource and renders each event as it arrives.","operationId":"send_message_stream_internal_api_cpa_chat_messages_stream_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"CustomOAuth2PasswordBearer":[]}]}},"/internal/api/cpa-chat/reset":{"post":{"tags":["CPA CHAT"],"summary":"Reset the caller's conversation for a (client, year) scope.","operationId":"reset_conversation_internal_api_cpa_chat_reset_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetConversationRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetConversationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"CustomOAuth2PasswordBearer":[]}]}},"/internal/api/mcp/keys":{"post":{"tags":["MCP CONNECTOR"],"summary":"Create an MCP API key for your organization.","description":"Mint a key and return the plaintext.\n\n``sha256(secret)`` drives authentication; a Fernet copy under a\ntenant-derived key is stored alongside so the Owner can read the\ncredential back later. Several live keys per organization is\nintentional: rotating means issuing a new key, moving the connector\nover, then revoking the old one.","operationId":"create_key_internal_api_mcp_keys_post","security":[{"CustomOAuth2PasswordBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["MCP CONNECTOR"],"summary":"List your organization's MCP API keys.","description":"Secrets are never included here — only the masked form.\n\nReading a key back is a separate, audited call on a single key, so\nthat listing cannot become a bulk credential export.\n\n``include_revoked`` exists for audit: a withdrawn key is kept so a\nreviewer can answer which credential was used and when access was\nremoved.","operationId":"list_keys_internal_api_mcp_keys_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"include_revoked","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Revoked"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/mcp/keys/{key_row_id}/reveal":{"get":{"tags":["MCP CONNECTOR"],"summary":"Read an MCP API key back (Owner only, audited).","description":"Return the plaintext credential to the firm Owner.\n\nOWNER-only, one role above the ADMIN who may manage the team: this\nhands back a live credential that reads every client in the firm.\n\nThe audit stamp is written and COMMITTED BEFORE the plaintext is\nreturned. If that write fails the request fails and nothing is\ndisclosed — an unrecorded reveal is exactly the event the record\nexists to capture, so it must not be possible to have one.\n\nA revoked key is not revealable. Handing back a withdrawn credential\nonly invites it being pasted into a connector that will fail, and it\nwidens the window in which the plaintext exists for no benefit.","operationId":"reveal_key_internal_api_mcp_keys__key_row_id__reveal_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"key_row_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Key Row Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevealApiKeyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/mcp/disclosures":{"get":{"tags":["MCP CONNECTOR"],"summary":"Export the MCP disclosure log for your organization.","description":"Answer \"who looked at this return, and what were they told?\".\n\nUnder §7216 the disclosure is the regulated event, so this is the\ncompliance artifact — self-service on purpose, because a firm should\nnot need a support ticket to answer a taxpayer.\n\nPass ``client_id`` for the taxpayer's own question. Results are\ntenant-scoped unconditionally: an export is one firm's record of its\nown disclosures, and a missing predicate here would turn the\ncompliance artifact into the leak it exists to prevent.","operationId":"list_disclosures_internal_api_mcp_disclosures_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Client Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":500,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisclosureListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/mcp/keys/{key_row_id}":{"delete":{"tags":["MCP CONNECTOR"],"summary":"Revoke an MCP API key.","description":"Withdraw a credential.\n\nThe tenant predicate lives on the UPDATE itself, so one firm cannot\nrevoke another's key by guessing an id — and the response does not\ndistinguish \"not yours\" from \"already revoked\", because a\ndistinguishable answer makes key ids probeable.\n\nClears this process's key cache immediately. Other workers age out\nwithin ``ELAN_MCP_API_KEY_CACHE_SECONDS`` (default 30s), which is the\nrevocation latency the cache TTL is chosen to bound. Returns 200 with\n``revoked=false`` rather than 404: revoking is idempotent, and the\ncaller's intent — \"this key must not work\" — is satisfied either way.","operationId":"revoke_key_internal_api_mcp_keys__key_row_id__delete","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"key_row_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Key Row Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeApiKeyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/mcp/settings":{"put":{"tags":["MCP CONNECTOR"],"summary":"Turn the MCP connector on or off for your organization.","description":"The per-firm switch the MCP auth path checks on every request.\n\nWithout this endpoint the self-service flow did not actually work:\nabsence of a settings row means DISABLED, nothing else created one, so\na firm could mint a key and get ``401 the MCP connector is not enabled\nfor this organization`` with no way to fix it from the dashboard.\n\nDisabling does NOT revoke keys. That separation is the point — an\noperator can suspend a firm without invalidating credentials their\nteam has already deployed into infrastructure we do not control, and\nre-enabling restores service without a re-integration.\n\nReturns the full connection state so the settings page re-renders from\none round trip rather than toggling and then re-fetching.","operationId":"update_settings_internal_api_mcp_settings_put","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMcpSettingsRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpConnectionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"CustomOAuth2PasswordBearer":[]}]}},"/internal/api/mcp/connection":{"get":{"tags":["MCP CONNECTOR"],"summary":"Connection details and setup steps for the MCP connector.","description":"Everything the Settings page shows a firm wiring Elan into their AI stack.\n\nCarries NO credential — ``<YOUR_API_KEY>`` is a placeholder in every\nsnippet. That keeps this response safe to render, screenshot and paste\ninto a support ticket, which is what people do with setup instructions\nwhatever the warning says.","operationId":"connection_details_internal_api_mcp_connection_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpConnectionResponse"}}}}},"security":[{"CustomOAuth2PasswordBearer":[]}]}},"/internal/api/dms/document-types":{"get":{"tags":["DMS Documents","DMS Documents"],"summary":"Get Document Types","description":"Get a list of all available document types from DocumentTypeEnum for use in intake requests. Display names are retrieved from the database for consistency.","operationId":"get_document_types_internal_api_dms_document_types_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"extraction-supported","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"When true, returns only extraction-supported active document types.","title":"Extraction-Supported"},"description":"When true, returns only extraction-supported active document types."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentTypesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/intake-requests":{"get":{"tags":["Intake Requests Dashboard","Intake Requests Dashboard"],"summary":"List Intake Requests for Dashboard","description":"Get a paginated list of all intake requests across all clients for the tenant. Includes client name, progress, status, and dates for dashboard display.","operationId":"list_upload_requests_for_dashboard_internal_api_intake_requests_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (1-based)","default":1,"title":"Page"},"description":"Page number (1-based)"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page (max 100)","default":20,"title":"Page Size"},"description":"Number of items per page (max 100)"},{"name":"status_filter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated list of status labels to filter by: 'Draft', 'Email Sent', 'In Progress', 'Completed', 'Expired', 'Revoked'","title":"Status Filter"},"description":"Comma-separated list of status labels to filter by: 'Draft', 'Email Sent', 'In Progress', 'Completed', 'Expired', 'Revoked'"},{"name":"client_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Optional client ID to filter by specific client","title":"Client Id"},"description":"Optional client ID to filter by specific client"},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","description":"Field to sort by: 'updated_at', 'created_at', 'expires_at'","default":"updated_at","title":"Sort By"},"description":"Field to sort by: 'updated_at', 'created_at', 'expires_at'"},{"name":"sort_order","in":"query","required":false,"schema":{"type":"string","description":"Sort order: 'asc' or 'desc'","default":"desc","title":"Sort Order"},"description":"Sort order: 'asc' or 'desc'"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search by client name (case-insensitive partial match)","title":"Search"},"description":"Search by client name (case-insensitive partial match)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUploadRequestDashboardListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/intake-requests/{request_id}":{"get":{"tags":["Intake Requests Dashboard","Intake Requests Dashboard"],"summary":"Get Intake Request Details for Dashboard","description":"Get comprehensive details about a specific intake request for dashboard view. Includes client information, completion statistics, and separated document lists.","operationId":"get_upload_request_for_dashboard_internal_api_intake_requests__request_id__get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Request Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUploadRequestDashboardDetailResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/tax-return-generation-requests":{"get":{"tags":["Tax Return Generation"],"summary":"List tax return generation requests","description":"Paginated list of tax returns that have at least one workpaper evaluation job, for all clients in the tenant. Filter by tax year, latest job status, client id, or client name search.","operationId":"list_tax_return_generation_requests_internal_api_tax_return_generation_requests_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (1-based)","default":1,"title":"Page"},"description":"Page number (1-based)"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Items per page (max 100)","default":20,"title":"Page Size"},"description":"Items per page (max 100)"},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","description":"Sort field: last_generation_at, first_generation_at, client_name, tax_year","default":"last_generation_at","title":"Sort By"},"description":"Sort field: last_generation_at, first_generation_at, client_name, tax_year"},{"name":"sort_order","in":"query","required":false,"schema":{"type":"string","description":"asc or desc","default":"desc","title":"Sort Order"},"description":"asc or desc"},{"name":"tax_year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":1900},{"type":"null"}],"description":"Filter by tax year","title":"Tax Year"},"description":"Filter by tax year"},{"name":"latest_job_status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated latest job statuses: PENDING, RUNNING, COMPLETED, FAILED","title":"Latest Job Status"},"description":"Comma-separated latest job statuses: PENDING, RUNNING, COMPLETED, FAILED"},{"name":"client_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filter by client id","title":"Client Id"},"description":"Filter by client id"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Case-insensitive partial match on client full name (min 2 chars when set)","title":"Search"},"description":"Case-insensitive partial match on client full name (min 2 chars when set)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxReturnGenerationRequestListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/tax-export/{client_id}/drake/fill-csv":{"get":{"tags":["Tax Export"],"summary":"Download a client's Drake fill CSV (System-B; feeds DrakeFiller.exe)","description":"Build the resolved fill CSV and stream it as a download. Fail-closed: 409 if any row does not\nresolve to a calibrated Drake control. Hand the CSV to DrakeFiller.exe on the preparer's machine.","operationId":"drake_fill_csv_internal_api_tax_export__client_id__drake_fill_csv_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client id","title":"Client Id"},"description":"Client id"},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","maximum":2100,"minimum":2000,"title":"Tax Year"}}],"responses":{"200":{"description":"The self-describing fill CSV as a file download (text/csv).","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/settings/team":{"get":{"tags":["SETTINGS"],"summary":"List team members","description":"Everyone with access to the firm's workspace: real users and pending invitations, merged into one list with a `type` discriminator. Available to every authenticated member; `last_login_at` is withheld from non-administrators.","operationId":"list_team_internal_api_settings_team_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamListResponse"}}}}},"security":[{"CustomOAuth2PasswordBearer":[]}]}},"/internal/api/settings/profile":{"get":{"tags":["SETTINGS"],"summary":"Get the signed-in user's profile","operationId":"get_profile_internal_api_settings_profile_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileResponse"}}}}},"security":[{"CustomOAuth2PasswordBearer":[]}]}},"/internal/api/settings/team/invites":{"post":{"tags":["SETTINGS"],"summary":"Invite someone to the firm","operationId":"create_invite_internal_api_settings_team_invites_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteCreateRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteCreatedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"CustomOAuth2PasswordBearer":[]}]}},"/internal/api/settings/team/invites/{invite_id}/resend":{"post":{"tags":["SETTINGS"],"summary":"Resend a pending invitation","description":"Mints a fresh token and resets the expiry. The previously emailed link stops working immediately.","operationId":"resend_invite_internal_api_settings_team_invites__invite_id__resend_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"invite_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Invite Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteCreatedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/settings/team/invites/{invite_id}":{"patch":{"tags":["SETTINGS"],"summary":"Change the role a pending invitation will grant","operationId":"update_invite_internal_api_settings_team_invites__invite_id__patch","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"invite_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Invite Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamMemberResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["SETTINGS"],"summary":"Revoke a pending invitation","operationId":"revoke_invite_internal_api_settings_team_invites__invite_id__delete","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"invite_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Invite Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/settings/team/members/{user_id}":{"patch":{"tags":["SETTINGS"],"summary":"Change a member's role and/or status","description":"Deactivation is effective on the target's very next request — the authentication dependency re-reads user status from the database on every call. There is deliberately no delete: a preparer who touched a return must still resolve to a name years later.","operationId":"update_member_internal_api_settings_team_members__user_id__patch","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemberUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemberUpdateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/settings/team/claim-ownership":{"post":{"tags":["SETTINGS"],"summary":"Take ownership of a firm whose Owner has left","description":"For the departed-Owner case, which transfer-ownership cannot serve because only the sitting Owner may call that. Refused while the Owner is still ACTIVE, so a live Owner always hands over deliberately. Audited as a critical access-control event.","operationId":"claim_ownership_internal_api_settings_team_claim_ownership_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamListResponse"}}}}},"security":[{"CustomOAuth2PasswordBearer":[]}]}},"/internal/api/settings/team/members/{user_id}/transfer-ownership":{"post":{"tags":["SETTINGS"],"summary":"Transfer firm ownership to another member","description":"Promotes the target to Owner and demotes the current Owner to Administrator in a single transaction, so the firm is never left with zero or two owners. Owner-only.","operationId":"transfer_ownership_internal_api_settings_team_members__user_id__transfer_ownership_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/settings/preferences":{"get":{"tags":["SETTINGS"],"summary":"List the firm's preferences","description":"Every preference the firm can configure, with its current value, the product default, and enough metadata to render a control without the client knowing what any individual preference means. Readable by any authenticated member; `editable` on each row reports whether THIS caller may change it.","operationId":"get_preferences_internal_api_settings_preferences_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreferencesResponse"}}}}},"security":[{"CustomOAuth2PasswordBearer":[]}]},"patch":{"tags":["SETTINGS"],"summary":"Change one or more preferences","description":"Partial update — only the keys present in `values` are touched. Validation is all-or-nothing: one invalid value rejects the whole request rather than saving half of it. Returns the full refreshed set so the client never has to merge. An unknown key answers 400 `SETTING_UNKNOWN_KEY`; a value outside its definition answers 400 `SETTING_INVALID_VALUE`.","operationId":"update_preferences_internal_api_settings_preferences_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreferencesUpdateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreferencesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"CustomOAuth2PasswordBearer":[]}]}},"/internal/api/invites/preview":{"post":{"tags":["INVITES"],"summary":"Preview an invitation","description":"POST rather than GET because the token is in the body, not the path — see the module docstring. Returns 410 with a specific error_type for expired / revoked / already-accepted invites so the page can tell the invitee what to do next, and 404 when the token doesn't resolve at all (typically because a resend replaced it).","operationId":"preview_invite_internal_api_invites_preview_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitePreviewRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitePreviewResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/invites/accept":{"post":{"tags":["INVITES"],"summary":"Accept an invitation and create the account","description":"Creates the member in the inviting tenant with the role stored on the invite, marks the email verified (the token already proved mailbox control), and returns an access token so the invitee lands signed in. Neither the email nor the role can be supplied by the caller.","operationId":"accept_invite_internal_api_invites_accept_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteAcceptRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteAcceptResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/tax-export/{client_id}/lacerte/bridge-file":{"get":{"tags":["Tax Export"],"summary":"Download a client's Lacerte GL Bridge file (.IB5)","description":"Build the client's .IB5 and stream it. The client's CPA drops the file into Lacerte via\nthe SignalsHQ importer; Lacerte reads it on its next startup.","operationId":"lacerte_bridge_file_internal_api_tax_export__client_id__lacerte_bridge_file_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client id","title":"Client Id"},"description":"Client id"},{"name":"tax_year","in":"query","required":false,"schema":{"type":"integer","maximum":2100,"minimum":2000,"default":2025,"title":"Tax Year"}}],"responses":{"200":{"description":"The .IB5 bridge file as a file download (application/xml).","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/tax-export/{client_id}/proseries/plan":{"get":{"tags":["Tax Export"],"summary":"Download a client's ProSeries fill plan","description":"Compile the client's ProSeries fill plan and stream it as a download.","operationId":"proseries_plan_internal_api_tax_export__client_id__proseries_plan_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client id","title":"Client Id"},"description":"Client id"},{"name":"tax_year","in":"query","required":false,"schema":{"type":"integer","maximum":2100,"minimum":2000,"default":2025,"title":"Tax Year"}}],"responses":{"200":{"description":"The fill artifact as a file download (application/json).","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Tax Export"],"summary":"Download a ProSeries fill plan for the chosen documents and questionnaire groups","description":"Compile a plan limited to what the preparer chose, and stream it as a download.\n\n☠ THE GET ABOVE IS UNTOUCHED AND STAYS THE FULL EXPORT. Every existing caller keeps working\n  with no selection concept at all; this is an addition, not a migration. A POST with an\n  empty body is identical to that GET.","operationId":"proseries_plan_selected_internal_api_tax_export__client_id__proseries_plan_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client id","title":"Client Id"},"description":"Client id"},{"name":"tax_year","in":"query","required":false,"schema":{"type":"integer","maximum":2100,"minimum":2000,"default":2025,"title":"Tax Year"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanSelection"}}}},"responses":{"200":{"description":"The fill artifact as a file download (application/json).","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/tax-export/{client_id}/proseries/selectable":{"get":{"tags":["Tax Export"],"summary":"What this client has that a ProSeries export could include","description":"The picker's contents. Builds no plan and writes nothing.\n\nAlways 200 for a readable client, including one with nothing to export — an empty picker is\na true answer, and the export endpoint is where \"nothing to export\" is a 409 with wording\nthat says what is missing.","operationId":"proseries_selectable_internal_api_tax_export__client_id__proseries_selectable_get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Client id","title":"Client Id"},"description":"Client id"},{"name":"tax_year","in":"query","required":false,"schema":{"type":"integer","maximum":2100,"minimum":2000,"default":2025,"title":"Tax Year"}}],"responses":{"200":{"description":"Documents and questionnaire groups the preparer can choose between.","content":{"application/json":{"schema":{"type":"object","title":"Response Proseries Selectable Internal Api Tax Export  Client Id  Proseries Selectable Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/intake":{"get":{"tags":["Public Intake Requests"],"summary":"Get Intake Request Details (Public)","description":"Get details about an intake request using the secure token from X-Intake-Token header. No authentication required.","operationId":"get_upload_request_details_api_public_intake_get","parameters":[{"name":"X-Intake-Token","in":"header","required":true,"schema":{"type":"string","description":"Secure intake token for document upload request","title":"X-Intake-Token"},"description":"Secure intake token for document upload request"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicUploadRequestDetailsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Public Intake Requests"],"summary":"Upload Document (Public)","description":"Upload document using the secure intake token from X-Intake-Token header. No authentication required.","operationId":"upload_document_public_api_public_intake_post","parameters":[{"name":"X-Intake-Token","in":"header","required":true,"schema":{"type":"string","description":"Secure intake token for document upload request","title":"X-Intake-Token"},"description":"Secure intake token for document upload request"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_document_public_api_public_intake_post"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicDocumentUploadResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/intake/mark-opened":{"post":{"tags":["Public Intake Requests"],"summary":"Mark Link Opened (Public)","description":"Record that the client opened the intake link. Transitions status from EMAIL_SENT to ACTIVE. Idempotent. Uses X-Intake-Token header. No authentication required.","operationId":"mark_link_opened_api_public_intake_mark_opened_post","parameters":[{"name":"X-Intake-Token","in":"header","required":true,"schema":{"type":"string","description":"Secure intake token for document upload request","title":"X-Intake-Token"},"description":"Secure intake token for document upload request"}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/intake/status":{"get":{"tags":["Public Intake Requests"],"summary":"Get Intake Progress (Public)","description":"Check the current progress of an intake request using X-Intake-Token header. No authentication required.","operationId":"get_upload_progress_api_public_intake_status_get","parameters":[{"name":"X-Intake-Token","in":"header","required":true,"schema":{"type":"string","description":"Secure intake token for document upload request","title":"X-Intake-Token"},"description":"Secure intake token for document upload request"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/intake/save-progress":{"post":{"tags":["Public Intake Requests"],"summary":"Save Intake Progress (Public)","description":"Save progress without completing. Updates last-saved timestamp. Notifies all tenant CPAs only when there are new uploads since last save and debounce has passed. No uploads -> no notification. Call after upload(s) complete (e.g. Save and Exit) so CPAs are notified. Uses X-Intake-Token header. No authentication required.","operationId":"save_upload_progress_api_public_intake_save_progress_post","parameters":[{"name":"X-Intake-Token","in":"header","required":true,"schema":{"type":"string","description":"Secure intake token for document upload request","title":"X-Intake-Token"},"description":"Secure intake token for document upload request"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveProgressResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/intake/complete":{"post":{"tags":["Public Intake Requests"],"summary":"Complete Intake Request (Public)","description":"Mark the intake request as complete after client has uploaded all documents. Uses X-Intake-Token header. No authentication required.","operationId":"complete_upload_request_api_public_intake_complete_post","parameters":[{"name":"X-Intake-Token","in":"header","required":true,"schema":{"type":"string","description":"Secure intake token for document upload request","title":"X-Intake-Token"},"description":"Secure intake token for document upload request"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/intake/items/{item_id}/reject":{"post":{"tags":["Public Intake Requests"],"summary":"Reject Document Item (Public)","description":"Reject a specific document item in the intake request. Uses X-Intake-Token header. No authentication required.","operationId":"reject_document_item_api_public_intake_items__item_id__reject_post","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}},{"name":"X-Intake-Token","in":"header","required":true,"schema":{"type":"string","description":"Secure intake token for document upload request","title":"X-Intake-Token"},"description":"Secure intake token for document upload request"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectDocumentRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicDocumentUploadRequestItemResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/intake/items/{item_id}/notes":{"patch":{"tags":["Public Intake Requests"],"summary":"Update Client Notes (Public)","description":"Add or update notes for a specific document item. Uses X-Intake-Token header. No authentication required.","operationId":"update_client_notes_api_public_intake_items__item_id__notes_patch","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}},{"name":"X-Intake-Token","in":"header","required":true,"schema":{"type":"string","description":"Secure intake token for document upload request","title":"X-Intake-Token"},"description":"Secure intake token for document upload request"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateClientNotesRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicDocumentUploadRequestItemResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/intake/additional-documents":{"post":{"tags":["Public Intake Requests"],"summary":"Upload Additional Document (Public)","description":"Upload an additional document not in the original request. Uses X-Intake-Token header. No authentication required.","operationId":"upload_additional_document_api_public_intake_additional_documents_post","parameters":[{"name":"X-Intake-Token","in":"header","required":true,"schema":{"type":"string","description":"Secure intake token for document upload request","title":"X-Intake-Token"},"description":"Secure intake token for document upload request"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_additional_document_api_public_intake_additional_documents_post"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicDocumentUploadResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/intake/voluntary-documents":{"post":{"tags":["Public Intake Requests"],"summary":"Upload Voluntary Document (Public)","description":"Upload a document voluntarily without document type. These documents are not counted in request totals. Uses X-Intake-Token header. No authentication required.","operationId":"upload_voluntary_document_api_public_intake_voluntary_documents_post","parameters":[{"name":"X-Intake-Token","in":"header","required":true,"schema":{"type":"string","description":"Secure intake token for document upload request","title":"X-Intake-Token"},"description":"Secure intake token for document upload request"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_voluntary_document_api_public_intake_voluntary_documents_post"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicDocumentUploadResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/intake/documents/{document_id}/download":{"get":{"tags":["Public Intake Requests"],"summary":"Get Document Download URL (Public)","description":"Get a secure download URL for a document uploaded via intake request. Uses X-Intake-Token header. No authentication required.","operationId":"get_document_download_url_api_public_intake_documents__document_id__download_get","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Document Id"}},{"name":"X-Intake-Token","in":"header","required":true,"schema":{"type":"string","description":"Secure intake token for document upload request","title":"X-Intake-Token"},"description":"Secure intake token for document upload request"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadUrlResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/intake/questionnaire/questions-with-responses":{"get":{"tags":["Public Questionnaire"],"summary":"Get Questions with Responses (Public)","description":"Get questionnaire questions with responses using intake token. No authentication required - uses X-Intake-Token header.","operationId":"get_questions_with_responses_public_api_public_intake_questionnaire_questions_with_responses_get","parameters":[{"name":"phase_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional phase code filter","title":"Phase Code"},"description":"Optional phase code filter"},{"name":"X-Intake-Token","in":"header","required":true,"schema":{"type":"string","description":"Secure intake token for document upload request","title":"X-Intake-Token"},"description":"Secure intake token for document upload request"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/intake/questionnaire/responses":{"post":{"tags":["Public Questionnaire V2","Public Questionnaire V2","Responses"],"summary":"Save Questionnaire Responses (Public)","description":"Save questionnaire responses using intake token. No authentication required - uses X-Intake-Token header.","operationId":"save_responses_api_public_intake_questionnaire_responses_post","parameters":[{"name":"X-Intake-Token","in":"header","required":true,"schema":{"type":"string","description":"Secure intake token for document upload request","title":"X-Intake-Token"},"description":"Secure intake token for document upload request"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuestionnaireResponseBatchCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/intake/questionnaire/responses/instances/{instance_id}":{"delete":{"tags":["Public Questionnaire"],"summary":"Delete Question Instance (Public)","description":"Delete a questionnaire instance and its entire subtree -- nested child instances and every bound response -- using an intake token. Addressed by instance UUID: instance numbers are sparse (delete leaves gaps), reused (the backend assigns max+1 over survivors), and cannot identify a nested instance at all. Every instance is deletable, including the first and the last; a group with zero instances is a valid state.","operationId":"delete_instance_public_api_public_intake_questionnaire_responses_instances__instance_id__delete","parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Instance Id"}},{"name":"X-Intake-Token","in":"header","required":true,"schema":{"type":"string","description":"Secure intake token for document upload request","title":"X-Intake-Token"},"description":"Secure intake token for document upload request"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/intake/questionnaire/responses/bulk":{"get":{"tags":["Public Questionnaire V2","Public Questionnaire V2","Responses"],"summary":"Get All Responses (Bulk) - Public","description":"Get all questionnaire responses as a flat map with type information using intake token. No authentication required - uses X-Intake-Token header.","operationId":"get_responses_bulk_api_public_intake_questionnaire_responses_bulk_get","parameters":[{"name":"question_codes","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Optional list of question codes to filter. Can be repeated: ?question_codes=CODE1&question_codes=CODE2","title":"Question Codes"},"description":"Optional list of question codes to filter. Can be repeated: ?question_codes=CODE1&question_codes=CODE2"},{"name":"phase_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional phase code filter","title":"Phase Code"},"description":"Optional phase code filter"},{"name":"X-Intake-Token","in":"header","required":true,"schema":{"type":"string","description":"Secure intake token for document upload request","title":"X-Intake-Token"},"description":"Secure intake token for document upload request"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/intake/questionnaire/phases":{"get":{"tags":["Public Questionnaire V2","Public Questionnaire V2","Phases"],"summary":"Get Questionnaire Phases (Public)","description":"Get all questionnaire phases with optional filtering using intake token. Phases are system-wide static data but authentication is required.","operationId":"get_phases_api_public_intake_questionnaire_phases_get","parameters":[{"name":"is_active","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Optional active status filter","title":"Is Active"},"description":"Optional active status filter"},{"name":"phase_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional phase type filter","title":"Phase Type"},"description":"Optional phase type filter"},{"name":"X-Intake-Token","in":"header","required":true,"schema":{"type":"string","description":"Secure intake token for document upload request","title":"X-Intake-Token"},"description":"Secure intake token for document upload request"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/intake/questionnaire/questions/with-responses":{"get":{"tags":["Public Questionnaire V2","Public Questionnaire V2","Questions"],"summary":"Get Questions with Responses (Public)","description":"Get questionnaire questions with responses using intake token. No authentication required - uses X-Intake-Token header.","operationId":"get_questions_with_responses_api_public_intake_questionnaire_questions_with_responses_get","parameters":[{"name":"phase_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional phase code filter","title":"Phase Code"},"description":"Optional phase code filter"},{"name":"X-Intake-Token","in":"header","required":true,"schema":{"type":"string","description":"Secure intake token for document upload request","title":"X-Intake-Token"},"description":"Secure intake token for document upload request"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/intake/questionnaire/responses/instances":{"post":{"tags":["Public Questionnaire V2","Public Questionnaire V2","Responses"],"summary":"Create Question Instance (Public)","description":"Create a new instance for a repeatable question group using intake token. No authentication required - uses X-Intake-Token header. Use this to create instances #2, #3, etc. Instance #1 is created automatically when the repeatable group question is answered positively.","operationId":"create_instance_api_public_intake_questionnaire_responses_instances_post","parameters":[{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","maximum":2100,"minimum":1900,"description":"Tax year (1900-2100)","title":"Tax Year"},"description":"Tax year (1900-2100)"},{"name":"X-Intake-Token","in":"header","required":true,"schema":{"type":"string","description":"Secure intake token for document upload request","title":"X-Intake-Token"},"description":"Secure intake token for document upload request"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"Body"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/document-checklist":{"get":{"tags":["Public Document Checklist"],"summary":"Get Active Document Checklist (Public)","description":"Get the active document checklist for a client and tax year. Returns items grouped by document_type with aggregated instance_names. Proxies to tax-engine /api/v1/document-checklist. No authentication required - uses client_id query parameter.","operationId":"get_checklist_api_public_document_checklist_get","parameters":[{"name":"client_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Client ID","title":"Client Id"},"description":"Client ID"},{"name":"tax_year","in":"query","required":true,"schema":{"type":"integer","maximum":2100,"minimum":1900,"description":"Tax year (1900-2100)","title":"Tax Year"},"description":"Tax year (1900-2100)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/dms/contents":{"get":{"tags":["Public DMS — Shared Documents"],"summary":"Browse shared DMS content","description":"Returns all DMS resources shared with the authenticated client, navigable the same way as the internal /dms/folders/contents endpoint. Omit folder_id to see the virtual root (all directly shared items). Pass folder_id to browse inside a shared folder or any of its sub-folders.","operationId":"get_client_dms_contents_api_public_dms_contents_get","parameters":[{"name":"folder_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Folder to browse. Omit for the virtual root (all shares). Must be a directly-shared folder or a descendant of one.","title":"Folder Id"},"description":"Folder to browse. Omit for the virtual root (all shares). Must be a directly-shared folder or a descendant of one."},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","description":"Sort field: name | type | created_at | updated_at","default":"type","title":"Sort By"},"description":"Sort field: name | type | created_at | updated_at"},{"name":"sort_order","in":"query","required":false,"schema":{"type":"string","description":"Sort order: asc | desc","default":"asc","title":"Sort Order"},"description":"Sort order: asc | desc"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (1-based)","default":1,"title":"Page"},"description":"Page number (1-based)"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Items per page","default":50,"title":"Page Size"},"description":"Items per page"},{"name":"X-Intake-Token","in":"header","required":true,"schema":{"type":"string","description":"Secure intake token for document upload request","title":"X-Intake-Token"},"description":"Secure intake token for document upload request"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderContentsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/dms/download/{document_id}":{"get":{"tags":["Public DMS — Shared Documents"],"summary":"Download a shared document by document ID","description":"Generates a short-lived presigned S3 URL for any document the client has access to — either via a direct document share or because the document lives inside a shared folder. No share_id required. Pair this with GET /dms/contents for a consistent browsing + download flow.","operationId":"download_shared_document_api_public_dms_download__document_id__get","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Document Id"}},{"name":"X-Intake-Token","in":"header","required":true,"schema":{"type":"string","description":"Secure intake token for document upload request","title":"X-Intake-Token"},"description":"Secure intake token for document upload request"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedDocumentDownloadResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/dms/upload-config":{"get":{"tags":["Public DMS — Shared Documents"],"summary":"Get document upload config (public)","description":"Public, unauthenticated read of the global document upload constraints (formats + size limits). Used by the client-organizer portal, which authenticates with an intake token rather than a dashboard session and therefore cannot reach the internal /dms/upload-config endpoint. The config is global and non-sensitive.","operationId":"get_public_upload_config_api_public_dms_upload_config_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadPolicyResponse"}}}}}}},"/internal/api/scribe/review-bundle/{client_id}/{document_id}":{"get":{"tags":["scribe-review"],"summary":"Fetch the review payload (data schema + layout + records).","operationId":"review_bundle_endpoint_internal_api_scribe_review_bundle__client_id___document_id__get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Client Id"}},{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Document Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewBundleResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/scribe/journey/{client_id}/{document_id}":{"get":{"tags":["scribe-review"],"summary":"The document's extraction journey: timeline, cost, and a plain-English story.","operationId":"journey_endpoint_internal_api_scribe_journey__client_id___document_id__get","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Client Id"}},{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Document Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Journey Endpoint Internal Api Scribe Journey  Client Id   Document Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/api/scribe/review/{client_id}/{document_id}/mutate":{"post":{"tags":["scribe-review"],"summary":"Apply one mutation to the document's extraction record.","operationId":"mutate_endpoint_internal_api_scribe_review__client_id___document_id__mutate_post","security":[{"CustomOAuth2PasswordBearer":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Client Id"}},{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Document Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Mutate Endpoint Internal Api Scribe Review  Client Id   Document Id  Mutate Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"summary":"Health Check","description":"Health check endpoint for monitoring.","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Health Check Health Get"}}}}}}},"/":{"get":{"summary":"Read Root","description":"Root endpoint that redirects to documentation or shows API info.","operationId":"read_root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"AccountSourceOut":{"properties":{"account_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Key"},"income_family":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Income Family"},"display_payer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Payer"},"document_ids":{"items":{"type":"string"},"type":"array","title":"Document Ids"}},"type":"object","required":["account_key","income_family","display_payer","document_ids"],"title":"AccountSourceOut"},"AddItemsToIntakeRequest":{"properties":{"items":{"items":{"$ref":"#/components/schemas/DocumentUploadRequestItemCreate"},"type":"array","maxItems":50,"minItems":1,"title":"Items","description":"List of document types/items to add to the request","example":[{"description":"1099-INT forms from 2024","document_type":"FORM_1099_INT","extraction_enabled":true,"is_optional":false,"max_files_per_item":1,"tags":["CHASE BANK"]}]}},"type":"object","required":["items"],"title":"AddItemsToIntakeRequest","description":"Schema for adding items to an existing intake request"},"AddressCreate":{"properties":{"street_address":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Street Address","description":"The primary street address including house number and street name"},"address_line_2":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Address Line 2","description":"Additional address information such as apartment, suite, or unit number"},"city":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"City","description":"The city name"},"state":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"State","description":"The state abbreviation or full state name"},"zip_code":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Zip Code","description":"The postal/ZIP code"}},"type":"object","title":"AddressCreate","example":{"address_line_2":"Apt 4B","city":"New York","state":"NY","street_address":"123 Main Street","zip_code":"10001"}},"ApiKeyListResponse":{"properties":{"keys":{"items":{"$ref":"#/components/schemas/ApiKeySummary"},"type":"array","title":"Keys","default":[]}},"type":"object","title":"ApiKeyListResponse"},"ApiKeySummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"key_id":{"type":"string","title":"Key Id","description":"Public half of the credential. Appears in server logs, so it is how you match a suspicious call back to one key."},"label":{"type":"string","title":"Label"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"revoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Revoked At"},"masked_key":{"type":"string","title":"Masked Key","description":"``elan_<key_id>_***`` — render this in the key list. Safe anywhere; the secret half is not in it.","default":""},"revealable":{"type":"boolean","title":"Revealable","description":"Whether the Owner can read this key back. False for keys minted before the reveal feature (no stored secret) and for revoked keys. Drive the reveal button off this rather than letting the user discover it by clicking.","default":false},"last_revealed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Revealed At"},"revealed_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revealed By"},"reveal_count":{"type":"integer","title":"Reveal Count","default":0}},"type":"object","required":["id","key_id","label","created_at"],"title":"ApiKeySummary","description":"A key as an admin sees it. Never carries the secret."},"AttributeEditRequest":{"properties":{"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"Client ID for the attribute"},"new_value":{"anyOf":[{"type":"string","maxLength":10000,"minLength":1},{"type":"null"}],"title":"New Value","description":"Optional new value for the attribute. If not provided, only supported_attribute_id will be updated if specified.","example":"12345"},"change_reason":{"anyOf":[{"type":"string","maxLength":500,"minLength":1},{"type":"null"}],"title":"Change Reason","description":"Optional reason for the change","example":"Corrected OCR error"},"supported_attribute_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Supported Attribute Id","description":"Optional supported attribute ID to update the attribute mapping. If provided, the attribute_id in tenant_client_extracted_attributes will be updated.","example":"550e8400-e29b-41d4-a716-446655440000"}},"type":"object","required":["client_id"],"title":"AttributeEditRequest","description":"Request schema for editing extracted attribute values"},"AttributeEditResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Attribute ID"},"attribute_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Attribute Value","description":"Current attribute value"},"version":{"type":"integer","minimum":1.0,"title":"Version","description":"Current version number"},"status":{"type":"string","title":"Status","description":"Current validation status"},"confidence":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Confidence","description":"Confidence score"},"is_user_updated":{"type":"boolean","title":"Is User Updated","description":"Whether the value was updated by a user"},"updated_at":{"type":"string","title":"Updated At","description":"Last update timestamp"},"updated_by":{"type":"string","title":"Updated By","description":"User who last updated the attribute"}},"type":"object","required":["id","attribute_value","version","status","confidence","is_user_updated","updated_at","updated_by"],"title":"AttributeEditResponse","description":"Response schema for attribute edit operations"},"AttributeStatus":{"type":"string","enum":["NEEDS_REVIEW","VERIFIED"],"title":"AttributeStatus"},"AttributeValidationRequest":{"properties":{"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"Client ID"}},"type":"object","required":["client_id"],"title":"AttributeValidationRequest","description":"Request to validate an extracted attribute."},"AttributeValidationResponse":{"properties":{"attribute_id":{"type":"string","format":"uuid","title":"Attribute Id","description":"ID of the validated attribute"},"status":{"$ref":"#/components/schemas/AttributeStatus","description":"Status of the attribute after validation"},"validated_at":{"type":"string","format":"date-time","title":"Validated At","description":"Timestamp when attribute was validated"},"validated_by":{"type":"string","format":"uuid","title":"Validated By","description":"User ID who validated the attribute"},"workflow_status":{"$ref":"#/components/schemas/WorkflowStatus","description":"Current workflow status"}},"type":"object","required":["attribute_id","status","validated_at","validated_by","workflow_status"],"title":"AttributeValidationResponse","description":"Response model for attribute validation."},"AuditLogItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"action":{"type":"string","title":"Action"},"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id"},"folder_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Folder Id"},"user_id":{"type":"string","format":"uuid","title":"User Id"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"},"details":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Details"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"},"ip_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ip Address","description":"IP address of the user"},"user_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Agent","description":"User agent string"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id","description":"Session ID"}},"type":"object","required":["id","action","document_id","folder_id","user_id","timestamp","details","reason"],"title":"AuditLogItem"},"AuditLogResponse":{"properties":{"audit_entries":{"items":{"$ref":"#/components/schemas/AuditLogItem"},"type":"array","title":"Audit Entries","description":"List of audit log entries"},"meta":{"$ref":"#/components/schemas/app__schemas__dms__audit__PaginationMeta"}},"type":"object","required":["audit_entries","meta"],"title":"AuditLogResponse","description":"Audit log response using generic pagination structure with meta object"},"Body_bulk_import_from_csv_internal_api_clients_bulk_import_csv_post":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"CSV file with client data"}},"type":"object","required":["file"],"title":"Body_bulk_import_from_csv_internal_api_clients_bulk_import_csv_post"},"Body_replace_previous_year_return_with_file_internal_api_clients__client_identifier__previous_year_return_replace_file_post":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"The replacement return"},"expected_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expected Version"},"wrong_taxpayer":{"type":"boolean","title":"Wrong Taxpayer","default":false},"retire_checklist":{"type":"boolean","title":"Retire Checklist","default":false},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"},"override_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Override Reason"}},"type":"object","required":["file"],"title":"Body_replace_previous_year_return_with_file_internal_api_clients__client_identifier__previous_year_return_replace_file_post"},"Body_upload_additional_document_api_public_intake_additional_documents_post":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"Document file to upload"},"document_type":{"$ref":"#/components/schemas/DocumentTypeEnum","description":"Type of document to add"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description of the additional document"},"client_notes":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Client Notes","description":"Optional notes from the client about this document"}},"type":"object","required":["file","document_type"],"title":"Body_upload_additional_document_api_public_intake_additional_documents_post"},"Body_upload_document_for_intake_request_internal_api_clients__client_id__intake_requests__request_id__upload_post":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"Document file to upload"},"item_id":{"type":"string","format":"uuid","title":"Item Id","description":"ID of the specific request item being fulfilled"},"notes":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Notes","description":"Optional notes about this document"}},"type":"object","required":["file","item_id"],"title":"Body_upload_document_for_intake_request_internal_api_clients__client_id__intake_requests__request_id__upload_post"},"Body_upload_document_internal_api_clients__client_id__dms_documents_upload_post":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"Document file to upload"},"folder_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Folder Id","description":"Target folder ID (null for root)"},"document_type":{"anyOf":[{"$ref":"#/components/schemas/DocumentTypeEnum"},{"type":"null"}],"description":"Document type"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Document name (defaults to filename)"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Document description"},"tax_year":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tax Year","description":"Tax year for the document (e.g., '2024')"},"doc_year":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Doc Year","description":"Document year for the document (e.g., '2024')"},"extraction_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Extraction Enabled","description":"Enable automatic document extraction after upload","default":false}},"type":"object","required":["file"],"title":"Body_upload_document_internal_api_clients__client_id__dms_documents_upload_post"},"Body_upload_document_public_api_public_intake_post":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"Document file to upload"},"item_id":{"type":"string","format":"uuid","title":"Item Id","description":"ID of the specific request item being fulfilled"},"client_notes":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Client Notes","description":"Optional notes from the client about this document"}},"type":"object","required":["file","item_id"],"title":"Body_upload_document_public_api_public_intake_post"},"Body_upload_new_version_internal_api_clients__client_id__dms_documents__document_id__versions_post":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"New version file to upload"},"preserve_metadata":{"type":"boolean","title":"Preserve Metadata","description":"Preserve name, folder, description from original (default: true)","default":true}},"type":"object","required":["file"],"title":"Body_upload_new_version_internal_api_clients__client_id__dms_documents__document_id__versions_post"},"Body_upload_voluntary_document_api_public_intake_voluntary_documents_post":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"Document file to upload"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description of the voluntary document"}},"type":"object","required":["file"],"title":"Body_upload_voluntary_document_api_public_intake_voluntary_documents_post"},"Body_validate_csv_file_internal_api_clients_bulk_import_validate_post":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"CSV file to validate"}},"type":"object","required":["file"],"title":"Body_validate_csv_file_internal_api_clients_bulk_import_validate_post"},"BoundingBox":{"properties":{"top":{"type":"number","title":"Top","description":"Y coordinate of top edge (origin top-left, points)"},"left":{"type":"number","title":"Left","description":"X coordinate of left edge (points)"},"width":{"type":"number","title":"Width","description":"Width of the line region (points)"},"height":{"type":"number","title":"Height","description":"Height of the line region (points)"},"page_number":{"type":"integer","title":"Page Number","description":"Zero-based page index (0 = first page). Required for multi-page forms.","default":0}},"type":"object","required":["top","left","width","height"],"title":"BoundingBox","description":"PDF coordinates for line overlay (e.g. in points, top-left origin)."},"BoundingRegion":{"properties":{"page_number":{"type":"integer","title":"Page Number","description":"Page number where the attribute was found"},"x1":{"type":"number","title":"X1","description":"X coordinate of first point"},"y1":{"type":"number","title":"Y1","description":"Y coordinate of first point"},"x2":{"type":"number","title":"X2","description":"X coordinate of second point"},"y2":{"type":"number","title":"Y2","description":"Y coordinate of second point"},"x3":{"type":"number","title":"X3","description":"X coordinate of third point"},"y3":{"type":"number","title":"Y3","description":"Y coordinate of third point"},"x4":{"type":"number","title":"X4","description":"X coordinate of fourth point"},"y4":{"type":"number","title":"Y4","description":"Y coordinate of fourth point"}},"type":"object","required":["page_number","x1","y1","x2","y2","x3","y3","x4","y4"],"title":"BoundingRegion","description":"Bounding region for an extracted attribute"},"BreadcrumbItem":{"properties":{"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Id"},"name":{"type":"string","title":"Name"}},"type":"object","required":["id","name"],"title":"BreadcrumbItem"},"BulkDeleteRequest":{"properties":{"document_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Document Ids","description":"List of document IDs to delete"},"reason":{"type":"string","title":"Reason","description":"Reason for deleting documents"}},"type":"object","required":["document_ids","reason"],"title":"BulkDeleteRequest"},"BulkDocumentExtractionRequest":{"properties":{"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"Client ID for the documents"},"document_ids":{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":500,"minItems":1,"title":"Document Ids","description":"List of document IDs to extract"},"document_type_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Type Id","description":"Optional. When set, extraction runs with this document type (reextraction). Skips the 'already extracted' check so reruns are allowed. Use IDs from GET /types."}},"type":"object","required":["client_id","document_ids"],"title":"BulkDocumentExtractionRequest","description":"Request schema for bulk document extraction"},"BulkDocumentExtractionResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/DocumentExtractionTaskItem"},"type":"array","title":"Data","description":"List of document extraction tasks with their status"}},"type":"object","required":["data"],"title":"BulkDocumentExtractionResponse","description":"Response schema for bulk document extraction"},"BulkDocumentStatusRequest":{"properties":{"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"Client ID for the documents"},"document_ids":{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":100,"minItems":1,"title":"Document Ids","description":"List of document IDs to check status for"}},"type":"object","required":["client_id","document_ids"],"title":"BulkDocumentStatusRequest","description":"Request schema for bulk document status polling"},"BulkFolderDeleteRequest":{"properties":{"folder_ids":{"items":{"type":"string","format":"uuid"},"type":"array","minItems":1,"title":"Folder Ids","description":"List of folder IDs to delete"},"reason":{"type":"string","minLength":1,"title":"Reason","description":"Reason for deleting folders"},"cascade_delete":{"type":"boolean","title":"Cascade Delete","description":"Whether to delete all contents (subfolders and documents) within the folders","default":true}},"type":"object","required":["folder_ids","reason"],"title":"BulkFolderDeleteRequest","description":"Request schema for bulk folder deletion"},"BulkImportResponse":{"properties":{"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of rows processed","example":10},"successful":{"type":"integer","minimum":0.0,"title":"Successful","description":"Number of successfully imported clients","example":8},"failed":{"type":"integer","minimum":0.0,"title":"Failed","description":"Number of failed imports","example":2},"errors":{"items":{"$ref":"#/components/schemas/ImportError"},"type":"array","title":"Errors","description":"List of import errors"},"imported_clients":{"items":{"$ref":"#/components/schemas/ImportedClientInfo"},"type":"array","title":"Imported Clients","description":"List of successfully imported clients"}},"type":"object","required":["total","successful","failed"],"title":"BulkImportResponse","description":"Schema for bulk import response","example":{"errors":[{"error":"Invalid email format","external_id":"RJ003","row":3}],"failed":2,"imported_clients":[{"external_id":"RJ001","full_name":"John Doe","id":"123e4567-e89b-12d3-a456-426614174000","readable_id":"CL-000001"}],"successful":8,"total":10}},"BulkMixedDeleteRequest":{"properties":{"folder_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Folder Ids","description":"List of folder IDs to delete"},"document_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Document Ids","description":"List of document IDs to delete"},"reason":{"type":"string","title":"Reason","description":"Reason for deletion"},"cascade_delete":{"type":"boolean","title":"Cascade Delete","description":"Whether to delete all contents within folders","default":true}},"type":"object","required":["reason"],"title":"BulkMixedDeleteRequest","description":"Request schema for mixed bulk deletion (folders + documents)"},"BulkMoveRequest":{"properties":{"folder_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Folder Ids","description":"List of folder IDs to move"},"document_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Document Ids","description":"List of document IDs to move"},"target_folder_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Target Folder Id","description":"Target folder ID (null for root folder)"},"reason":{"type":"string","title":"Reason","description":"Reason for moving folders/documents"},"auto_rename_on_conflict":{"type":"boolean","title":"Auto Rename On Conflict","description":"Auto-rename folders/documents if name conflicts in target folder (e.g., folder(1), file(1).pdf). Default is True.","default":true}},"type":"object","required":["target_folder_id","reason"],"title":"BulkMoveRequest","description":"Request schema for bulk move operations (folders and/or documents)"},"BulkOperationDetails":{"properties":{"folders_deleted":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Folders Deleted","description":"Number of folders successfully deleted (bulk-delete only)","example":5},"folders_failed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Folders Failed","description":"Number of folders that failed (delete or move)","example":2},"documents_deleted":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Documents Deleted","description":"Number of documents successfully deleted (bulk-delete only)","example":15},"documents_failed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Documents Failed","description":"Number of documents that failed (delete or move)","example":1},"folders_moved":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Folders Moved","description":"Number of folders in the move request / successfully moved (bulk-move only)","example":1},"documents_moved":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Documents Moved","description":"Number of documents in the move request / successfully moved (bulk-move only)","example":1}},"type":"object","title":"BulkOperationDetails","description":"Detailed breakdown of bulk operation results. Uses *_deleted for delete ops, *_moved for move ops.","example":{"documents_deleted":15,"documents_failed":1,"folders_deleted":5,"folders_failed":2}},"BulkOperationError":{"properties":{"entity_id":{"type":"string","title":"Entity Id","description":"UUID of the entity (folder or document) that failed","example":"123e4567-e89b-12d3-a456-426614174000"},"entity_type":{"type":"string","title":"Entity Type","description":"Type of entity (folder or document)","example":"folder"},"entity_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Name","description":"Name of the entity that failed (if available)","example":"Tax Documents 2024"},"error":{"type":"string","title":"Error","description":"Error message describing why the operation failed","example":"Folder is not empty. Use cascade_delete=true to delete contents."}},"type":"object","required":["entity_id","entity_type","error"],"title":"BulkOperationError","description":"Error details for a failed bulk operation item","examples":[{"entity_id":"123e4567-e89b-12d3-a456-426614174000","entity_name":"Tax Documents 2024","entity_type":"folder","error":"Folder is not empty. Use cascade_delete=true to delete contents."},{"entity_id":"987fcdeb-51a2-43f7-b890-123456789abc","entity_name":"W2_Form.pdf","entity_type":"document","error":"Document is locked and cannot be deleted."}]},"BulkOperationResponse":{"properties":{"success_count":{"type":"integer","title":"Success Count","description":"Number of successful operations","example":18},"failure_count":{"type":"integer","title":"Failure Count","description":"Number of failed operations","example":3},"total_count":{"type":"integer","title":"Total Count","description":"Total number of operations attempted","example":21},"errors":{"items":{"$ref":"#/components/schemas/BulkOperationError"},"type":"array","title":"Errors","description":"List of errors with detailed information about each failed operation"},"details":{"anyOf":[{"$ref":"#/components/schemas/BulkOperationDetails"},{"type":"null"}],"description":"Detailed breakdown of operations by type (folders vs documents)"},"renamed_documents":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/RenamedDocumentInfo"},"type":"object"},{"type":"null"}],"title":"Renamed Documents","description":"Documents that were auto-renamed due to conflicts. Key: document_id (str), Value: RenamedDocumentInfo","example":{"123e4567-e89b-12d3-a456-426614174000":{"new_name":"invoice(1).pdf","old_name":"invoice.pdf"}}},"renamed_folders":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/RenamedDocumentInfo"},"type":"object"},{"type":"null"}],"title":"Renamed Folders","description":"Folders that were auto-renamed due to conflicts. Key: folder_id (str), Value: RenamedDocumentInfo","example":{"223e4567-e89b-12d3-a456-426614174001":{"new_name":"Tax Documents(1)","old_name":"Tax Documents"}}},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Non-fatal warnings surfaced to the CPA. For move operations: populated when any moved item lands inside a shared folder, meaning the client immediately gains access to those items."}},"type":"object","required":["success_count","failure_count","total_count"],"title":"BulkOperationResponse","description":"Response schema for bulk operations","example":{"details":{"documents_deleted":13,"documents_failed":1,"folders_deleted":5,"folders_failed":2},"errors":[{"entity_id":"123e4567-e89b-12d3-a456-426614174000","entity_name":"Tax Documents 2024","entity_type":"folder","error":"Folder is not empty. Use cascade_delete=true to delete contents."},{"entity_id":"987fcdeb-51a2-43f7-b890-123456789abc","entity_name":"W2_Form.pdf","entity_type":"document","error":"Document is locked and cannot be deleted."}],"failure_count":3,"success_count":18,"total_count":21}},"BundleSummary":{"properties":{"total":{"type":"integer","title":"Total","description":"Number of child forms in the bundle."},"in_progress":{"type":"integer","title":"In Progress","description":"Children still extracting (or not yet started)."},"ready":{"type":"integer","title":"Ready","description":"Children successfully extracted (ready for review)."},"failed":{"type":"integer","title":"Failed","description":"Children that failed or are unsupported (need CPA action)."},"ignored":{"type":"integer","title":"Ignored","description":"Children dismissed by a human as non-tax forms (SKIPPED)."}},"type":"object","required":["total","in_progress","ready","failed","ignored"],"title":"BundleSummary","description":"Coverage ledger for a multi-form BUNDLE — the rollup of its children's statuses.\n\nRendered by the FE as a chip (✓ ready · ⚠ failed · — ignored). Present only on BUNDLE rows."},"BundleTieOutResponse":{"properties":{"parent_document_id":{"type":"string","format":"uuid","title":"Parent Document Id"},"has_statement_total":{"type":"boolean","title":"Has Statement Total"},"forms":{"items":{"$ref":"#/components/schemas/FormTieOut"},"type":"array","title":"Forms"}},"type":"object","required":["parent_document_id","has_statement_total","forms"],"title":"BundleTieOutResponse"},"CalculationStep":{"properties":{"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label","description":"Human-readable label (e.g. 20%, Schedule C Line 31)"},"value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"null"}],"title":"Value","description":"Numeric or display value for this step"},"operator":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operator","description":"Between this step and next: *, +, =, etc."},"step_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Step Type","description":"Trace step type: input, intermediate, decision, election, bracket, phaseout, limit, override, result, review, skip"},"source":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Source","description":"TraceSource dict — clickable reference to origin"},"expr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expr","description":"Arithmetic expression (e.g. '$85,000 − $14,600')"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Reason for a decision"},"decision_result":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Decision Result","description":"Decision outcome: True/False"},"chosen":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chosen","description":"Election: what was chosen"},"alternative":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alternative","description":"Election: what the alternative was"},"savings":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Savings","description":"Election: quantified impact of the choice"},"authority":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authority","description":"IRC/legal citation (e.g. 'IRC 63(a)')"},"rate":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rate","description":"Tax bracket rate (e.g. '15%')"},"bracket_lower":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Bracket Lower","description":"Tax bracket lower bound"},"bracket_upper":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Bracket Upper","description":"Tax bracket upper bound"},"raw_amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Raw Amount","description":"Pre-limit/phaseout amount"},"limit_amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Limit Amount","description":"Statutory limit amount"},"threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Threshold","description":"Phaseout threshold"},"reduction":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Reduction","description":"Phaseout reduction amount"},"original_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original Value","description":"Override: computed value before override"},"overridden_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Overridden Value","description":"Override: preparer's value"},"override_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Override Reason","description":"Override: preparer's reason"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code","description":"Review step only: stable machine identifier, e.g. 'SCH_A_5B_ESCROW_OVERLAP'. Needed to dedupe or suppress from the breakdown alone."},"severity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Severity","description":"Review step only: 'high' | 'medium' | 'low'. Advisory — see LineDetail.review_severity."},"resolution_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolution Hint","description":"Review step only: the concrete action a preparer takes to clear the flag."},"is_auto":{"type":"boolean","title":"Is Auto","description":"True if auto-captured by proxy, not manually annotated","default":false}},"type":"object","title":"CalculationStep","description":"One step in a calculation breakdown (e.g. 0.2 × 25000 = 5000).\n\nBackward-compatible: existing fields (label, value, operator) are preserved.\nNew trace-derived fields are all optional with defaults."},"ChildDocumentSummary":{"properties":{"document_id":{"type":"string","format":"uuid","title":"Document Id"},"chunk_id":{"type":"string","format":"uuid","title":"Chunk Id"},"form_type":{"type":"string","title":"Form Type"},"issuer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issuer","description":"Issuer/payer of this form, if known."},"document_type_identifier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Type Identifier","description":"Canonical identifier (e.g. FORM_1099_INT); None for an UNSUPPORTED child."},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"page_start":{"type":"integer","title":"Page Start"},"page_end":{"type":"integer","title":"Page End"},"extraction_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extraction Status","description":"Initial extraction status (PENDING on materialization); uses the BulkStatus vocabulary."}},"type":"object","required":["document_id","chunk_id","form_type","page_start","page_end"],"title":"ChildDocumentSummary","description":"A materialized split child, for the FE BundleReview list + per-child polling."},"CitiesResponse":{"properties":{"state_code":{"type":"string","maxLength":2,"minLength":2,"title":"State Code","description":"Two-letter state code","example":"NY"},"state_name":{"type":"string","maxLength":255,"title":"State Name","description":"Full name of the state","example":"New York"},"cities":{"items":{"$ref":"#/components/schemas/CityListItem"},"type":"array","title":"Cities","description":"List of cities in the state","example":[{"name":"New York"},{"name":"Buffalo"}]},"count":{"type":"integer","title":"Count","description":"Total number of cities in the state","example":100},"meta":{"anyOf":[{"$ref":"#/components/schemas/app__schemas__common__pagination__PaginationMeta"},{"type":"null"}],"description":"Pagination metadata (only present when pagination is used)"}},"type":"object","required":["state_code","state_name","cities","count"],"title":"CitiesResponse","description":"Cities available for a given state code with pagination support.","example":{"cities":[{"name":"New York"},{"name":"Buffalo"}],"count":100,"meta":{"page":1,"page_size":20,"total_count":100,"total_pages":5},"state_code":"NY","state_name":"New York"}},"CityListItem":{"properties":{"name":{"type":"string","maxLength":255,"title":"Name","description":"Name of the city","example":"New York"}},"type":"object","required":["name"],"title":"CityListItem","description":"Readable summary of a city for lists and dropdowns.\nNote: external_id is intentionally not exposed in API responses.","example":{"name":"New York"}},"ClearsAtRole":{"type":"string","enum":["PREPARER","REVIEWER","PARTNER"],"title":"ClearsAtRole","description":"Which role's phase owns a flag (drives the readiness gate + reopen-targeting). The resolving\nrole (who dispositioned it) uses the same three roles."},"ClientAddressCreate":{"properties":{"street_address":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Street Address","description":"Street address"},"address_line_2":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Address Line 2","description":"Additional address information"},"city":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"City","description":"City"},"state":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"State","description":"State"},"zip_code":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Zip Code","description":"ZIP code"}},"type":"object","title":"ClientAddressCreate","description":"Address information for client creation"},"ClientAddressesResponse":{"properties":{"primary_address":{"anyOf":[{"$ref":"#/components/schemas/app__schemas__client__address__AddressResponse"},{"type":"null"}],"description":"The client's primary residential address"},"mailing_address":{"anyOf":[{"$ref":"#/components/schemas/app__schemas__client__address__AddressResponse"},{"type":"null"}],"description":"The client's mailing address (may be same as primary)"},"same_mailing_address":{"type":"boolean","title":"Same Mailing Address","description":"Indicates if mailing address is same as primary address","default":false}},"type":"object","title":"ClientAddressesResponse","example":{"mailing_address":{"address_line_2":"Suite 200","city":"Los Angeles","id":"660f9511-f39c-52e5-b827-557766551111","state":"CA","street_address":"456 Business Blvd","zip_code":"90210"},"primary_address":{"address_line_2":"Apt 4B","city":"New York","id":"550e8400-e29b-41d4-a716-446655440000","state":"NY","street_address":"123 Main Street","zip_code":"10001"},"same_mailing_address":false}},"ClientAddressesUpdate":{"properties":{"primary_address":{"$ref":"#/components/schemas/AddressCreate","description":"Primary residential address (required for all clients)"},"mailing_address":{"anyOf":[{"$ref":"#/components/schemas/AddressCreate"},{"type":"null"}],"description":"Mailing address (optional - if different from primary address)"},"same_mailing_address":{"type":"boolean","title":"Same Mailing Address","description":"Set to true to use primary address as mailing address","default":false}},"type":"object","required":["primary_address"],"title":"ClientAddressesUpdate","example":{"mailing_address":{"address_line_2":"Suite 200","city":"Los Angeles","state":"CA","street_address":"456 Business Blvd","zip_code":"90210"},"primary_address":{"address_line_2":"Apt 4B","city":"New York","state":"NY","street_address":"123 Main Street","zip_code":"10001"},"same_mailing_address":false}},"ClientAutocompleteItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Client UUID"},"full_name":{"type":"string","title":"Full Name","description":"Client's full name"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Client's email address"},"readable_id":{"type":"string","title":"Readable Id","description":"Client's readable ID (e.g., CL-000001)"}},"type":"object","required":["id","full_name","email","readable_id"],"title":"ClientAutocompleteItem","description":"Simplified client response for autocomplete"},"ClientAutocompleteResponse":{"properties":{"clients":{"items":{"$ref":"#/components/schemas/ClientAutocompleteItem"},"type":"array","title":"Clients","description":"List of matching clients"}},"type":"object","required":["clients"],"title":"ClientAutocompleteResponse","description":"Response for client autocomplete endpoint"},"ClientCreate":{"properties":{"full_name":{"type":"string","maxLength":255,"minLength":1,"title":"Full Name","description":"Full legal name of the client (required)","example":"John Doe"},"external_id":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"External Id","description":"External client ID from external system (optional)","example":"CLIENT-12345"},"filing_type":{"anyOf":[{"$ref":"#/components/schemas/FilingTypeEnum"},{"type":"null"}],"description":"Filing type: Individual (1040) or Solo (Schedule C)","example":"INDIVIDUAL_1040"},"filing_status":{"anyOf":[{"$ref":"#/components/schemas/FilingStatusEnum"},{"type":"null"}],"description":"Filing status","example":"SINGLE"},"blind":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Blind","description":"Is the client blind?","default":false,"example":false},"disabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Disabled","description":"Is the client disabled?","default":false,"example":false},"ssn":{"anyOf":[{"type":"string","maxLength":11,"minLength":9},{"type":"null"}],"title":"Ssn","description":"Social Security Number (optional - will be encrypted and stored securely if provided)","example":"123-45-6789"},"date_of_birth":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date Of Birth","description":"Date of birth in YYYY-MM-DD format (optional)","example":"1990-01-15"},"address":{"anyOf":[{"$ref":"#/components/schemas/ClientAddressCreate"},{"type":"null"}],"description":"Primary address information (optional)"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Email address for communication (optional)","example":"john.doe@example.com"},"phone":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Phone","description":"Phone number with country code (optional)","example":"+1-555-123-4567"},"spouse":{"anyOf":[{"$ref":"#/components/schemas/SpouseCreate"},{"type":"null"}],"description":"Spouse information (optional)"},"dependents":{"anyOf":[{"items":{"$ref":"#/components/schemas/DependentCreate"},"type":"array"},{"type":"null"}],"title":"Dependents","description":"List of dependents (optional)"}},"type":"object","required":["full_name"],"title":"ClientCreate","description":"Schema for creating a new client.\n\nContains all the information needed to create a client record including address.\nOnly full name is mandatory; all other fields are optional.","example":{"address":{"city":"New York","state":"NY","street_address":"123 Main Street","zip_code":"10001"},"blind":false,"date_of_birth":"1990-01-15","disabled":false,"email":"john.doe@example.com","external_id":"CLIENT-12345","filing_status":"SINGLE","filing_type":"INDIVIDUAL_1040","full_name":"John Doe","phone":"+1-555-123-4567","ssn":"123-45-6789"}},"ClientLinkResponse":{"properties":{"upload_url":{"type":"string","title":"Upload Url","description":"Public upload URL for clients"},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"When the upload link expires"},"status":{"$ref":"#/components/schemas/IntakeRequestStatus","description":"Current status of the request"},"status_label":{"type":"string","title":"Status Label","description":"Human-readable status for UI display.","readOnly":true}},"type":"object","required":["upload_url","expires_at","status","status_label"],"title":"ClientLinkResponse","description":"Schema for client link response"},"ClientListResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"readable_id":{"type":"string","title":"Readable Id"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id"},"full_name":{"type":"string","title":"Full Name"},"filing_type":{"anyOf":[{"$ref":"#/components/schemas/FilingTypeResponse"},{"type":"null"}]},"filing_status":{"anyOf":[{"$ref":"#/components/schemas/FilingStatusResponse"},{"type":"null"}]},"blind":{"type":"boolean","title":"Blind"},"disabled":{"type":"boolean","title":"Disabled"},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Email"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"status":{"$ref":"#/components/schemas/StatusEnum"},"ssn_info":{"anyOf":[{"$ref":"#/components/schemas/SSNInfoResponse"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","readable_id","external_id","full_name","filing_type","filing_status","blind","disabled","email","phone","status","ssn_info","created_at","updated_at"],"title":"ClientListResponse"},"ClientResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"readable_id":{"type":"string","title":"Readable Id"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id"},"tenant_id":{"type":"string","format":"uuid","title":"Tenant Id"},"full_name":{"type":"string","title":"Full Name"},"filing_type":{"anyOf":[{"$ref":"#/components/schemas/FilingTypeResponse"},{"type":"null"}]},"filing_status":{"anyOf":[{"$ref":"#/components/schemas/FilingStatusResponse"},{"type":"null"}]},"blind":{"type":"boolean","title":"Blind"},"disabled":{"type":"boolean","title":"Disabled"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"date_of_birth":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date Of Birth"},"status":{"$ref":"#/components/schemas/StatusEnum"},"ssn_info":{"anyOf":[{"$ref":"#/components/schemas/SSNInfoResponse"},{"type":"null"}]},"primary_address":{"anyOf":[{"$ref":"#/components/schemas/app__schemas__client__client__AddressResponse"},{"type":"null"}]},"mailing_address":{"anyOf":[{"$ref":"#/components/schemas/app__schemas__client__client__AddressResponse"},{"type":"null"}]},"spouse":{"anyOf":[{"$ref":"#/components/schemas/SpouseResponse"},{"type":"null"}]},"dependents":{"items":{"$ref":"#/components/schemas/DependentResponse"},"type":"array","title":"Dependents","default":[]},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","readable_id","external_id","tenant_id","full_name","filing_type","filing_status","blind","disabled","email","phone","date_of_birth","status","ssn_info","primary_address","mailing_address","created_at","updated_at"],"title":"ClientResponse"},"ClientSearchRequest":{"properties":{"search_query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search Query","description":"Search by name, email, or readable_id"},"status":{"anyOf":[{"$ref":"#/components/schemas/StatusEnum"},{"type":"null"}],"description":"Filter by status"},"filing_type":{"anyOf":[{"$ref":"#/components/schemas/FilingTypeEnum"},{"type":"null"}],"description":"Filter by filing type"},"filing_status":{"anyOf":[{"$ref":"#/components/schemas/FilingStatusEnum"},{"type":"null"}],"description":"Filter by filing status"},"page":{"type":"integer","minimum":1.0,"title":"Page","description":"Page number","default":1},"page_size":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Page Size","description":"Items per page","default":20},"sort_by":{"type":"string","title":"Sort By","description":"Sort field (created_at, name, email, readable_id, filing_type, filing_status)","default":"created_at"},"sort_order":{"type":"string","title":"Sort Order","description":"Sort order (asc, desc)","default":"desc"}},"type":"object","title":"ClientSearchRequest","description":"Client-specific search request extending generic pagination"},"ClientSearchResponse":{"properties":{"clients":{"items":{"$ref":"#/components/schemas/ClientListResponse"},"type":"array","title":"Clients","description":"List of clients"},"meta":{"$ref":"#/components/schemas/app__schemas__common__pagination__PaginationMeta","description":"Pagination metadata"}},"type":"object","required":["clients","meta"],"title":"ClientSearchResponse","description":"Client-specific search response using generic pagination structure with meta object"},"ClientSortField":{"type":"string","enum":["created_at","name","email","readable_id","filing_type","filing_status"],"title":"ClientSortField","description":"Client sort field enumeration"},"ClientUpdate":{"properties":{"full_name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Full Name"},"external_id":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"External Id"},"filing_type":{"anyOf":[{"$ref":"#/components/schemas/FilingTypeEnum"},{"type":"null"}]},"filing_status":{"anyOf":[{"$ref":"#/components/schemas/FilingStatusEnum"},{"type":"null"}]},"blind":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Blind"},"disabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Disabled"},"ssn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ssn","description":"SSN to update (will be encrypted)"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"phone":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Phone"},"date_of_birth":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date Of Birth"},"address":{"anyOf":[{"$ref":"#/components/schemas/ClientAddressCreate"},{"type":"null"}]},"mailing_address":{"anyOf":[{"$ref":"#/components/schemas/ClientAddressCreate"},{"type":"null"}]},"spouse":{"anyOf":[{"$ref":"#/components/schemas/SpouseUpdate"},{"type":"null"}],"description":"Spouse information to create or update"},"dependents":{"anyOf":[{"items":{"$ref":"#/components/schemas/DependentUpdate"},"type":"array"},{"type":"null"}],"title":"Dependents","description":"List of dependents to create or update"},"status":{"anyOf":[{"$ref":"#/components/schemas/StatusEnum"},{"type":"null"}]}},"type":"object","title":"ClientUpdate"},"ConfirmMatchRequest":{"properties":{"item_upload_id":{"type":"string","format":"uuid","title":"Item Upload Id","description":"ID of the intake request upload to move (tenant_client_intake_request_uploads.id)"},"suggested_item_id":{"type":"string","format":"uuid","title":"Suggested Item Id","description":"ID of the suggested item to move the upload to"}},"type":"object","required":["item_upload_id","suggested_item_id"],"title":"ConfirmMatchRequest","description":"Schema for confirming a match suggestion"},"ConfirmMatchResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether the match was confirmed successfully","default":true},"message":{"type":"string","title":"Message","description":"Success message","example":"Match confirmed and upload moved successfully"},"item_upload_id":{"type":"string","format":"uuid","title":"Item Upload Id","description":"ID of the upload that was moved"},"new_item_id":{"type":"string","format":"uuid","title":"New Item Id","description":"ID of the item the upload was moved to"}},"type":"object","required":["message","item_upload_id","new_item_id"],"title":"ConfirmMatchResponse","description":"Schema for confirm match response"},"ConfirmSplitRequest":{"properties":{"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"Client the bundle belongs to (tenant comes from the JWT)."},"forms":{"items":{"$ref":"#/components/schemas/DetectedFormInput"},"type":"array","minItems":1,"title":"Forms","description":"The confirmed form segments."}},"type":"object","required":["client_id","forms"],"title":"ConfirmSplitRequest","description":"The validated breakup the CPA confirmed. Server re-validates coverage/caps/K-1 before slicing.","example":{"client_id":"…","forms":[{"form_type":"W-2","page_end":2,"page_start":1},{"form_type":"1099-INT","page_end":5,"page_start":3}]}},"ConfirmSplitResponse":{"properties":{"parent_document_id":{"type":"string","format":"uuid","title":"Parent Document Id"},"child_documents":{"items":{"$ref":"#/components/schemas/ChildDocumentSummary"},"type":"array","title":"Child Documents"}},"type":"object","required":["parent_document_id","child_documents"],"title":"ConfirmSplitResponse"},"ConversationBookmarkRequest":{"properties":{"is_bookmarked":{"type":"boolean","title":"Is Bookmarked","description":"Whether to bookmark (True) or unbookmark (False) the conversation"}},"type":"object","required":["is_bookmarked"],"title":"ConversationBookmarkRequest","description":"Request schema for bookmarking/unbookmarking a conversation.","example":{"is_bookmarked":true}},"ConversationBookmarkResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Status of the bookmark operation"},"conversation_id":{"type":"string","format":"uuid","title":"Conversation Id","description":"ID of the bookmarked/unbookmarked conversation"},"is_bookmarked":{"type":"boolean","title":"Is Bookmarked","description":"Current bookmark status of the conversation"}},"type":"object","required":["status","conversation_id","is_bookmarked"],"title":"ConversationBookmarkResponse","description":"Response schema for conversation bookmark operation.","example":{"conversation_id":"123e4567-e89b-12d3-a456-426614174000","is_bookmarked":true,"status":"SUCCESS"}},"ConversationListResponse":{"properties":{"status":{"type":"string","title":"Status"},"page":{"type":"integer","title":"Page"},"limit":{"type":"integer","title":"Limit"},"total_conversations":{"type":"integer","title":"Total Conversations"},"total_pages":{"type":"integer","title":"Total Pages"},"conversations":{"items":{"$ref":"#/components/schemas/ConversationSummary"},"type":"array","title":"Conversations"}},"type":"object","required":["status","page","limit","total_conversations","total_pages","conversations"],"title":"ConversationListResponse","description":"Response model for the conversations listing API."},"ConversationMessage":{"properties":{"message_id":{"type":"string","format":"uuid","title":"Message Id","description":"Unique identifier for the message"},"sender":{"$ref":"#/components/schemas/MessageSender","description":"Who sent the message (USER/SYSTEM)"},"message_type":{"$ref":"#/components/schemas/MessageType","description":"Type of message (USER/SYSTEM)"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Plain text message content"},"markdown_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Markdown Message","description":"Markdown formatted message content"},"sequence_number":{"type":"integer","minimum":1.0,"title":"Sequence Number","description":"Message sequence number in conversation"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the message was created"},"rating":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rating","description":"User rating (UP/DOWN) if rated"},"comment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment","description":"User comment with rating if provided"},"status":{"$ref":"#/components/schemas/MessageStatus","description":"Current status of the message"},"is_user_input_required":{"type":"boolean","title":"Is User Input Required","description":"Whether user input is required","default":false},"citations":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Citations","description":"Citations and references for the message"}},"type":"object","required":["message_id","sender","message_type","sequence_number","created_at","status"],"title":"ConversationMessage","description":"Individual message in a conversation."},"ConversationMessagesResponse":{"properties":{"status":{"type":"string","title":"Status"},"conversation_id":{"type":"string","format":"uuid","title":"Conversation Id"},"conversation_type":{"$ref":"#/components/schemas/ConversationType"},"page":{"type":"integer","title":"Page"},"limit":{"type":"integer","title":"Limit"},"total_messages":{"type":"integer","title":"Total Messages"},"total_pages":{"type":"integer","title":"Total Pages"},"messages":{"items":{"$ref":"#/components/schemas/ConversationMessage"},"type":"array","title":"Messages"}},"type":"object","required":["status","conversation_id","conversation_type","page","limit","total_messages","total_pages","messages"],"title":"ConversationMessagesResponse","description":"Response model for conversation messages only."},"ConversationMetadataResponse":{"properties":{"conversation_id":{"type":"string","format":"uuid","title":"Conversation Id"},"conversation_type":{"$ref":"#/components/schemas/ConversationType"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"last_updated_at":{"type":"string","format":"date-time","title":"Last Updated At"},"message_count":{"type":"integer","title":"Message Count"},"last_user_message_preview":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last User Message Preview"},"last_response_preview":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Response Preview"},"status":{"$ref":"#/components/schemas/ConversationStatus"},"is_bookmarked":{"type":"boolean","title":"Is Bookmarked","default":false}},"type":"object","required":["conversation_id","conversation_type","created_at","last_updated_at","message_count","status"],"title":"ConversationMetadataResponse","description":"Response model for conversation metadata (same as single item from conversations list)."},"ConversationStatus":{"type":"string","enum":["ACTIVE","ARCHIVED","DELETED"],"title":"ConversationStatus"},"ConversationSummary":{"properties":{"conversation_id":{"type":"string","format":"uuid","title":"Conversation Id"},"conversation_type":{"$ref":"#/components/schemas/ConversationType"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"last_updated_at":{"type":"string","format":"date-time","title":"Last Updated At"},"message_count":{"type":"integer","title":"Message Count"},"last_user_message_preview":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last User Message Preview"},"last_response_preview":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Response Preview"},"status":{"$ref":"#/components/schemas/ConversationStatus"},"is_bookmarked":{"type":"boolean","title":"Is Bookmarked","default":false}},"type":"object","required":["conversation_id","conversation_type","created_at","last_updated_at","message_count","status"],"title":"ConversationSummary","description":"Summary information for a single conversation in the list."},"ConversationType":{"type":"string","enum":["TAX_RESEARCH","STATE_TAX_RESEARCH","GENERAL","INVOICE_HELP","TEMPLATE_HELP"],"title":"ConversationType"},"ConversionReason":{"type":"string","enum":["RETIRED_TYPE","LEGACY_EXTRACTION"],"title":"ConversionReason","description":"Why a document is being offered a conversion to the new extraction system.\n\n* ``RETIRED_TYPE`` — the document sits on a type that has been superseded (the legacy P&L,\n  the Schedule C worksheet, the K-1 envelope, an older Schedule K-1 spelling). Moving it is\n  a genuine type change.\n* ``LEGACY_EXTRACTION`` — the type is already correct and already on the new flow, but THIS\n  document's values came from the old extractor because it was processed before the doctype\n  was flipped. Nothing to change but the extraction, which is why it needs ``force``."},"CorrectionConsequenceOut":{"properties":{"line_key":{"type":"string","title":"Line Key","description":"The corrected line that caused it."},"label":{"type":"string","title":"Label","description":"What is now out of date, in the preparer's language."},"detail":{"type":"string","title":"Detail","description":"What specifically is wrong, and why."},"question_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Question Code","description":"The questionnaire code to open, when the consequence has one. None where the consequence is real but has no single field — the e-file signature AGI is not a questionnaire answer."}},"type":"object","required":["line_key","label","detail"],"title":"CorrectionConsequenceOut","description":"Something downstream a correction invalidated and we did not fix."},"CreateApiKeyRequest":{"properties":{"label":{"type":"string","maxLength":120,"minLength":1,"title":"Label","description":"How this key will be identified later, e.g. 'Perplexity — tax team'. The secret is never shown again, so the label is the only way to tell two keys apart when deciding what to revoke.","example":"Perplexity — tax team"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At","description":"Optional expiry. Omit for a key that lasts until revoked."}},"additionalProperties":false,"type":"object","required":["label"],"title":"CreateApiKeyRequest"},"CreateApiKeyResponse":{"properties":{"api_key":{"type":"string","title":"Api Key","description":"The full credential. Copy it now — the Owner can read it back later from the key list, but nobody else can, and every read-back is recorded."},"key":{"$ref":"#/components/schemas/ApiKeySummary"}},"additionalProperties":false,"type":"object","required":["api_key","key"],"title":"CreateApiKeyResponse","description":"The ONLY response that ever carries the plaintext key."},"CreateFigureOverrideRequest":{"properties":{"line_key":{"type":"string","title":"Line Key","description":"Which headline line — a `HeadlineConcept` value, the same key the comparison row and the intake panel's FIGURE fact carry."},"value_text":{"type":"string","title":"Value Text","description":"The corrected figure, as TEXT. Sent and stored as text so a float round-trip cannot turn $76,333.00 into $76,332.99 on a table whose entire value is that it agrees with the paper."},"extracted_value_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extracted Value Text","description":"What was on screen when the preparer decided — the value they disagreed with. Ignored on a re-correction, where the ORIGINAL machine read is carried forward instead: recording the previous correction here would erase the only account of what the run saw."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Required only where the extraction was CONFIDENT about this line and still wrong. From a closed list — 'it looks wrong' is not on it, because a preparer who believes the prior RETURN is wrong has a different and legitimate path and a free-text box would collect that case as a correction and lose it."},"observed_source_page":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Observed Source Page","description":"The page they read it off, if they said. Never inferred."},"supersedes_override_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Supersedes Override Id","description":"Advisory. The server retires whatever is CURRENT for the line rather than trusting this: a stale id from a panel that has not reloaded would otherwise retire a row that is no longer live and leave two corrections standing, which the unique index then refuses with an error naming neither."}},"type":"object","required":["line_key","value_text"],"title":"CreateFigureOverrideRequest","description":"A preparer's correction to one prior-year figure."},"CurrentFolderInfo":{"properties":{"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Id"},"name":{"type":"string","title":"Name"},"path":{"type":"string","title":"Path"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"breadcrumb":{"items":{"$ref":"#/components/schemas/BreadcrumbItem"},"type":"array","title":"Breadcrumb"},"total_size":{"type":"integer","title":"Total Size","default":0},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","name","path","description","breadcrumb","created_at"],"title":"CurrentFolderInfo"},"DMSShareCreateRequest":{"properties":{"resource_type":{"$ref":"#/components/schemas/DMSShareResourceTypeEnum","description":"Type of resource to share: FOLDER or DOCUMENT"},"resource_id":{"type":"string","format":"uuid","title":"Resource Id","description":"UUID of the folder or document to share"}},"type":"object","required":["resource_type","resource_id"],"title":"DMSShareCreateRequest","description":"Request body for sharing a DMS resource with the client in the URL path."},"DMSShareListResponse":{"properties":{"shares":{"items":{"$ref":"#/components/schemas/DMSShareResponse"},"type":"array","title":"Shares","description":"List of active share records"},"total":{"type":"integer","title":"Total","description":"Total number of active shares for this resource"}},"type":"object","required":["total"],"title":"DMSShareListResponse","description":"Paginated list of shares for a resource (CPA view)."},"DMSShareResourceTypeEnum":{"type":"string","enum":["FOLDER","DOCUMENT"],"title":"DMSShareResourceTypeEnum"},"DMSShareResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique share record ID"},"resource_type":{"$ref":"#/components/schemas/DMSShareResourceTypeEnum","description":"Type of the shared resource: FOLDER or DOCUMENT"},"resource_id":{"type":"string","format":"uuid","title":"Resource Id","description":"UUID of the shared resource"},"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"UUID of the client this resource is shared with"},"shared_with_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shared With Email","description":"Email of the recipient — resolved internally from TenantClient.email at creation time. Never accepted as API input."},"shared_by":{"type":"string","title":"Shared By","description":"CPA user ID who created the share"},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the share is currently active"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when the share was created"},"revoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Revoked At","description":"Timestamp when the share was revoked, if applicable"}},"type":"object","required":["id","resource_type","resource_id","client_id","shared_by","is_active","created_at"],"title":"DMSShareResponse","description":"Response returned to CPA after creating or fetching a share."},"Dependencies":{"properties":{"questions":{"items":{"$ref":"#/components/schemas/QuestionRef"},"type":"array","title":"Questions","description":"Questionnaire items"},"documents":{"items":{"$ref":"#/components/schemas/DocumentRef"},"type":"array","title":"Documents","description":"Document types"},"form_lines":{"items":{"$ref":"#/components/schemas/FormLineRef"},"type":"array","title":"Form Lines","description":"Form lines"}},"type":"object","title":"Dependencies","description":"What a form or line depends on (questions, documents, form lines)."},"DependentCreate":{"properties":{"full_name":{"type":"string","maxLength":255,"title":"Full Name","description":"Full legal name of the dependent","example":"John Doe Jr."},"date_of_birth":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date Of Birth","description":"Date of birth in YYYY-MM-DD format (optional but recommended for tax purposes)","example":"2010-05-15"},"blind":{"type":"boolean","title":"Blind","description":"Is the dependent blind for tax deduction purposes","default":false,"example":false},"disabled":{"type":"boolean","title":"Disabled","description":"Is the dependent disabled for tax deduction purposes","default":false,"example":false},"relationship_type":{"$ref":"#/components/schemas/RelationshipEnum","description":"Relationship to the primary client","example":"SON"},"relationship_other":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Relationship Other","description":"Custom relationship description for additional context","example":"Step-sister"},"months_in_home":{"anyOf":[{"type":"integer","maximum":12.0,"minimum":1.0},{"type":"null"}],"title":"Months In Home","description":"Number of months the dependent lived in the home during the tax year (1-12)","example":12},"full_time_student":{"type":"boolean","title":"Full Time Student","description":"Whether the dependent is a full-time student","default":false,"example":false},"ssn":{"anyOf":[{"type":"string","maxLength":11,"minLength":9},{"type":"null"}],"title":"Ssn","description":"Social Security Number (will be encrypted and stored securely)","example":"123-45-6789"}},"type":"object","required":["full_name","relationship_type"],"title":"DependentCreate","description":"Schema for creating a new dependent.\n\nIncludes all dependent information for tax filing purposes.","example":{"blind":false,"date_of_birth":"2010-05-15","disabled":false,"full_name":"John Doe Jr.","relationship_type":"SON","ssn":"123-45-6789"}},"DependentListResponse":{"properties":{"dependents":{"items":{"$ref":"#/components/schemas/DependentResponse"},"type":"array","title":"Dependents","description":"List of dependent records for the client"},"total_count":{"type":"integer","title":"Total Count","description":"Total number of dependents for this client","example":2}},"type":"object","required":["dependents","total_count"],"title":"DependentListResponse","description":"Schema for dependent list response.\n\nReturns a list of all dependents for a client along with the total count.\nUseful for pagination and displaying family information.","example":{"dependents":[{"blind":false,"client_id":"550e8400-e29b-41d4-a716-446655440000","date_of_birth":"2010-05-15","disabled":false,"full_name":"John Doe Jr.","full_time_student":false,"id":"990f9622-f49d-63f6-c938-668877662222","months_in_home":12,"relationship_type":"SON","ssn_info":{"entity_type":"DEPENDENT","id":"aa0f9622-f49d-63f6-c938-668877662444","ssn_masked":"XXX-XX-3333","ssn_type":"SSN"},"tenant_id":"440d7300-d18b-31c3-9605-335544330000"}],"total_count":1}},"DependentResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier for the dependent record","example":"990f9622-f49d-63f6-c938-668877662222"},"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"ID of the client this dependent belongs to","example":"550e8400-e29b-41d4-a716-446655440000"},"tenant_id":{"type":"string","format":"uuid","title":"Tenant Id","description":"Tenant organization ID","example":"440d7300-d18b-31c3-9605-335544330000"},"full_name":{"type":"string","title":"Full Name","description":"Full legal name of the dependent","example":"John Doe Jr."},"date_of_birth":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date Of Birth","description":"Date of birth","example":"2010-05-15"},"blind":{"type":"boolean","title":"Blind","description":"Blind status","example":false},"disabled":{"type":"boolean","title":"Disabled","description":"Disabled status","example":false},"relationship_type":{"$ref":"#/components/schemas/RelationshipEnum","description":"Relationship to the primary client","example":"SON"},"relationship_other":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Relationship Other","description":"Custom relationship description","example":"Step-sister"},"months_in_home":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Months In Home","description":"Number of months in home during tax year","example":12},"full_time_student":{"type":"boolean","title":"Full Time Student","description":"Full-time student status","example":false},"ssn_info":{"anyOf":[{"$ref":"#/components/schemas/SSNInfoResponse"},{"type":"null"}],"description":"Encrypted SSN information (masked for security)"}},"type":"object","required":["id","client_id","tenant_id","full_name","blind","disabled","relationship_type","full_time_student"],"title":"DependentResponse","description":"Schema for dependent response data.\n\nReturns complete dependent information.","example":{"blind":false,"client_id":"550e8400-e29b-41d4-a716-446655440000","date_of_birth":"2010-05-15","disabled":false,"full_name":"John Doe Jr.","full_time_student":false,"id":"990f9622-f49d-63f6-c938-668877662222","months_in_home":12,"relationship_type":"SON","ssn_info":{"entity_type":"DEPENDENT","id":"aa0f9622-f49d-63f6-c938-668877662444","ssn_masked":"XXX-XX-3333","ssn_type":"SSN"},"tenant_id":"440d7300-d18b-31c3-9605-335544330000"}},"DependentUpdate":{"properties":{"full_name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Full Name","description":"Updated full name","example":"John Doe III"},"date_of_birth":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date Of Birth","description":"Updated date of birth","example":"2010-05-15"},"blind":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Blind","description":"Updated blind status","example":false},"disabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Disabled","description":"Updated disabled status","example":false},"relationship_type":{"anyOf":[{"$ref":"#/components/schemas/RelationshipEnum"},{"type":"null"}],"description":"Updated relationship type","example":"DAUGHTER"},"relationship_other":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Relationship Other","description":"Updated custom relationship description","example":"Step-sister"},"months_in_home":{"anyOf":[{"type":"integer","maximum":12.0,"minimum":1.0},{"type":"null"}],"title":"Months In Home","description":"Updated number of months in home (1-12)","example":12},"full_time_student":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Full Time Student","description":"Updated full-time student status","example":true},"ssn":{"anyOf":[{"type":"string","maxLength":11,"minLength":9},{"type":"null"}],"title":"Ssn","description":"Social Security Number (optional - will be encrypted and stored securely if provided)","example":"123-45-6789"}},"type":"object","title":"DependentUpdate","description":"Schema for updating an existing dependent.\n\nAll fields are optional to support partial updates.","example":{"full_name":"John Doe III","relationship_type":"DAUGHTER"}},"DetectedFormInput":{"properties":{"chunk_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Chunk Id","description":"Stable per-form identity, echoed from the detected proposal. Server mints one if absent. Carried onto the child + the slice key so re-split is incremental."},"form_type":{"type":"string","title":"Form Type","description":"Classifier label, e.g. '1099-INT', 'W-2'."},"issuer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issuer","description":"Issuer/payer of this form (e.g. the brokerage on a 1099 Consolidated, the employer on a W-2). Lets the CPA tell same-type forms apart; stored on the child document."},"page_start":{"type":"integer","minimum":1.0,"title":"Page Start","description":"First page of this form in the bundle (1-indexed)."},"page_end":{"type":"integer","minimum":1.0,"title":"Page End","description":"Last page of this form in the bundle (1-indexed, inclusive)."},"document_type_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Type Id","description":"Optional FE-resolved canonical type. When absent the server canonicalizes from form_type; unresolved -> the child is materialized UNSUPPORTED."}},"type":"object","required":["form_type","page_start","page_end"],"title":"DetectedFormInput","description":"One user-confirmed form segment in the bundle (1-indexed inclusive page range)."},"DisclosureListResponse":{"properties":{"records":{"items":{"$ref":"#/components/schemas/DisclosureRecord"},"type":"array","title":"Records","default":[]},"truncated":{"type":"boolean","title":"Truncated","description":"More records exist than were returned. NEVER present a truncated export as a complete disclosure history.","default":false}},"type":"object","title":"DisclosureListResponse"},"DisclosureRecord":{"properties":{"occurred_at":{"type":"string","format":"date-time","title":"Occurred At"},"tool":{"type":"string","title":"Tool"},"actor":{"type":"string","title":"Actor","description":"'service:<id>' for an organization credential, 'user:<id>' for a named CPA. A shared connector credential CANNOT be attributed to a person, and this prefix keeps an audit from reading it as though it could."},"api_key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key Id"},"client_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Client Id"},"tax_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tax Year"},"question_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Question Text"},"outcome":{"type":"string","title":"Outcome","description":"ok | denied | not_found | clarification | timeout | error. Denied attempts are recorded on purpose — an attempt to reach a return is a fact a reviewer wants."},"elapsed_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Elapsed Ms"},"correlation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Correlation Id"}},"type":"object","required":["occurred_at","tool","actor","outcome"],"title":"DisclosureRecord","description":"One recorded MCP tool call, as an auditor reads it."},"Document1099CExtractionResponse":{"properties":{"document_classification":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Classification","description":"DEPRECATED legacy LLM classification varchar from tenant_client_dms_documents.document_classification. Frozen at upload — NOT updated on reclassify, so it goes stale once the user supersedes the type. Use document_type_identifier for routing."},"document_type_identifier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Type Identifier","description":"Canonical document_identifier of the document's CURRENT type (e.g. 'FORM_1099_CONSOLIDATED_STATEMENT'), resolved from the canonical document_type_id. Source of truth after a reclassify — route on THIS, not on the (possibly stale) document_classification.","example":"FORM_1099_CONSOLIDATED_STATEMENT"},"data":{"items":{"$ref":"#/components/schemas/YearGroup1099C"},"type":"array","title":"Data","description":"List of year-grouped 1099-C tree data, sorted by year (descending)"},"provided_document_type_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Provided Document Type Id","description":"Document type UUID from POST /internal/api/document/extract request body when `document_type_id` was supplied (reextract-with-type)."}},"type":"object","required":["data"],"title":"Document1099CExtractionResponse","description":"Response schema for the 1099-Consolidated tree-format extraction endpoint."},"DocumentApprovalRequest":{"properties":{"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"Client ID"}},"type":"object","required":["client_id"],"title":"DocumentApprovalRequest","description":"Request to approve a document."},"DocumentApprovalResponse":{"properties":{"document_id":{"type":"string","format":"uuid","title":"Document Id","description":"ID of the approved document"},"workflow_id":{"type":"string","format":"uuid","title":"Workflow Id","description":"ID of the workflow"},"status":{"$ref":"#/components/schemas/WorkflowStatus","description":"Workflow status after approval"},"approved_at":{"type":"string","format":"date-time","title":"Approved At","description":"Timestamp when document was approved"},"approved_by":{"type":"string","format":"uuid","title":"Approved By","description":"User ID who approved the document"}},"type":"object","required":["document_id","workflow_id","status","approved_at","approved_by"],"title":"DocumentApprovalResponse","description":"Response model for document approval."},"DocumentConversionHint":{"properties":{"reason":{"$ref":"#/components/schemas/ConversionReason","description":"Why this document can be converted."},"requires_force":{"type":"boolean","title":"Requires Force","description":"Pass force=true on the reclassify call. True when the target type is the one the document already has, which a plain reclassify would treat as a no-op."},"target_type_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Target Type Id","description":"supported_document_types id to reclassify to; pre-select it in the picker. Null when the successor is ambiguous and the user must choose."},"target_identifier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Identifier","description":"document_identifier of the target type (e.g. 'SCH_K1_1065')."},"target_display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Display Name","description":"Display name of the target type, for the confirmation copy."},"message":{"type":"string","title":"Message","description":"Display-ready explanation of what the conversion will do."}},"type":"object","required":["reason","requires_force","message"],"title":"DocumentConversionHint","description":"How to move ONE document onto the new extraction system.\n\nPresent only when a conversion is actually available; ``null`` means the document is already\ncurrent and the frontend shows nothing. Backend-owned so the client never carries its own\ncopy of the retired-type map or re-derives \"is this the old system\" from other fields.\n\nFeed ``target_type_id`` and ``requires_force`` straight into POST\n``/document/{document_id}/reclassify``. ``target_type_id`` is null only for an ambiguous\nretirement the backend could not settle (a K-1 whose original form was never recorded); the\nfrontend must then open the picker and let the user choose."},"DocumentExtractionRequest":{"properties":{"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"Client ID for the document"}},"type":"object","required":["client_id"],"title":"DocumentExtractionRequest","description":"Request schema for document extraction response"},"DocumentExtractionResponse":{"properties":{"document_classification":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Classification","description":"DEPRECATED legacy LLM classification varchar from tenant_client_dms_documents.document_classification. Frozen at upload — NOT updated on reclassify, so it goes stale once the user supersedes the type. Use document_type_identifier for routing."},"document_type_identifier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Type Identifier","description":"Canonical document_identifier of the document's CURRENT type (e.g. 'SCH_K1_1065'), resolved from the canonical document_type_id. Source of truth after a reclassify — route the review screen on THIS, not on the (possibly stale) document_classification.","example":"FORM_W2"},"data":{"items":{"$ref":"#/components/schemas/ExtractedAttributeItem"},"type":"array","title":"Data","description":"Flat list of extracted attributes (old structure for backward compatibility)"},"provided_document_type_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Provided Document Type Id","description":"Document type UUID from POST /internal/api/document/extract request body when `document_type_id` was supplied (reextract-with-type). Null when extraction was triggered by upload or by extract without that field; resolved type is still stored on the extraction job as `document_type_id`."}},"type":"object","required":["data"],"title":"DocumentExtractionResponse","description":"Original response schema for document extraction (flat list - backward compatibility)"},"DocumentExtractionResponseV2":{"properties":{"document_classification":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Classification","description":"DEPRECATED legacy LLM classification varchar from tenant_client_dms_documents.document_classification. Frozen at upload — NOT updated on reclassify, so it goes stale once the user supersedes the type. Use document_type_identifier for routing."},"document_type_identifier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Type Identifier","description":"Canonical document_identifier of the document's CURRENT type (e.g. 'SCH_K1_1065'), resolved from the canonical document_type_id. Source of truth after a reclassify — route the review screen on THIS, not on the (possibly stale) document_classification.","example":"FORM_W2"},"data":{"items":{"$ref":"#/components/schemas/YearGroupedAttributes"},"type":"array","title":"Data","description":"List of year-grouped attribute data, sorted by year (descending)"},"provided_document_type_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Provided Document Type Id","description":"Document type UUID from POST /internal/api/document/extract request body when `document_type_id` was supplied (reextract-with-type). Null when extraction was triggered by upload or by extract without that field; resolved type is still stored on the extraction job as `document_type_id`."},"extraction_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extraction Status","description":"Status of the document's latest extraction job (e.g. COMPLETED, FAILED, SKIPPED, UNSUPPORTED). Lets the UI distinguish a genuinely-empty document from one where automatic extraction FAILED or returned nothing — so it can show an 'extraction unavailable, enter values manually' banner instead of treating blank fields as verified-empty. The fields in `data` are always the document type's editable schema."}},"type":"object","required":["data"],"title":"DocumentExtractionResponseV2","description":"V2 Response schema for document extraction grouped by year"},"DocumentExtractionStatus":{"type":"string","enum":["REQUESTED","ACCEPTED","IN_PROGRESS","COMPLETED","UNSUPPORTED","FAILED","SKIPPED"],"title":"DocumentExtractionStatus"},"DocumentExtractionStatusItem":{"properties":{"document_id":{"type":"string","format":"uuid","title":"Document Id","description":"Document ID"},"status":{"type":"string","title":"Status","description":"Current extraction status"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"Error message if extraction failed"},"last_updated":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Updated","description":"Last update timestamp"}},"type":"object","required":["document_id","status"],"title":"DocumentExtractionStatusItem","description":"Individual document extraction status item"},"DocumentExtractionTaskItem":{"properties":{"document_id":{"type":"string","format":"uuid","title":"Document Id","description":"Document ID"},"status":{"$ref":"#/components/schemas/DocumentExtractionStatus","description":"Extraction status"}},"type":"object","required":["document_id","status"],"title":"DocumentExtractionTaskItem","description":"Individual document extraction task item"},"DocumentFlagSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"flag_type":{"type":"string","title":"Flag Type"},"family":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Family"},"severity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Severity"},"label":{"type":"string","title":"Label","description":"Display-ready badge label (backend-owned presentation)."}},"type":"object","required":["id","flag_type","label"],"title":"DocumentFlagSummary","description":"One flag on a document — enough to render + route a badge to its resolve panel."},"DocumentInputUsed":{"properties":{"document_type":{"type":"string","title":"Document Type","description":"Document type code"},"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id","description":"Document record id when available"},"document_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Name","description":"Display name from DMS when integrated; reserved until then."},"attribute_identifier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Attribute Identifier","description":"Box/field (e.g. BOX_1)"},"contributing_value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"null"}],"title":"Contributing Value","description":"Actual value from this document when present; null when the input was blank (see blank_reason)."},"blank_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Blank Reason","description":"When this document input was blank (N/A), the reason code. Omit when contributing_value is set."},"blank_display_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Blank Display Message","description":"User-facing message for blank_reason. Use for tooltip when contributing_value is null."},"document_status":{"anyOf":[{"$ref":"#/components/schemas/DocumentStatusEnum"},{"type":"null"}],"description":"From DMS when integrated; reserved until then (APPROVED, PENDING_REVIEW, etc.)."},"tax_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tax Year","description":"Tax year of document when relevant"},"entity_scope":{"anyOf":[{"$ref":"#/components/schemas/EntityScopeEnum"},{"type":"null"}],"description":"Primary vs spouse when relevant"}},"type":"object","required":["document_type"],"title":"DocumentInputUsed","description":"One document that fed a line.\n\ndocument_name and document_status: Intended to be resolved from DMS on every GET\nwhen DMS integration is available; until then they may be null (reserved)."},"DocumentItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"type":{"type":"string","title":"Type","description":"Item type identifier","default":"document"},"name":{"type":"string","title":"Name"},"document_type":{"anyOf":[{"$ref":"#/components/schemas/DocumentTypeEnum"},{"type":"null"}],"description":"Document type classification"},"derived_document_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Derived Document Type","description":"DEPRECATED legacy display name — superseded by document_type_display_name. Read nowhere on the consumer dashboard; dropped with the legacy columns in Phase 3.","example":"W-2"},"document_type_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Type Id","description":"Canonical document type id (FK to supported_document_types). The stable identifier the client should use for logic (e.g. pre-selecting the current type); pair with document_type_display_name for display."},"document_type_identifier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Type Identifier","description":"Canonical document_identifier of the document's type (e.g. 'SCH_K1_1065', 'FORM_1099_CONSOLIDATED'). The stable routing key for selecting a specialized review screen — route on THIS, not on document_classification.","example":"SCH_K1_1065"},"document_type_display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Type Display Name","description":"Single canonical 'what type is this document' display name, resolved by the backend with precedence document_type_id > derived_document_type > document_classification. Clients should read THIS field for the document type — no column-picking on the client.","example":"Form W-2"},"party_role":{"anyOf":[{"$ref":"#/components/schemas/DocumentPartyRoleEnum"},{"type":"null"}],"description":"The decided party. None = undecided, which the UI renders as the 'Set owner' ghost state. Present only on joint returns."},"party_confirmed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Party Confirmed","description":"False = auto-set from a corroborated TIN match but not yet agreed by a human; the UI renders it with the AI-provenance mark and the sign-off assertion counts it. The tax engine uses the value either way. A bool rather than the DB timestamp: the client only needs 'has a human agreed?', and sending the instant invites it to render one."},"party_display":{"anyOf":[{"$ref":"#/components/schemas/PartyDisplay"},{"type":"null"}],"description":"Display strings resolved BY THE BACKEND. There is no first_name field anywhere in the client API — only full_name — so splitting a name client-side would break mononyms, double surnames and CJK order, which is a uniquely bad bug class in a tax product. Clients render THESE strings."},"party_allowed_roles":{"anyOf":[{"items":{"$ref":"#/components/schemas/DocumentPartyRoleEnum"},"type":"array"},{"type":"null"}],"title":"Party Allowed Roles","description":"The roles this document's TYPE permits, already filtered to what v1 can store. The picker renders exactly this list — never a hardcoded one — because ownership is a fact about the form: a W-2 has one employee, an IRA has exactly one owner (IRC 408(a)), a bank account may be joint. Empty = the question does not apply."},"party_suggestion_basis":{"anyOf":[{"$ref":"#/components/schemas/DocumentPartyBasisEnum"},{"type":"null"}],"description":"Evidence behind the suggestion, for the popover's evidence line."},"party_role_suggested":{"anyOf":[{"$ref":"#/components/schemas/DocumentPartyRoleEnum"},{"type":"null"}],"description":"What the RESOLVER guessed, retained even after a human overrides it. Distinct from party_role: without it the UI cannot tell 'the TIN matched this person' from 'a CPA chose this person against the TIN', and would claim a corroboration it never had on a return the CPA signs."},"split_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Split State","description":"NONE | AWAITING_SPLIT | BUNDLE | CHILD."},"parent_document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Document Id","description":"For a CHILD, the BUNDLE it belongs to (for nested display)."},"bundle_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bundle Status","description":"BUNDLE only: SPLITTING | EXTRACTING | ACTION_NEEDED | ALL_FAILED | READY | COMPLETED. Derived rollup of the bundle's children — the canonical bundle status. None for non-bundles."},"bundle_summary":{"anyOf":[{"$ref":"#/components/schemas/BundleSummary"},{"type":"null"}],"description":"BUNDLE only: coverage ledger (counts of ready/failed/ignored/in-progress children)."},"document_classification":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Classification","description":"DEPRECATED legacy LLM classification varchar. Do NOT use for type display or review routing — use document_type_display_name / document_type_identifier. Retained only as a transition fallback + 1099C/K1 panel data; dropped in Phase 3."},"document_classification_display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Classification Display Name","description":"DEPRECATED — superseded by document_type_display_name (which resolves with precedence). Not consumed by the consumer dashboard; removed in Phase 2/3.","example":"Form W-2"},"instance_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Instance Name","description":"Instance label for this classification (e.g., employer or institution)."},"file_size":{"type":"integer","title":"File Size"},"version":{"type":"integer","title":"Version","description":"Version number of this document (1, 2, 3, etc.)","example":2},"is_latest":{"type":"boolean","title":"Is Latest","description":"Whether this is the latest version (always True in folder contents)","example":true},"folder_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Folder Id"},"folder_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Folder Path"},"tags":{"items":{"additionalProperties":{"type":"string"},"type":"object"},"type":"array","title":"Tags"},"uploaded_at":{"type":"string","format":"date-time","title":"Uploaded At"},"download_count":{"type":"integer","title":"Download Count"},"tax_year":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tax Year","description":"Tax year for the document"},"doc_year":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Doc Year","description":"Document year for the document"},"extraction_request_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extraction Request Status","description":"Extraction request status (computed from extraction jobs). Always None for BUNDLE rows — a bundle has no extraction of its own; read bundle_status instead."},"extraction_requested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Extraction Requested At","description":"When extraction was requested (computed from extraction jobs)"},"extraction_completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Extraction Completed At","description":"When extraction was completed (computed from extraction jobs)"},"is_extraction_allowed":{"type":"boolean","title":"Is Extraction Allowed","description":"Whether the FE may offer (re-)extraction for this document. True when the document has never been extracted (extraction_request_status is null). Once it has been extracted at least once, true only when the document has a canonical document_type_identifier AND that document type is extraction-enabled (is_active, same semantics as /document/types); false otherwise. Computed by the backend (shared.dms.extraction_eligibility.is_extraction_allowed).","default":true,"example":true},"extraction_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extraction Status","description":"Current status of document extraction (COMPLETED, FAILED, IN_PROGRESS, etc.)"},"workflow_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workflow Status","description":"Current status of document workflow (CREATED, IN_PROGRESS, APPROVED, REJECTED, etc.)"},"extraction_version":{"$ref":"#/components/schemas/ExtractionVersion","description":"Which extraction generation THIS document is on (v1 = legacy flow, v2 = new flow). Derived from the document's active extraction job; for a not-yet-extracted document it reflects the doctype's new_extraction_flow_enabled flag. The frontend picks the v1/v2 review UI from this.","default":"v1"},"is_shared":{"type":"boolean","title":"Is Shared","description":"True when this document has an active direct share with the client. Use share_id to call DELETE /dms/shares/{share_id} to unshare. Always False when is_shared_via_folder is True.","default":false},"share_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Share Id","description":"Active direct share ID when is_shared=True."},"is_shared_via_folder":{"type":"boolean","title":"Is Shared Via Folder","description":"True when this document is inside a directly-shared folder. The client can access it via the folder share. Cannot be independently unshared — move the document or unshare the folder.","default":false},"folder_share_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Folder Share Id","description":"Share ID of the parent folder when is_shared_via_folder=True. Call DELETE /dms/shares/{folder_share_id} to unshare the entire folder."},"open_flag_count":{"type":"integer","title":"Open Flag Count","description":"Number of OPEN, visible cross-document/content flags on this document.","default":0},"top_flag_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Top Flag Type","description":"Highest-priority OPEN flag_type — for routing/logic."},"top_flag_severity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Top Flag Severity","description":"Severity of the top flag (ERROR | WARNING | INFO) — badge colour."},"top_flag_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Top Flag Label","description":"Display-ready badge label (backend-owned presentation)."},"flags":{"items":{"$ref":"#/components/schemas/DocumentFlagSummary"},"type":"array","title":"Flags","description":"Every OPEN, visible flag on this document (most-severe first). A document can carry several flags that are each resolved independently — the UI renders one badge per flag."}},"type":"object","required":["id","name","file_size","version","is_latest","folder_id","folder_path","uploaded_at","download_count"],"title":"DocumentItem","description":"Unified document item for folder contents with version information.\n\nAlways returns the latest version when listed in folder contents.\nVersion fields allow UI to display which version is shown."},"DocumentMatchingInfo":{"properties":{"is_document_classification_match":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Document Classification Match","description":"Whether document_classification matches requested document_type (strict match)"},"is_instance_name_match":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Instance Name Match","description":"Whether instance_name matches requested instance_name (fuzzy match)"},"instance_match_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Instance Match Score","description":"Instance-name match score (0-100) computed via rapidfuzz partial_ratio."},"document_classification":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Classification","description":"DEPRECATED human-readable display name of the matched type. Prefer document_type_identifier (stable routing key) + document_type_id. Phase 3 removal.","example":"Form W-2"},"document_type_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Type Id","description":"Canonical document type id (FK to supported_document_types) of the matched document's CURRENT type. Source of truth after a reclassify; null until the document has a type."},"document_type_identifier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Type Identifier","description":"Canonical document_identifier of the matched document's CURRENT type (e.g. 'W2', 'FORM_1099_INT'), resolved from document_type_id. Stable routing/compare key — use THIS instead of the human-readable document_classification.","example":"W2"},"document_type_display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Type Display Name","description":"Canonical human-readable display name of the matched document's CURRENT type, resolved from document_type_id. Read THIS for display (replaces the legacy document_classification, which held the display name).","example":"Form W-2"},"instance_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Instance Name","description":"Instance name from automatic classification functionality","example":"ACME Corporation"},"is_implicit_document_matching":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Implicit Document Matching","description":"True when SUGGESTION_APPLIED was done implicitly (by system); False when applied by user confirm-match; None when no suggestion was applied."},"document_classification_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Classification Status","description":"Latest document classification audit status for this document (ACCEPTED, IN_PROGRESS, COMPLETED, FAILED).","example":"COMPLETED"}},"type":"object","title":"DocumentMatchingInfo","description":"Schema for document type matching information"},"DocumentPartyBasisEnum":{"type":"string","enum":["TIN_EXACT","TIN_LAST4","NAME_ONLY","AMBIGUOUS","NO_MATCH"],"title":"DocumentPartyBasisEnum","description":"Evidence behind a party suggestion — gates whether it may auto-set.\n\nAzure DI extracts TINs VERBATIM including masking, so a full-digit comparison\nis only possible when both sides are complete; below that, last-4 is all there\nis. Four masked digits alone is a 1-in-10^4 coincidence with CORRELATED family\nserials and no checksum, so ``TIN_LAST4`` auto-sets only with a corroborating\nname."},"DocumentPartyOutcome":{"properties":{"document_id":{"type":"string","format":"uuid","title":"Document Id"},"applied":{"type":"boolean","title":"Applied"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Why it was skipped. The UI shows these verbatim — assigning 9 of 12 without saying which 3 were skipped is a correctness bug the CPA cannot see.","example":"FORM_5498 does not permit JOINT"}},"type":"object","required":["document_id","applied"],"title":"DocumentPartyOutcome","description":"What happened to one document in a party assignment."},"DocumentPartyRoleEnum":{"type":"string","enum":["TAXPAYER","SPOUSE","JOINT","DEPENDENT","NOT_ON_RETURN"],"title":"DocumentPartyRoleEnum","description":"Whose document this is, on a joint return.\n\n``DEPENDENT`` and ``NOT_ON_RETURN`` are RESERVED, not live — the DB constraint\n``ck_dms_party_v1_scope`` blocks them. Both need the engine to EXCLUDE a document\nfrom the value lists rather than merely label it, and exclusion changes the\ncorrect answer at every document read, not just the few that already do owner\nattribution. Shipping half of that is an internally inconsistent 1040."},"DocumentRef":{"properties":{"document_type":{"type":"string","title":"Document Type","description":"Document type code (e.g. FORM_1099_INT, W_2)"},"display_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Label","description":"Human-readable label (e.g. 1099-INT)"},"field_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field Name","description":"Field/attribute identifier when dependency is field-specific (e.g. BOX_1)."},"suggestion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Suggestion","description":"User-facing suggestion"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Optional reason"},"tax_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tax Year","description":"Tax year filter when relevant"},"entity_scope":{"anyOf":[{"$ref":"#/components/schemas/EntityScopeEnum"},{"type":"null"}],"description":"Primary vs spouse when relevant"},"jurisdiction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Jurisdiction","description":"e.g. federal"}},"type":"object","required":["document_type"],"title":"DocumentRef","description":"One document type reference in dependencies or missing_inputs."},"DocumentRejectionRequest":{"properties":{"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"Client ID"},"reason":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Reason","description":"Reason for rejection"}},"type":"object","required":["client_id","reason"],"title":"DocumentRejectionRequest","description":"Request to reject a document."},"DocumentRejectionResponse":{"properties":{"document_id":{"type":"string","format":"uuid","title":"Document Id","description":"ID of the rejected document"},"workflow_id":{"type":"string","format":"uuid","title":"Workflow Id","description":"ID of the workflow"},"status":{"$ref":"#/components/schemas/WorkflowStatus","description":"Workflow status after rejection"},"rejected_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Rejected At","description":"Timestamp when document was rejected"},"rejected_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Rejected By","description":"User ID who rejected the document"},"rejection_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rejection Reason","description":"Reason for rejection"}},"type":"object","required":["document_id","workflow_id","status","rejected_at","rejected_by","rejection_reason"],"title":"DocumentRejectionResponse","description":"Response model for document rejection."},"DocumentReopenRequest":{"properties":{"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"Client ID"},"reason":{"type":"string","minLength":1,"title":"Reason","description":"Reason for reopening"}},"type":"object","required":["client_id","reason"],"title":"DocumentReopenRequest","description":"Request model for document reopening."},"DocumentReopenResponse":{"properties":{"document_id":{"type":"string","format":"uuid","title":"Document Id","description":"ID of the reopened document"},"workflow_id":{"type":"string","format":"uuid","title":"Workflow Id","description":"ID of the workflow"},"status":{"$ref":"#/components/schemas/WorkflowStatus","description":"Workflow status after reopening"},"reopened_at":{"type":"string","format":"date-time","title":"Reopened At","description":"Timestamp when document was reopened"},"reopened_by":{"type":"string","format":"uuid","title":"Reopened By","description":"User ID who reopened the document"},"reopen_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reopen Reason","description":"Reason for reopening"}},"type":"object","required":["document_id","workflow_id","status","reopened_at","reopened_by","reopen_reason"],"title":"DocumentReopenResponse","description":"Response model for document reopening."},"DocumentResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"original_filename":{"type":"string","title":"Original Filename"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"document_type":{"anyOf":[{"$ref":"#/components/schemas/DocumentTypeEnum"},{"type":"null"}],"description":"DEPRECATED legacy coarse enum (W2 / FORM_1099 / OTHER…). Not the canonical type — use document_type_identifier / document_type_display_name. Dropped in Phase 3."},"file_size":{"type":"integer","title":"File Size"},"file_hash":{"type":"string","title":"File Hash"},"mime_type":{"type":"string","title":"Mime Type"},"storage_reference":{"type":"string","title":"Storage Reference"},"version":{"type":"integer","title":"Version","description":"Version number of this document (1, 2, 3, etc.)","example":3},"is_latest":{"type":"boolean","title":"Is Latest","description":"Whether this is the latest/current version of the document","example":true},"is_deleted":{"type":"boolean","title":"Is Deleted"},"download_count":{"type":"integer","title":"Download Count"},"folder_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Folder Id"},"folder_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Folder Path"},"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url"},"tax_year":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tax Year"},"doc_year":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Doc Year"},"derived_document_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Derived Document Type","description":"DEPRECATED legacy display name — superseded by document_type_display_name. Dropped with the legacy columns in Phase 3.","example":"W-2"},"document_type_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Type Id","description":"Canonical document type id (FK to supported_document_types). Stable identifier for logic (e.g. pre-selecting the current type); pair with document_type_display_name."},"document_type_identifier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Type Identifier","description":"Canonical document_identifier of the document's CURRENT type (e.g. 'SCH_K1_1065'), resolved from document_type_id. Source of truth after a reclassify — route on THIS, not on the legacy document_type enum / derived_document_type.","example":"FORM_W2"},"document_type_display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Type Display Name","description":"Single canonical 'what type is this document' display name, resolved BE-side with precedence document_type_id > derived_document_type > document_classification. Read THIS for display — no column-picking on the client.","example":"Form W-2"},"split_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Split State","description":"NONE | AWAITING_SPLIT | BUNDLE | CHILD. AWAITING_SPLIT drives the FE 'review the split' entry CTA."},"tax_forms_detected":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Tax Forms Detected","description":"Classifier's per-form proposal for a bundle: [{form_type, issuer, page_start, page_end}]. The FE seeds the split-validation screen from this."},"page_number_start":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Number Start","description":"For a SPLIT_CHILD, its origin start page in the parent bundle."},"page_number_end":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Number End","description":"For a SPLIT_CHILD, its origin end page in the parent bundle."},"parent_document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Document Id","description":"For a SPLIT_CHILD, the bundle parent it was sliced from."},"extraction_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extraction Status","description":"Current status of document extraction (COMPLETED, FAILED, IN_PROGRESS, etc.)"},"workflow_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workflow Status","description":"Current status of document workflow (CREATED, IN_PROGRESS, APPROVED, REJECTED, etc.)"},"extraction_version":{"$ref":"#/components/schemas/ExtractionVersion","description":"Which extraction generation THIS document is on (v1 = legacy flow, v2 = new flow). Derived from the document's active extraction job; for a not-yet-extracted document it reflects the doctype's new_extraction_flow_enabled flag (the generation a future run will use). The frontend picks the v1/v2 review UI from this.","default":"v1"},"conversion":{"anyOf":[{"$ref":"#/components/schemas/DocumentConversionHint"},{"type":"null"}],"description":"How to move this document onto the new extraction system, or null when it is already current. Populated on the document-detail read; null on the upload / update responses, which describe a write rather than the document's standing."},"open_flag_count":{"type":"integer","title":"Open Flag Count","description":"Number of OPEN cross-document flags (duplicate/superseded) on this document.","default":0},"top_flag_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Top Flag Type","description":"Highest-priority OPEN flag_type — kept for routing/logic. None when no flags."},"top_flag_severity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Top Flag Severity","description":"Severity of the top flag (ERROR | WARNING | INFO) — drives the badge colour."},"top_flag_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Top Flag Label","description":"Display-ready badge label for the top flag (backend-owned presentation), so the FE renders it without a per-type map."},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the document was created"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When the document was last updated"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Non-fatal advisory messages. Populated on upload when the target folder is already shared with the client — the uploaded document is immediately accessible to them via the folder share."}},"type":"object","required":["id","name","original_filename","description","file_size","file_hash","mime_type","storage_reference","version","is_latest","is_deleted","download_count","folder_id"],"title":"DocumentResponse","description":"Complete document response with version information.\n\nVersion fields indicate which version of the document this is and whether\nit's the currently active (latest) version."},"DocumentStatusEnum":{"type":"string","enum":["APPROVED","PENDING_REVIEW","NEEDS_REVIEW","REJECTED"],"title":"DocumentStatusEnum","description":"Document status for inputs_used (DMS workflow)."},"DocumentTypeChangeReasonEnum":{"type":"string","enum":["MISCLASSIFIED","WAS_UNCLASSIFIED","WRONG_VARIANT","CONVERT_TO_NEW_EXTRACTION","OTHER"],"title":"DocumentTypeChangeReasonEnum","description":"User-supplied reason for a RECLASSIFY (tenant_client_document_type_change_audit.reason_code)."},"DocumentTypeEnum":{"type":"string","enum":["W2","W2_AS","W2_CM","W2_GU","W2_VI","FORM_W2G","FORM_W3","FORM_1040","FORM_1040_SCHEDULE_A","FORM_1040_SCHEDULE_B","FORM_1040_SCHEDULE_E","FORM_1040_SCHEDULE_F","FORM_1040_SENIOR","FORM_1098","FORM_1098_C","FORM_1098_E","FORM_1098_T","FORM_1099_INT","FORM_1099_A","FORM_1099_B","FORM_1099_CAP","FORM_1099_CONSOLIDATED_STATEMENT","FORM_1099_DIV","FORM_1099_R","FORM_1099_G","FORM_1099_MISC","FORM_1099_NEC","FORM_1099_C","FORM_1099_K","FORM_1099_LTC","FORM_1099_OID","FORM_1099_PATR","FORM_1099_QA","FORM_1099_SA","FORM_1099_Q","FORM_1099_DA","FORM_RRB_1099","FORM_RRB_1099R","FORM_1099_S","FORM_1042_S","FORM_8805","FORM_8288_A","FORM_1095_A","FORM_1095_C","FORM_SSA_1099","FORM_2439","FORM_3921","FORM_3922","FORM_5498","FORM_5498_SA","SCHEDULE_K1_GENERIC","SCH_K1_1041","SCH_K1_1065","SCH_K1_1120S","FORM_1041_SCHEDULE_K1","FORM_1065_SCHEDULE_K1","FORM_1120S_SCHEDULE_K1","INVOICE","RECEIPT","TAX_FORM","PROFIT_AND_LOSS_STATEMENT","PROFIT_AND_LOSS_STATEMENT_BUSINESS","PROFIT_AND_LOSS_STATEMENT_FARM","PROFIT_AND_LOSS_STATEMENT_RENTAL","INCOME_STATEMENT","GENERAL_LEDGER","TRIAL_BALANCE","BALANCE_SHEET","SCHEDULE_C_INPUT","PREVIOUS_YEAR_RETURN","BROKERAGE_STATEMENT","ASSETS_PURCHASED_BUSINESS","ASSETS_SOLD_BUSINESS","ASSETS_PURCHASED_RENTAL","ASSETS_SOLD_RENTAL","ASSETS_PURCHASED_FARM","ASSETS_SOLD_FARM","MEDICAL_EXPENSES","CHARITABLE_CONTRIBUTIONS_CASH","CHARITABLE_CONTRIBUTIONS_NON_CASH","PERSONAL_PROPERTY_TAXES","SALES_AND_USE_TAXES","VEHICLE_EXPENSES","DAY_CARE_EXPENSES","MAJOR_PURCHASES","PROPERTY_TAX_STATEMENT","ESTIMATED_TAX_PAYMENT_RECEIPTS","CLOSING_STATEMENT_REAL_ESTATE","PREVIOUS_YEAR_TAX_RETURNS","TAX_RETURN","TAX_ORGANIZER","TAX_PLANNING","REPAIRS_AND_IMPROVEMENTS_RENTAL","PAYROLL_TAX_REPORT","CLIENT_INTAKE_FORM","GOVERNMENT_ISSUED_IDENTIFICATION","IRS_NOTICE_OR_LETTER","DEPENDENT_DOCUMENTATION","FOREIGN_FINANCIAL_ACCOUNTS","FOREIGN_INCOME_DOCUMENTATION","529_PLAN_STATEMENT","83B_ELECTION_STATEMENT","SALES_BY_STATE_REPORT","STATES_FILING_SALES_TAX_RETURNS","VEHICLE_SELLER_REPORT","HEALTH_INSURANCE_PREMIUM_STATEMENT","BIRTH_CERTIFICATE","DRIVERS_LICENSE","DIRECT_DEPOSIT","REGISTRATION_RENEWAL_NOTICE","ENGAGEMENT_LETTER","SERVICE_AGREEMENT","CLIENT_NOTE","BUNDLED_DOCUMENT","OTHER_DOCUMENTS","UNCATEGORIZED","VESTING_STATEMENT","EXERCISE_CONFIRMATION","CLERGY_INFORMATION","OTHER"],"title":"DocumentTypeEnum"},"DocumentTypesResponse":{"properties":{"document_types":{"items":{"$ref":"#/components/schemas/app__schemas__dms__document__SupportedDocumentType"},"type":"array","title":"Document Types","description":"List of available document types"}},"type":"object","required":["document_types"],"title":"DocumentTypesResponse","description":"Response for document types list endpoint"},"DocumentUpdateRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"null"}],"title":"Name","description":"Document name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Document description"},"document_type":{"anyOf":[{"$ref":"#/components/schemas/DocumentTypeEnum"},{"type":"null"}],"description":"Document type"},"folder_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Folder Id","description":"Target folder ID"},"tags":{"anyOf":[{"items":{"$ref":"#/components/schemas/TagSchema"},"type":"array"},{"type":"null"}],"title":"Tags","description":"Document tags"}},"type":"object","title":"DocumentUpdateRequest"},"DocumentUploadRequestCreate":{"properties":{"recipient_email":{"type":"string","title":"Recipient Email","description":"Email address to send the request to","example":"client@example.com"},"recipient_name":{"type":"string","title":"Recipient Name","description":"Name of the recipient","example":"John Doe"},"tax_year":{"type":"string","pattern":"^\\d{4}$","title":"Tax Year","description":"Tax year for the documents (YYYY format)","example":"2024"},"target_folder_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Target Folder Id","description":"Target folder ID where documents will be uploaded (null for root)"},"items":{"items":{"$ref":"#/components/schemas/DocumentUploadRequestItemCreate"},"type":"array","maxItems":50,"title":"Items","description":"List of document types/items to request (optional - can be empty for questionnaire-only requests)","example":[{"description":"All W-2 forms from 2024","document_type":"W2","extraction_enabled":true,"is_optional":false,"max_files_per_item":5,"tags":["CORP - PERSON_ABC","CORP - PERSON_XYZ"]},{"description":"1099-INT forms from 2024","document_type":"FORM_1099_INT","extraction_enabled":true,"is_optional":false,"max_files_per_item":1,"tags":["CHASE BANK","STANFORD FEDERAL CREDIT UNION - 268"]},{"description":"Bank statements for December 2024","document_type":"TAX_FORM","extraction_enabled":false,"is_optional":true,"max_files_per_item":10}]}},"type":"object","required":["recipient_email","recipient_name","tax_year"],"title":"DocumentUploadRequestCreate","description":"Schema for creating a document upload request"},"DocumentUploadRequestDashboardDetailResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier for the upload request"},"tenant_id":{"type":"string","format":"uuid","title":"Tenant Id","description":"Tenant ID"},"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"Client ID"},"client_name":{"type":"string","title":"Client Name","description":"Client's full name"},"client_identifier":{"type":"string","title":"Client Identifier","description":"Client's readable identifier (e.g., 'AT-23456')","example":"AT-23456"},"request_title":{"type":"string","title":"Request Title","description":"Title of the upload request"},"instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Instructions","description":"General instructions for the client"},"tax_year":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tax Year","description":"Tax year"},"recipient_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recipient Email","description":"Email address where request was sent"},"recipient_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recipient Name","description":"Name of the recipient"},"target_folder_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Target Folder Id","description":"Target folder ID"},"intake_token":{"type":"string","title":"Intake Token","description":"Secure intake token"},"upload_url":{"type":"string","title":"Upload Url","description":"Public upload URL for clients"},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"When the upload link expires"},"status":{"$ref":"#/components/schemas/IntakeRequestStatus","description":"Current status of the request"},"total_items":{"type":"integer","title":"Total Items","description":"Total number of items requested"},"completed_items":{"type":"integer","title":"Completed Items","description":"Number of items completed"},"completion_rate":{"type":"string","title":"Completion Rate","description":"Completion rate in format 'completed/total' (e.g., '2/8')","example":"2/8"},"completion_status":{"type":"string","title":"Completion Status","description":"Completion status: 'Completed', 'In Progress', or 'Pending'","example":"In Progress"},"completed_count":{"type":"integer","title":"Completed Count","description":"Number of completed/uploaded items","example":2},"pending_count":{"type":"integer","title":"Pending Count","description":"Number of pending items","example":6},"rejected_count":{"type":"integer","title":"Rejected Count","description":"Number of rejected items","default":0,"example":0},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the request was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the request was last updated"},"created_by":{"type":"string","title":"Created By","description":"User who created the request"},"revoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Revoked At","description":"When the request was revoked"},"revoked_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revoked By","description":"User who revoked the request"},"revoked_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revoked Reason","description":"Reason for revocation"},"max_edits_per_item":{"type":"integer","title":"Max Edits Per Item","description":"Maximum number of edits/reuploads allowed per item"},"items":{"items":{"$ref":"#/components/schemas/DocumentUploadRequestItemResponse"},"type":"array","title":"Items","description":"List of regular request items (not additional documents)"},"additional_documents":{"items":{"$ref":"#/components/schemas/DocumentUploadRequestItemResponse"},"type":"array","title":"Additional Documents","description":"List of additional documents added by the client"},"voluntary_documents":{"items":{"$ref":"#/components/schemas/DocumentUploadRequestItemResponse"},"type":"array","title":"Voluntary Documents","description":"List of voluntary documents uploaded without document type (not counted in totals)"},"questionnaire_from_pyr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Questionnaire From Pyr","description":"Questionnaire processing status for previous year return (if applicable for this intake request)","example":"COMPLETED"},"document_checklist_suggestion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Checklist Suggestion","description":"Document checklist processing status for previous year return (if applicable for this intake request)","example":"COMPLETED"},"previous_year_return":{"$ref":"#/components/schemas/PreviousYearReturnInfo","description":"Previous year return reupload eligibility and document reference."},"status_label":{"type":"string","title":"Status Label","description":"Human-readable status for UI display.","readOnly":true}},"type":"object","required":["id","tenant_id","client_id","client_name","client_identifier","request_title","intake_token","upload_url","expires_at","status","total_items","completed_items","completion_rate","completion_status","completed_count","pending_count","created_at","updated_at","created_by","max_edits_per_item","items","previous_year_return","status_label"],"title":"DocumentUploadRequestDashboardDetailResponse","description":"Schema for dashboard upload request detail response with comprehensive information"},"DocumentUploadRequestDashboardListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/DocumentUploadRequestDashboardResponse"},"type":"array","title":"Data","description":"List of upload requests"},"meta":{"$ref":"#/components/schemas/app__schemas__common__pagination__PaginationMeta","description":"Pagination metadata"}},"type":"object","required":["data","meta"],"title":"DocumentUploadRequestDashboardListResponse","description":"Paginated response for dashboard upload requests list"},"DocumentUploadRequestDashboardResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier for the upload request"},"request_title":{"type":"string","title":"Request Title","description":"Title of the upload request"},"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"Client ID"},"client_name":{"type":"string","title":"Client Name","description":"Client's full name"},"upload_count":{"type":"string","title":"Upload Count","description":"Upload count in format 'completed/total' (e.g., '4/8')","example":"4/8"},"completed_items":{"type":"integer","title":"Completed Items","description":"Number of items completed"},"total_items":{"type":"integer","title":"Total Items","description":"Total number of items requested"},"last_updated":{"type":"string","format":"date-time","title":"Last Updated","description":"When the request was last updated"},"due_date":{"type":"string","format":"date-time","title":"Due Date","description":"When the upload link expires (due date)"},"status":{"type":"string","title":"Status","description":"UI-friendly status label (same as get_intake_request_status_label): 'Draft', 'Email Sent', 'In Progress', 'Completed', 'Expired', 'Revoked'","example":"In Progress"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the request was created"},"created_by":{"type":"string","title":"Created By","description":"User who created the request"},"questionnaire_from_pyr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Questionnaire From Pyr","description":"Questionnaire processing status for previous year return (if applicable for this intake request)","example":"COMPLETED"},"document_checklist_suggestion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Checklist Suggestion","description":"Document checklist processing status for previous year return (if applicable for this intake request)","example":"COMPLETED"},"status_code":{"$ref":"#/components/schemas/IntakeRequestStatus","description":"Actual request status enum value (DRAFT, EMAIL_SENT, ACTIVE, COMPLETED, EXPIRED, REVOKED) for filtering and logic.","example":"EMAIL_SENT"}},"type":"object","required":["id","request_title","client_id","client_name","upload_count","completed_items","total_items","last_updated","due_date","status","created_at","created_by","status_code"],"title":"DocumentUploadRequestDashboardResponse","description":"Schema for dashboard upload request response with client information"},"DocumentUploadRequestItemCreate":{"properties":{"document_type":{"anyOf":[{"$ref":"#/components/schemas/DocumentTypeEnum"},{"type":"null"}],"description":"Type of document requested (None for voluntary documents)","example":"W2"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Additional instructions for this specific document type","example":"Please upload all W-2 forms from 2024"},"notes":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Notes","description":"Optional notes from CPA for this specific document type request","example":"Client mentioned they will upload this next week"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags","description":"Tags/instance names associated with this document item (e.g., employer names, bank names)","example":["CORP - PERSON_ABC","CHASE BANK"]},"is_optional":{"type":"boolean","title":"Is Optional","description":"Whether this document is optional or required","default":false,"example":false},"is_additional_document":{"type":"boolean","title":"Is Additional Document","description":"Whether this is an additional document added by the client (not part of original request)","default":false,"example":false},"is_voluntary_document":{"type":"boolean","title":"Is Voluntary Document","description":"Whether this is a voluntary document uploaded without document type (not counted in totals)","default":false,"example":false},"extraction_enabled":{"type":"boolean","title":"Extraction Enabled","description":"Whether to automatically start document extraction after upload for this specific item","default":false,"example":false},"max_files_per_item":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Max Files Per Item","description":"Maximum number of files allowed for this specific document type","default":1,"example":1},"doc_checklist_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Doc Checklist Id","description":"ID of the checklist item from tenant_client_intake_document_checklist table, if this request item is linked to an existing checklist entry","example":"00000000-0000-0000-0000-000000000000"}},"type":"object","title":"DocumentUploadRequestItemCreate","description":"Schema for creating a document upload request item"},"DocumentUploadRequestItemResponse":{"properties":{"document_type":{"anyOf":[{"$ref":"#/components/schemas/DocumentTypeEnum"},{"type":"null"}],"description":"Type of document requested (None for voluntary documents)","example":"W2"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Additional instructions for this specific document type","example":"Please upload all W-2 forms from 2024"},"notes":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Notes","description":"Optional notes from CPA for this specific document type request","example":"Client mentioned they will upload this next week"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags","description":"Tags/instance names associated with this document item","example":["CORP - PERSON_ABC","CHASE BANK"]},"is_optional":{"type":"boolean","title":"Is Optional","description":"Whether this document is optional or required","default":false,"example":false},"is_additional_document":{"type":"boolean","title":"Is Additional Document","description":"Whether this is an additional document added by the client","default":false,"example":false},"is_voluntary_document":{"type":"boolean","title":"Is Voluntary Document","description":"Whether this is a voluntary document (no document type, not counted in totals)","default":false,"example":false},"extraction_enabled":{"type":"boolean","title":"Extraction Enabled","description":"Whether to automatically start document extraction after upload for this specific item","default":false,"example":false},"max_files_per_item":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Max Files Per Item","description":"Maximum number of files allowed for this specific document type","default":1},"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier for the request item"},"intake_request_id":{"type":"string","format":"uuid","title":"Intake Request Id","description":"ID of the parent intake request"},"display_order":{"type":"integer","title":"Display Order","description":"Display order in the UI"},"status":{"$ref":"#/components/schemas/IntakeRequestItemStatus","description":"Current status of this item"},"edit_count":{"type":"integer","title":"Edit Count","description":"Number of times this item has been edited/reuploaded"},"client_notes":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Client Notes","description":"Optional notes added by the client/user for this document item","example":"This is my W-2 from Acme Corporation"},"document_type_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Type Label","description":"Human-readable label for the document type (None for voluntary documents)","example":"W-2"},"uploaded_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uploaded By","description":"Name of the person who uploaded the document (for CPA view)","example":"John Doe"},"can_modify":{"type":"boolean","title":"Can Modify","description":"Whether this item can still be modified (false if UPLOADED)","default":true,"example":true},"rejection_reason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Rejection Reason","description":"Reason provided when rejecting this document item (only set when status is REJECTED)","example":"Document not available"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the item was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the item was last updated"},"uploaded_documents":{"anyOf":[{"items":{"$ref":"#/components/schemas/UploadedDocumentInfo"},"type":"array"},{"type":"null"}],"title":"Uploaded Documents","description":"List of uploaded documents for this item (only included when status is UPLOADED)"}},"type":"object","required":["id","intake_request_id","display_order","status","edit_count","created_at","updated_at"],"title":"DocumentUploadRequestItemResponse","description":"Schema for document upload request item response (internal/CPA use)"},"DocumentUploadRequestResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier for the upload request"},"tenant_id":{"type":"string","format":"uuid","title":"Tenant Id","description":"Tenant ID"},"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"Client ID"},"request_title":{"type":"string","title":"Request Title","description":"Title of the upload request"},"instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Instructions","description":"General instructions for the client"},"tax_year":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tax Year","description":"Tax year"},"recipient_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recipient Email","description":"Email address where request was sent"},"recipient_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recipient Name","description":"Name of the recipient"},"target_folder_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Target Folder Id","description":"Target folder ID"},"intake_token":{"type":"string","title":"Intake Token","description":"Secure intake token"},"upload_url":{"type":"string","title":"Upload Url","description":"Public upload URL for clients"},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"When the upload link expires"},"status":{"$ref":"#/components/schemas/IntakeRequestStatus","description":"Current status of the request"},"total_items":{"type":"integer","title":"Total Items","description":"Total number of items requested"},"completed_items":{"type":"integer","title":"Completed Items","description":"Number of items completed"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the request was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the request was last updated"},"created_by":{"type":"string","title":"Created By","description":"User who created the request"},"revoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Revoked At","description":"When the request was revoked"},"revoked_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revoked By","description":"User who revoked the request"},"revoked_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revoked Reason","description":"Reason for revocation"},"max_edits_per_item":{"type":"integer","title":"Max Edits Per Item","description":"Maximum number of edits/reuploads allowed per item"},"items":{"anyOf":[{"items":{"$ref":"#/components/schemas/DocumentUploadRequestItemResponse"},"type":"array"},{"type":"null"}],"title":"Items","description":"List of regular request items"},"additional_documents":{"anyOf":[{"items":{"$ref":"#/components/schemas/DocumentUploadRequestItemResponse"},"type":"array"},{"type":"null"}],"title":"Additional Documents","description":"List of additional documents added by the client"},"voluntary_documents":{"anyOf":[{"items":{"$ref":"#/components/schemas/DocumentUploadRequestItemResponse"},"type":"array"},{"type":"null"}],"title":"Voluntary Documents","description":"List of voluntary documents uploaded without document type (not counted in totals)"},"questionnaire_from_pyr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Questionnaire From Pyr","description":"Questionnaire processing status for previous year return (if applicable for this intake request)","example":"COMPLETED"},"document_checklist_suggestion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Checklist Suggestion","description":"Document checklist processing status for previous year return (if applicable for this intake request)","example":"COMPLETED"},"previous_year_return":{"$ref":"#/components/schemas/PreviousYearReturnInfo","description":"Previous year return reupload eligibility and document reference."},"status_label":{"type":"string","title":"Status Label","description":"Human-readable status for UI display.","readOnly":true}},"type":"object","required":["id","tenant_id","client_id","request_title","intake_token","upload_url","expires_at","status","total_items","completed_items","created_at","updated_at","created_by","max_edits_per_item","previous_year_return","status_label"],"title":"DocumentUploadRequestResponse","description":"Schema for document upload request response"},"DocumentUploadRequestSummaryResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier for the upload request"},"request_title":{"type":"string","title":"Request Title","description":"Title of the upload request"},"status":{"$ref":"#/components/schemas/IntakeRequestStatus","description":"Current status of the request"},"total_items":{"type":"integer","title":"Total Items","description":"Total number of items requested"},"completed_items":{"type":"integer","title":"Completed Items","description":"Number of items completed"},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"When the upload link expires"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the request was created"},"created_by":{"type":"string","title":"Created By","description":"User who created the request"},"questionnaire_from_pyr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Questionnaire From Pyr","description":"Questionnaire processing status for previous year return (if applicable for this intake request)","example":"COMPLETED"},"document_checklist_suggestion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Checklist Suggestion","description":"Document checklist processing status for previous year return (if applicable for this intake request)","example":"COMPLETED"}},"type":"object","required":["id","request_title","status","total_items","completed_items","expires_at","created_at","created_by"],"title":"DocumentUploadRequestSummaryResponse","description":"Schema for summarized document upload request response (for lists)"},"DocumentUploadRequestUpdate":{"properties":{"action":{"type":"string","title":"Action","description":"Action to perform: 'revoke' or 'extend'","example":"revoke"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Reason for the action (required for revoke)","example":"Client uploaded documents via email instead"},"extend_days":{"anyOf":[{"type":"integer","maximum":90.0,"minimum":1.0},{"type":"null"}],"title":"Extend Days","description":"Number of days to extend (required for extend action)","example":7}},"type":"object","required":["action"],"title":"DocumentUploadRequestUpdate","description":"Schema for updating a document upload request"},"DocumentUploadResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether the upload was successful","default":true},"message":{"type":"string","title":"Message","description":"Success message","example":"Document uploaded successfully"},"item_id":{"type":"string","format":"uuid","title":"Item Id","description":"ID of the request item that was uploaded"},"document_id":{"type":"string","format":"uuid","title":"Document Id","description":"ID of the uploaded document"},"document_name":{"type":"string","title":"Document Name","description":"Name of the uploaded document"},"file_size":{"type":"integer","title":"File Size","description":"Size of the uploaded file in bytes"},"uploaded_at":{"type":"string","format":"date-time","title":"Uploaded At","description":"When the document was uploaded"},"request_info":{"$ref":"#/components/schemas/UploadRequestInfo","description":"Information about the upload request"}},"type":"object","required":["message","item_id","document_id","document_name","file_size","uploaded_at","request_info"],"title":"DocumentUploadResponse","description":"Schema for successful dashboard document upload"},"DocumentVersionListResponse":{"properties":{"document_name":{"type":"string","title":"Document Name","description":"Name of the document","example":"Invoice_2024.pdf"},"version_group_id":{"type":"string","format":"uuid","title":"Version Group Id","description":"Unique ID grouping all versions together"},"total_versions":{"type":"integer","title":"Total Versions","description":"Total number of versions","example":3},"latest_version":{"type":"integer","title":"Latest Version","description":"Latest version number","example":3},"versions":{"items":{"$ref":"#/components/schemas/DocumentResponse"},"type":"array","title":"Versions","description":"List of all versions ordered by version number (descending)"}},"type":"object","required":["document_name","version_group_id","total_versions","latest_version","versions"],"title":"DocumentVersionListResponse","description":"Response for document version history listing"},"DocumentWorkflowAction":{"type":"string","enum":["approve","reject","reopen"],"title":"DocumentWorkflowAction","description":"Enum for document workflow actions."},"DownloadUrlResponse":{"properties":{"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url"},"download_token":{"type":"string","title":"Download Token"},"expires_in_seconds":{"type":"integer","title":"Expires In Seconds"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"},"use_proxy":{"type":"boolean","title":"Use Proxy","default":true},"file_size_mb":{"type":"number","title":"File Size Mb"},"recommended_method":{"type":"string","title":"Recommended Method"}},"type":"object","required":["download_token","expires_in_seconds","expires_at","file_size_mb","recommended_method"],"title":"DownloadUrlResponse","description":"Response schema for download URL generation with hybrid approach"},"EligibilityAuditDocument":{"properties":{"document_type":{"type":"string","title":"Document Type","description":"Document type code"},"field_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field Name","description":"Field/attribute when relevant"},"display_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Label","description":"Human-readable label"},"role":{"type":"string","title":"Role","description":"accepted | used | possible_overlap | excluded"},"amount_total":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"null"}],"title":"Amount Total"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note"}},"type":"object","required":["document_type","role"],"title":"EligibilityAuditDocument","description":"One accepted, used, or flagged document source in eligibility audit."},"EligibilityAuditMetric":{"properties":{"key":{"type":"string","title":"Key","description":"Stable metric key"},"label":{"type":"string","title":"Label","description":"Human-readable label"},"value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"title":"Value"}},"type":"object","required":["key","label"],"title":"EligibilityAuditMetric","description":"One computed value shown in form-level eligibility audit."},"EligibilityAuditTrail":{"properties":{"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary"},"computed_values":{"items":{"$ref":"#/components/schemas/EligibilityAuditMetric"},"type":"array","title":"Computed Values"},"documents":{"items":{"$ref":"#/components/schemas/EligibilityAuditDocument"},"type":"array","title":"Documents"},"review_notes":{"items":{"type":"string"},"type":"array","title":"Review Notes"}},"type":"object","title":"EligibilityAuditTrail","description":"Why a form was or was not considered eligible."},"EntityScopeEnum":{"type":"string","enum":["primary","spouse"],"title":"EntityScopeEnum","description":"Entity scope for document refs (primary vs spouse)."},"EntityTypeEnum":{"type":"string","enum":["CLIENT","SPOUSE","DEPENDENT"],"title":"EntityTypeEnum","description":"Entity types for SSN information"},"EvaluateCompletenessResponse":{"properties":{"tax_year":{"type":"string","title":"Tax Year"},"flags_written":{"type":"integer","title":"Flags Written"}},"type":"object","required":["tax_year","flags_written"],"title":"EvaluateCompletenessResponse"},"ExtractedAttributeItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Extracted attribute ID"},"key":{"type":"string","title":"Key","description":"Vendor attribute name (e.g., 'Box1', 'Part I, Line 1')"},"display_name":{"type":"string","title":"Display Name","description":"Human-readable display name"},"datatype":{"type":"string","title":"Datatype","description":"Data type of the attribute"},"value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"items":{},"type":"array"},{"type":"object"},{"type":"null"}],"title":"Value","description":"Formatted attribute value: single-line string for ADDRESS, otherwise unchanged (str, number, bool, list, or dict)."},"confidence_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Confidence Score","description":"Confidence score (0.0 to 1.0)"},"bounding_regions":{"items":{"$ref":"#/components/schemas/BoundingRegion"},"type":"array","title":"Bounding Regions","description":"Bounding regions where the attribute was found"},"status":{"type":"string","title":"Status","description":"Validation status (e.g., 'NEEDS_REVIEW', 'VERIFIED')"},"document_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Key","description":"Original line item name (for LLM extractions only)"}},"type":"object","required":["id","key","display_name","datatype","value","status"],"title":"ExtractedAttributeItem","description":"Individual extracted attribute item"},"ExtractionVersion":{"type":"string","enum":["v1","v2"],"title":"ExtractionVersion","description":"Which extraction generation a specific document is on.\n\nPer-DOCUMENT (vs the per-doctype ``new_extraction_flow_enabled`` flag): the\ndoctype flag says which generation a type uses going forward, but a document\nalready extracted under the old generation stays on it until re-extracted.\nThe frontend uses this to pick the v1/v2 review UI for each document.\n\n* ``V2`` — extracted via the v2 flow (data in the new typed store).\n* ``V1`` — extracted via the legacy flow (data in the legacy store)."},"FigureOverrideListResponse":{"properties":{"tax_year":{"type":"integer","title":"Tax Year"},"prior_year":{"type":"integer","title":"Prior Year"},"overrides":{"items":{"$ref":"#/components/schemas/FigureOverrideOut"},"type":"array","title":"Overrides"}},"type":"object","required":["tax_year","prior_year","overrides"],"title":"FigureOverrideListResponse","description":"Everything ever done to this client-year's prior figures."},"FigureOverrideOut":{"properties":{"override_id":{"type":"string","format":"uuid","title":"Override Id"},"line_key":{"type":"string","title":"Line Key"},"value_text":{"type":"string","title":"Value Text","description":"The corrected figure, as TEXT. Money never becomes a float here for the same reason it does not in the basis: these numbers exist to agree with a filed return line by line."},"extracted_value_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extracted Value Text","description":"What the MACHINE read, kept beside the correction for ever and carried unchanged across a re-correction. None where it read nothing at all — a figure supplied for a line the extractor never found is an ORIGINAL entry, not a correction of one, and a reviewer in year three needs to tell those apart."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Why, from a closed list. Required only where the extraction was CONFIDENT and still wrong; a line already hedged, or never read, needs none — the run has already said it was unsure."},"observed_source_page":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Observed Source Page"},"corrected_by":{"type":"string","title":"Corrected By"},"corrected_at":{"type":"string","format":"date-time","title":"Corrected At"},"superseded_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Superseded At","description":"This correction was replaced by a later one on the same line. Null on a live correction.\n\nPresent only on the history read. Superseded rows stay on the record because 'somebody corrected this twice, and here is what they said the first time' is what a reviewer asks in year three, and a live-only view cannot answer it."},"revoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Revoked At","description":"This correction was withdrawn and the line fell back to what the extraction read. The row is kept rather than deleted: that it was made and then undone is part of the account."},"revoked_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revoked By","description":"WHO withdrew it, which is not always who made it. The history drawer pairs a name with the timestamp of the LATEST event on the row, so without this it printed the original corrector beside the moment somebody else withdrew their correction — a change attributed to the wrong person on the one screen that exists to attribute changes. Recorded on the row since the withdrawal statement was written; never read back until now."},"superseded_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Superseded By","description":"WHO replaced it. Same reasoning as `revoked_by`. Taken from `updated_by`, and only on a row that was actually superseded — on a live row that column is just the creator, and reporting it as a replacement would invent an event."}},"type":"object","required":["override_id","line_key","value_text","corrected_by","corrected_at"],"title":"FigureOverrideOut","description":"One correction to the firm's read of a prior-year return.\n\nNot the return, which is a historical fact nobody may change, and not the\nextraction, which stays on record as what the machine saw. This is the third\nthing: a workpaper assertion, attributed and reversible."},"FigureOverrideResponse":{"properties":{"override":{"$ref":"#/components/schemas/FigureOverrideOut"},"digest":{"$ref":"#/components/schemas/YoyDigestResponse","description":"The RECOMPUTED digest, in the same transaction. Not a convenience: correcting a line that was never read moves a row across the compared/not-compared partition, every derived row recomputes, and `summary` is generated here and rendered verbatim — so a client that patched the row itself would show a table and a sentence that disagree."}},"type":"object","required":["override","digest"],"title":"FigureOverrideResponse","description":"The correction, and the comparison as it now stands."},"FilingStatusEnum":{"type":"string","enum":["SINGLE","MARRIED_FILING_JOINTLY","MARRIED_FILING_SEPARATELY","HEAD_OF_HOUSEHOLD","QUALIFYING_SURVIVING_SPOUSE"],"title":"FilingStatusEnum"},"FilingStatusResponse":{"properties":{"value":{"$ref":"#/components/schemas/FilingStatusEnum","description":"The filing status enum value"},"label":{"type":"string","title":"Label","description":"Human-readable label for the filing status"}},"type":"object","required":["value","label"],"title":"FilingStatusResponse","description":"Response schema for filing status with value and human-readable label.\nProvides both the enum value and display-friendly text for frontend use.","example":{"label":"Single","value":"SINGLE"}},"FilingTypeEnum":{"type":"string","enum":["INDIVIDUAL_1040","SOLO_SCHEDULE_C"],"title":"FilingTypeEnum"},"FilingTypeResponse":{"properties":{"value":{"$ref":"#/components/schemas/FilingTypeEnum","description":"The filing type enum value"},"label":{"type":"string","title":"Label","description":"Human-readable label for the filing type"}},"type":"object","required":["value","label"],"title":"FilingTypeResponse","description":"Response schema for filing type with value and human-readable label.\nProvides both the enum value and display-friendly text for frontend use.","example":{"label":"Individual (Form 1040)","value":"INDIVIDUAL_1040"}},"FlagResolutionRequest":{"properties":{"action":{"$ref":"#/components/schemas/ResolutionAction","description":"keep_both | keep_selected | reopen."},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"Optional reviewer rationale, recorded in the audit trail."},"reason_code":{"anyOf":[{"$ref":"#/components/schemas/ReasonCode"},{"type":"null"}],"description":"One-tap disposition reason. REQUIRED to dismiss (keep_both) an ASSERT flag."},"resolved_role":{"anyOf":[{"$ref":"#/components/schemas/ClearsAtRole"},{"type":"null"}],"description":"Role acting (PREPARER | REVIEWER | PARTNER); solo = single actor."},"keep_document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Keep Document Id","description":"REQUIRED for keep_selected: the copy to KEEP. Must be one of the flag's two documents; the other one is soft-deleted."}},"type":"object","required":["action"],"title":"FlagResolutionRequest","description":"CPA resolution of a cross-document flag (spec §13). Vocabularies validated at the edge."},"FlagResponse":{"properties":{"id":{"type":"string","title":"Id"},"document_id":{"type":"string","title":"Document Id"},"tax_year":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tax Year"},"source":{"type":"string","title":"Source"},"family":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Family"},"flag_type":{"type":"string","title":"Flag Type"},"tier":{"type":"string","title":"Tier"},"clears_at":{"type":"string","title":"Clears At"},"severity":{"type":"string","title":"Severity"},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence"},"related_document_ids":{"items":{"type":"string"},"type":"array","title":"Related Document Ids"},"display":{"type":"object","title":"Display"},"evidence":{"type":"object","title":"Evidence"},"disposition":{"type":"string","title":"Disposition"},"resolution_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolution Note"},"resolution_reason_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolution Reason Code"},"resolved_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolved Role"},"resolved_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolved By"},"resolved_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolved At"},"detector_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detector Version"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","document_id","tax_year","source","family","flag_type","tier","clears_at","severity","confidence","related_document_ids","display","evidence","disposition","resolution_note","resolution_reason_code","resolved_role","resolved_by","resolved_at","detector_version","created_at","updated_at"],"title":"FlagResponse","description":"A cross-document flag serialized for the list + compare/resolve panel (spec §7/§13)."},"FolderContentsResponse":{"properties":{"current_folder":{"$ref":"#/components/schemas/CurrentFolderInfo"},"items":{"items":{"anyOf":[{"$ref":"#/components/schemas/FolderItem"},{"$ref":"#/components/schemas/DocumentItem"}]},"type":"array","title":"Items"},"summary":{"$ref":"#/components/schemas/FolderSummary"},"pagination":{"$ref":"#/components/schemas/app__schemas__common__pagination__PaginationMeta","description":"Pagination metadata"}},"type":"object","required":["current_folder","items","summary","pagination"],"title":"FolderContentsResponse"},"FolderCreateRequest":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name","description":"Folder name"},"parent_folder_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Folder Id","description":"Parent folder ID (null for root)"},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description","description":"Folder description"},"tags":{"items":{"$ref":"#/components/schemas/TagAssignment"},"type":"array","title":"Tags","description":"Folder tags (key-value pairs only)"}},"type":"object","required":["name"],"title":"FolderCreateRequest"},"FolderItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"type":{"type":"string","title":"Type","description":"Item type identifier","default":"folder"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"path":{"type":"string","title":"Path"},"tags":{"items":{"additionalProperties":{"type":"string"},"type":"object"},"type":"array","title":"Tags"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"is_shared":{"type":"boolean","title":"Is Shared","description":"True when this folder has an active direct share with the client. Use share_id to call DELETE /dms/shares/{share_id} to unshare.","default":false},"share_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Share Id","description":"Active share ID when is_shared=True. Used for the Unshare action."},"is_shared_via_folder":{"type":"boolean","title":"Is Shared Via Folder","description":"True when this folder's nearest shared ancestor gives the client access. The client can browse into this folder via that share. Use folder_share_id to identify (and optionally unshare) the ancestor share.","default":false},"folder_share_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Folder Share Id","description":"Share ID of the nearest shared ancestor folder when is_shared_via_folder=True."}},"type":"object","required":["id","name","description","path","created_at","updated_at"],"title":"FolderItem","description":"Unified folder item for the items array"},"FolderResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"parent_folder_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Folder Id"},"path":{"type":"string","title":"Path"},"breadcrumb":{"items":{"$ref":"#/components/schemas/BreadcrumbItem"},"type":"array","title":"Breadcrumb"},"tags":{"items":{"$ref":"#/components/schemas/TagSchema"},"type":"array","title":"Tags"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"created_by":{"type":"string","title":"Created By"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"updated_by":{"type":"string","title":"Updated By"}},"type":"object","required":["id","name","description","parent_folder_id","path","breadcrumb","tags","created_at","created_by","updated_at","updated_by"],"title":"FolderResponse"},"FolderSummary":{"properties":{"total_items":{"type":"integer","title":"Total Items"},"total_folders":{"type":"integer","title":"Total Folders"},"total_documents":{"type":"integer","title":"Total Documents"},"total_size":{"type":"integer","title":"Total Size"}},"type":"object","required":["total_items","total_folders","total_documents","total_size"],"title":"FolderSummary","description":"Summary information for folder contents"},"FolderUpdateRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"null"}],"title":"Name","description":"Folder name"},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description","description":"Folder description"},"parent_folder_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Folder Id","description":"Parent folder ID (null for root)"},"tags":{"anyOf":[{"items":{"$ref":"#/components/schemas/TagAssignment"},"type":"array"},{"type":"null"}],"title":"Tags","description":"Folder tags (key-value pairs only)"}},"type":"object","title":"FolderUpdateRequest"},"ForgotPasswordRequest":{"properties":{"email":{"type":"string","maxLength":100,"format":"email","title":"Email","description":"Email address (max 100 characters)"},"recaptcha_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recaptcha Token","description":"Google reCAPTCHA token (v3 or v2)"},"recaptcha_version":{"anyOf":[{"$ref":"#/components/schemas/RecaptchaVersion"},{"type":"null"}],"description":"reCAPTCHA version used (v3 or v2)"}},"type":"object","required":["email"],"title":"ForgotPasswordRequest"},"ForgotPasswordResponse":{"properties":{"message":{"type":"string","title":"Message","default":"If an account exists with this email, you will receive an OTP."}},"type":"object","title":"ForgotPasswordResponse"},"FormInstance":{"properties":{"form_code":{"type":"string","title":"Form Code","description":"e.g. 1040, SCH_2"},"instance_number":{"type":"integer","title":"Instance Number","description":"1-based; >1 for multiple instances (e.g. Schedule C)"},"display_order":{"type":"integer","title":"Display Order","description":"Display order of form in list"},"display_label":{"type":"string","title":"Display Label","description":"e.g. Form 1040, Schedule 2"},"form_eligibility_status":{"type":"string","title":"Form Eligibility Status","description":"Always ELIGIBLE in forms[]","default":"ELIGIBLE"},"status":{"$ref":"#/components/schemas/WorkpaperFormStatusEnum","description":"Form calculation status. CALCULATED: all lines done. PARTIAL: some lines pending or error. NOT_CALCULATED: not run. ERROR: form-level failure."},"lines":{"items":{"$ref":"#/components/schemas/LineDetail"},"type":"array","title":"Lines","description":"Per-line data (ordered by display_order)"},"has_workpaper_pdf":{"type":"boolean","title":"Has Workpaper Pdf","description":"True when a per-form workpaper PDF has been generated and stored (artifact storage).","default":false},"workpaper_pdf_storage_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workpaper Pdf Storage Key","description":"Storage key for this form's workpaper PDF; use with GET .../workpaper/pdf?storage_key= to get presigned URL."},"eligibility_audit":{"anyOf":[{"$ref":"#/components/schemas/EligibilityAuditTrail"},{"type":"null"}],"description":"User-facing audit trail for why this form was included."},"transmitted_parts":{"items":{"type":"string"},"type":"array","title":"Transmitted Parts","description":"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":{"items":{"type":"string"},"type":"array","title":"Workpaper Only Parts","description":"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."}},"type":"object","required":["form_code","instance_number","display_order","display_label","status"],"title":"FormInstance","description":"One eligible form with line details (form_eligibility_status = ELIGIBLE)."},"FormLineInputUsed":{"properties":{"form_code":{"type":"string","title":"Form Code","description":"Form code (e.g. SCH_B, 1040)"},"line_number":{"type":"string","title":"Line Number","description":"Line identifier"},"display_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Label","description":"Human-readable label"},"instance_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Instance Number","description":"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":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"null"}],"title":"Contributing Value","description":"Actual value used when the form line had a value; null when the input was blank (see blank_reason)."},"blank_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Blank Reason","description":"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":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Blank Display Message","description":"User-facing message for blank_reason (e.g. 'No dependents for CTC'). Use for tooltip or secondary text when contributing_value is null."}},"type":"object","required":["form_code","line_number"],"title":"FormLineInputUsed","description":"One form line that was an input to this line's calculation.\n\n- When the form line had a value: contributing_value is set; frontend can show and format it.\n- When the form line was blank (N/A): contributing_value is null; use blank_reason and\n  blank_display_message so the frontend can show e.g. \"—\" or \"N/A\" with tooltip \"No dependents for CTC\"."},"FormLineRef":{"properties":{"form_code":{"type":"string","title":"Form Code","description":"Form code (e.g. SCH_B, 1040)"},"line_number":{"type":"string","title":"Line Number","description":"Line identifier (e.g. 1, 2b)"},"display_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Label","description":"Human-readable label (e.g. Schedule B, Line 1)"},"instance_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Instance Number","description":"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":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Suggestion","description":"User-facing suggestion"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Optional reason"}},"type":"object","required":["form_code","line_number"],"title":"FormLineRef","description":"One form line reference in dependencies or missing_inputs."},"FormTieOut":{"properties":{"form_type":{"type":"string","title":"Form Type"},"status":{"type":"string","title":"Status","description":"match | reconciled | unreconciled | no_basis."},"is_red":{"type":"boolean","title":"Is Red","description":"True only on a TRUE unreconciled delta past tolerance."},"extracted_total":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extracted Total","description":"Sum of the contributing children's control-line box values."},"summary_total":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary Total","description":"The statement total to reconcile against (None when no basis exists)."},"residual":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Residual"},"message":{"type":"string","title":"Message","default":""},"child_document_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Child Document Ids"}},"type":"object","required":["form_type","status","is_red"],"title":"FormTieOut","description":"Per-form reconciliation of a split bundle (sum-of-children vs the statement, where available)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ImpactPreviewEntity":{"properties":{"instance_id":{"type":"string","format":"uuid","title":"Instance Id"},"group_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Group Code","description":"The repeatable group's trigger code, e.g. `rental_properties.did_confirm_repeat`."},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label","description":"What the CPA calls it — an address, an EIN, a business name. NULL for instances written before `canonical_key` existed, which the response-derived match path still handles."}},"type":"object","required":["instance_id"],"title":"ImpactPreviewEntity","description":"One entity a replace would re-read."},"ImpactPreviewFigure":{"properties":{"question_code":{"type":"string","title":"Question Code"},"question_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Question Label","description":"The questionnaire's own wording for `question_code` — 'Prior-year AGI', not `estimated_taxes.prior_year_agi`. Resolved on read from the question catalog. None when the catalog no longer carries the code: render the code itself rather than a blank, because on a destructive confirmation an unnamed line is worse than an ugly one."},"instance_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Instance Id"},"kind":{"type":"string","title":"Kind","description":"Which floor class holds it: `trap`, `election` or `carry_safe`. Decides the wording, not the membership."},"why":{"type":"string","title":"Why","description":"The CPA-facing reason, e.g. 'Confirm DIRECTION: the carryover OUT to next year, not the loss used this year.'"}},"type":"object","required":["question_code","kind","why"],"title":"ImpactPreviewFigure","description":"One figure that may not come back."},"ImpactPreviewResponse":{"properties":{"state":{"type":"string","title":"State","description":"`NORMAL` — answers are attributable and clearable. `BACKFILLED` — a run exists but predates provenance tracking, so nothing can be cleared automatically. `EMPTY` — nothing on this questionnaire can be traced to a prior-year return."},"answers_from_this_run":{"type":"integer","title":"Answers From This Run","description":"Response ROWS the retract would remove. Larger than 'fields you can see' — gates and instance-scoped leaves are rows a form does not render as separate boxes — and reporting the truer number is the point: an under-count makes a destructive act look smaller.","default":0},"entities":{"items":{"$ref":"#/components/schemas/ImpactPreviewEntity"},"type":"array","title":"Entities"},"at_risk_figures":{"items":{"$ref":"#/components/schemas/ImpactPreviewFigure"},"type":"array","title":"At Risk Figures","description":"Figures that come from last year and cannot be re-derived from this year's documents. Phrased to the CPA as 'may not come back' rather than 'will be lost' — most replaces recover them; the point is knowing which to check if they do not."},"answers_you_edited":{"type":"integer","title":"Answers You Edited","default":0},"answers_your_client_gave":{"type":"integer","title":"Answers Your Client Gave","default":0},"answers_on_file":{"type":"integer","title":"Answers On File","description":"Everything on the questionnaire, which is what the backfilled ledger reports in place of a clearable count.","default":0},"is_destructive":{"type":"boolean","title":"Is Destructive","description":"Whether pressing Replace removes anything at all. False for BACKFILLED and EMPTY — a dialog promising to clear 148 answers when it will clear none is the empty-ledger error in the other direction.","default":false},"version_token":{"type":"string","title":"Version Token","description":"What this ledger was computed against. Echo it back on replace: a mismatch is a 409, because the questionnaire moved while the dialog was open and the ledger the CPA read no longer describes what would happen. Server-derived, so a client cannot fabricate agreement.","default":""},"checklist_rows_at_risk":{"type":"integer","title":"Checklist Rows At Risk","description":"Document-checklist rows derived from the return being replaced. NOT removed by default — this is what the 'also retire the document checklist' box would take. Zero means the box has no consequence and should not be offered.","default":0},"checklist_items_client_can_see":{"type":"integer","title":"Checklist Items Client Can See","description":"Of those rows, how many the client has already been sent a request for. The expensive subset: the ask is out and cannot be unsent, which is why retiring the checklist is opt-in rather than automatic.","default":0},"wrong_taxpayer_prechecked":{"type":"boolean","title":"Wrong Taxpayer Prechecked","description":"Whether the dialog should open with the wrong-taxpayer box already ticked. Driven by the SUPERSEDED run's recorded pre-flight outcome, never by the check on the new file: the box asserts something about the OLD return, and the commonest sequence — old file wrong, new file right — makes the new check MATCH and would leave it unticked exactly when it matters. Uploads predating the gate have no recorded outcome and start unticked, which is the safe default.","default":false},"wrong_taxpayer_available":{"type":"boolean","title":"Wrong Taxpayer Available","default":true},"wrong_taxpayer_unavailable_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Wrong Taxpayer Unavailable Reason","description":"Why the wrong-taxpayer branch is withheld. It is disabled for backfilled clients because its copy promises a removal the code cannot perform, and the branch also supersedes the document and pulls back checklist items."}},"type":"object","required":["state"],"title":"ImpactPreviewResponse","description":"What replacing this return would do, before it does it.\n\nThree states, and `BACKFILLED` is the one that matters at launch, because\nevery client is backfilled until they are re-analysed. It is the INVERTED\nledger, not the empty one: rendering \"nothing was filled in from the current\nreturn\" on a questionnaire full of answers is visibly false, and a warning a\nCPA can see is wrong is worse than no warning."},"ImportError":{"properties":{"row":{"type":"integer","minimum":1.0,"title":"Row","description":"Row number where error occurred (1-based, excluding header)","example":2},"external_id":{"type":"string","title":"External Id","description":"External ID of the client that failed","example":"RJ001"},"error":{"type":"string","title":"Error","description":"Error message","example":"Invalid email format"}},"type":"object","required":["row","external_id","error"],"title":"ImportError","description":"Schema for import error information","example":{"error":"Invalid email format","external_id":"RJ001","row":2}},"ImportedClientInfo":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Client ID (UUID as string)","example":"123e4567-e89b-12d3-a456-426614174000"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id","description":"External client ID","example":"RJ001"},"full_name":{"type":"string","title":"Full Name","description":"Client full name","example":"John Doe"},"readable_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Readable Id","description":"Human-readable client ID","example":"CL-000001"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Import status (for dry run)","example":"validated"}},"type":"object","required":["full_name"],"title":"ImportedClientInfo","description":"Schema for imported client information","example":{"external_id":"RJ001","full_name":"John Doe","id":"123e4567-e89b-12d3-a456-426614174000","readable_id":"CL-000001"}},"IndeterminateForm":{"properties":{"form_code":{"type":"string","title":"Form Code","description":"e.g. SCH_1, 1040"},"display_label":{"type":"string","title":"Display Label","description":"e.g. Schedule 1"},"form_eligibility_status":{"type":"string","title":"Form Eligibility Status","description":"Always INDETERMINATE here","default":"INDETERMINATE"},"dependencies":{"$ref":"#/components/schemas/Dependencies","description":"What eligibility depends on"},"missing_inputs":{"$ref":"#/components/schemas/MissingInputs","description":"What is missing"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"User-facing one-line reason (e.g. 'Answer the questions below to determine if this form applies.')."},"eligibility_audit":{"anyOf":[{"$ref":"#/components/schemas/EligibilityAuditTrail"},{"type":"null"}],"description":"User-facing audit trail for this form's current eligibility decision."},"priority":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Priority","description":"Lower = resolve first"},"recommended_first_action":{"anyOf":[{"$ref":"#/components/schemas/RecommendedFirstAction"},{"type":"null"}],"description":"Do this first"}},"type":"object","required":["form_code","display_label"],"title":"IndeterminateForm","description":"Form whose eligibility is not yet determined (dependencies + missing_inputs)."},"InputsUsed":{"properties":{"questions":{"items":{"$ref":"#/components/schemas/QuestionInputUsed"},"type":"array","title":"Questions","description":"Questionnaire answers used"},"documents":{"items":{"$ref":"#/components/schemas/DocumentInputUsed"},"type":"array","title":"Documents","description":"Documents used"},"form_lines":{"items":{"$ref":"#/components/schemas/FormLineInputUsed"},"type":"array","title":"Form Lines","description":"Form lines used"}},"type":"object","title":"InputsUsed","description":"What was used to compute a line (questions, documents, form lines)."},"IntakeRequestItemPatch":{"properties":{"document_type":{"anyOf":[{"$ref":"#/components/schemas/DocumentTypeEnum"},{"type":"null"}],"description":"Document type for this item (e.g. W2, FORM_1099_INT). Only provided fields are updated.","example":"W2"},"notes":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Notes","description":"Optional CPA notes for this document item (only provided fields are updated)","example":"Client will upload by Friday"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags","description":"Tags/instance names for this item (e.g. employer names). Pass empty list to clear.","example":["ACME Corp","CHASE BANK"]},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description","description":"Instructions for this specific document type (only provided fields are updated)","example":"Please upload all W-2 forms from 2024"}},"additionalProperties":false,"type":"object","title":"IntakeRequestItemPatch","description":"Schema for partial update of an intake request item (CPA notes, tags, description, document_type)."},"IntakeRequestItemStatus":{"type":"string","enum":["DRAFT","PENDING","UPLOADED","MAPPED","ANSWERED","SKIPPED","REJECTED"],"title":"IntakeRequestItemStatus","description":"Enum for intake request item status"},"IntakeRequestStatus":{"type":"string","enum":["DRAFT","EMAIL_SENT","ACTIVE","COMPLETED","EXPIRED","REVOKED"],"title":"IntakeRequestStatus","description":"Enum for intake request status"},"IntakeRequestTargetFolderUpdate":{"properties":{"target_folder_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Target Folder Id","description":"Target folder ID for future uploads. null = root folder; UUID = specific folder. Only affects uploads after this update."}},"type":"object","title":"IntakeRequestTargetFolderUpdate","description":"Schema for updating only the target folder of an intake request.\n\nUse the dedicated PATCH .../target-folder endpoint. null = root folder;\nUUID = specific folder. Only affects uploads after this update."},"InviteAcceptRequest":{"properties":{"token":{"type":"string","maxLength":256,"minLength":16,"title":"Token"},"name":{"type":"string","maxLength":100,"minLength":1,"title":"Name"},"password":{"type":"string","maxLength":128,"minLength":8,"title":"Password"}},"type":"object","required":["token","name","password"],"title":"InviteAcceptRequest","description":"Body of the public acceptance call.\n\nCarries no email and no role by design: the email comes from the invite (the\ntoken proves control of that mailbox) and so does the role. Accepting either\nfrom the client would let an invitee choose their own privileges.\n\nThe token travels in this body too, NOT in the URL path — see\ndocs/settings_team_members_v1.md §4.5b. A path segment is captured by\nreverse-proxy access logs, browser history, Referer headers and front-end\ntelemetry, none of which this codebase controls."},"InviteAcceptResponse":{"properties":{"access_token":{"type":"string","title":"Access Token"},"token_type":{"type":"string","title":"Token Type","default":"bearer"},"user_details":{"type":"object","title":"User Details"}},"type":"object","required":["access_token","user_details"],"title":"InviteAcceptResponse"},"InviteCreateRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email","description":"Email address to invite"},"role":{"$ref":"#/components/schemas/UserRole","description":"Role granted on acceptance (ADMIN or USER)","default":"USER"},"name":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Name","description":"Optional display name"}},"type":"object","required":["email"],"title":"InviteCreateRequest"},"InviteCreatedResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"type":{"$ref":"#/components/schemas/TeamMemberType"},"email":{"type":"string","title":"Email"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"role":{"$ref":"#/components/schemas/UserRole"},"status":{"$ref":"#/components/schemas/TeamMemberStatus"},"last_login_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Login At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"invited_by":{"anyOf":[{"$ref":"#/components/schemas/InvitedByRef"},{"type":"null"}]},"invite_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Invite Expires At"},"is_self":{"type":"boolean","title":"Is Self","default":false},"invite_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invite Url"}},"type":"object","required":["id","type","email","role","status","created_at"],"title":"InviteCreatedResponse","description":"The new invite plus the raw invite link.\n\n``invite_url`` is returned exactly once, at creation, and never again — the\ndatabase only holds the token's hash. It exists so an admin can paste the\nlink into Slack when firm mail quarantines our messages, which is the most\nlikely launch-week support ticket."},"InvitePreviewRequest":{"properties":{"token":{"type":"string","maxLength":256,"minLength":16,"title":"Token"}},"type":"object","required":["token"],"title":"InvitePreviewRequest","description":"Body of the public preview call. Token in the body, never the path."},"InvitePreviewResponse":{"properties":{"tenant_name":{"type":"string","title":"Tenant Name"},"email":{"type":"string","title":"Email"},"role":{"$ref":"#/components/schemas/UserRole"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"},"invited_by_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invited By Name"}},"type":"object","required":["tenant_name","email","role","expires_at"],"title":"InvitePreviewResponse","description":"What the unauthenticated acceptance page may see.\n\nIntentionally minimal: firm name, the invited address, and the role. No\ninviter email, no member counts, no tenant id — this endpoint is reachable\nby anyone holding a URL."},"InviteUpdateRequest":{"properties":{"role":{"$ref":"#/components/schemas/UserRole"}},"type":"object","required":["role"],"title":"InviteUpdateRequest","description":"Change the role a pending invite will grant on acceptance."},"InvitedByRef":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"}},"type":"object","required":["id"],"title":"InvitedByRef"},"JobResponse":{"properties":{"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Id","description":"Current or latest evaluation job id"},"status":{"$ref":"#/components/schemas/RegenerationDisplayStatusEnum","description":"DB workpaper_regeneration_job_status_enum + IDLE when no job"},"last_outcome":{"anyOf":[{"$ref":"#/components/schemas/WorkpaperStatusOutcomeEnum"},{"type":"null"}],"description":"DB workpaper_status_outcome_enum when job completed"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When the job finished"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"When status=FAILED, error details"}},"type":"object","required":["status"],"title":"JobResponse","description":"Evaluation job details (replaces regeneration at level 1). Uses DB-backed enums."},"K1Activity":{"properties":{"activity_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Activity Name","description":"Name of the activity"},"activity_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Activity Number","description":"Activity sequence number"},"attributes":{"items":{"$ref":"#/components/schemas/K1NormalizedAttribute"},"type":"array","title":"Attributes","description":"Attributes for this activity"}},"type":"object","title":"K1Activity","description":"Rental or other activity reported on a K1 form."},"K1Form":{"properties":{"form_type":{"type":"string","title":"Form Type","description":"Document identifier for the form type"},"tax_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tax Year","description":"Tax year for this K1"},"tax_year_beginning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tax Year Beginning","description":"Fiscal year start date"},"tax_year_ending":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tax Year Ending","description":"Fiscal year end date"},"is_final_k1":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Final K1","description":"Whether this is a final K1"},"is_amended_k1":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Amended K1","description":"Whether this is an amended K1"},"is_ocr":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Ocr","description":"Whether this was OCR-processed"},"summary":{"$ref":"#/components/schemas/K1FormSummary","description":"Form summary metadata"},"sections":{"items":{"$ref":"#/components/schemas/K1Section"},"type":"array","title":"Sections","description":"Sections containing extracted attributes"},"activities":{"anyOf":[{"items":{"$ref":"#/components/schemas/K1Activity"},"type":"array"},{"type":"null"}],"title":"Activities","description":"Activities reported on the form"}},"type":"object","required":["form_type","summary","sections"],"title":"K1Form","description":"Normalized representation of a single K1 form type (1065, 1041, 1120S, or K-3)."},"K1FormSummary":{"properties":{"issuer":{"anyOf":[{"$ref":"#/components/schemas/K1FormSummaryParty"},{"type":"null"}],"description":"Issuer party details"},"recipient":{"anyOf":[{"$ref":"#/components/schemas/K1FormSummaryParty"},{"type":"null"}],"description":"Recipient party details"},"profit_loss_capital":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Profit Loss Capital","description":"Profit, loss, and capital percentages"},"modifications":{"anyOf":[{},{"type":"null"}],"title":"Modifications","description":"Any modifications to the K1"}},"type":"object","title":"K1FormSummary","description":"Summary metadata extracted from the K1 form header."},"K1FormSummaryParty":{"properties":{"tax_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tax Id","description":"Tax identification number"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Party name"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address","description":"Party address"}},"type":"object","title":"K1FormSummaryParty","description":"Issuer or recipient party information from a K1 form."},"K1NormalizedAttribute":{"properties":{"id":{"type":"string","title":"Id","description":"Unique identifier for this extracted attribute"},"key":{"type":"string","title":"Key","description":"Attribute key used for programmatic lookups"},"vendor_attribute_name":{"type":"string","title":"Vendor Attribute Name","description":"Original vendor-assigned attribute name"},"display_name":{"type":"string","title":"Display Name","description":"Human-readable label for the attribute"},"datatype":{"type":"string","title":"Datatype","description":"Data type of the attribute value"},"display_order":{"type":"integer","title":"Display Order","description":"Sort order for UI rendering"},"value":{"title":"Value","description":"Extracted value for the attribute"},"is_user_updateable":{"type":"boolean","title":"Is User Updateable","description":"Whether the user can edit this value","default":true},"confidence_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence Score","description":"Model confidence score"},"status":{"type":"string","title":"Status","description":"Review status of the attribute","default":"NEEDS_REVIEW"},"is_user_updated":{"type":"boolean","title":"Is User Updated","description":"Whether the user has modified this value","default":false},"bounding_regions":{"items":{},"type":"array","title":"Bounding Regions","description":"Bounding regions for the attribute on the source document"}},"type":"object","required":["id","key","vendor_attribute_name","display_name","datatype","display_order"],"title":"K1NormalizedAttribute","description":"Single extracted attribute within a K1 normalized section."},"K1NormalizedResponse":{"properties":{"document_id":{"type":"string","title":"Document Id","description":"Document ID that was extracted"},"extraction_source":{"type":"string","title":"Extraction Source","description":"Extraction engine used","default":"LLM"},"extraction_job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extraction Job Id","description":"Extraction job identifier"},"standard_1065":{"anyOf":[{"$ref":"#/components/schemas/K1Form"},{"type":"null"}],"description":"Schedule K-1 (Form 1065)"},"standard_1041":{"anyOf":[{"$ref":"#/components/schemas/K1Form"},{"type":"null"}],"description":"Schedule K-1 (Form 1041)"},"standard_1120s":{"anyOf":[{"$ref":"#/components/schemas/K1Form"},{"type":"null"}],"description":"Schedule K-1 (Form 1120-S)"},"schedule_k3":{"anyOf":[{"$ref":"#/components/schemas/K1Form"},{"type":"null"}],"description":"Schedule K-3"},"state_k1_information":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"State K1 Information","description":"State-level K1 information"},"supplemental_information":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Supplemental Information","description":"Supplemental information statements"},"foreign_disclosures":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Foreign Disclosures","description":"Foreign transaction disclosures"},"section_199as":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Section 199As","description":"Section 199A qualified business income"},"ubti":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Ubti","description":"Unrelated business taxable income"},"form_1099s":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Form 1099S","description":"Associated Form 1099 information"},"form_w2s":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Form W2S","description":"Associated Form W-2 information"}},"type":"object","required":["document_id"],"title":"K1NormalizedResponse","description":"Complete K1 extraction response in the normalized envelope shape."},"K1Section":{"properties":{"key":{"type":"string","title":"Key","description":"Section identifier key"},"display_name":{"type":"string","title":"Display Name","description":"Human-readable section title"},"display_order":{"type":"integer","title":"Display Order","description":"Sort order for UI rendering"},"attributes":{"items":{"$ref":"#/components/schemas/K1NormalizedAttribute"},"type":"array","title":"Attributes","description":"Attributes within this section"}},"type":"object","required":["key","display_name","display_order","attributes"],"title":"K1Section","description":"Logical grouping of attributes within a K1 form."},"LeafNode1099C":{"properties":{"node_type":{"type":"string","const":"leaf","title":"Node Type","description":"Discriminator: this is a leaf","default":"leaf"},"id":{"type":"string","format":"uuid","title":"Id","description":"Extracted attribute ID"},"attribute_identifier":{"type":"string","title":"Attribute Identifier","description":"DB attribute_identifier (e.g. FORM_1099_INT_BOX_1)"},"key":{"type":"string","title":"Key","description":"Vendor attribute name (dotted path, e.g. form_1099_int.box_1)"},"display_name":{"type":"string","title":"Display Name","description":"Human-readable label for this row"},"datatype":{"type":"string","title":"Datatype","description":"Data type of the attribute"},"value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"items":{},"type":"array"},{"type":"object"},{"type":"null"}],"title":"Value","description":"Extracted value (formatted for ADDRESS / OBJECT / ARRAY datatypes)"},"confidence_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Confidence Score","description":"Confidence score (0.0 to 1.0)"},"bounding_regions":{"items":{"$ref":"#/components/schemas/BoundingRegion"},"type":"array","title":"Bounding Regions","description":"Bounding regions where the attribute was found"},"status":{"type":"string","title":"Status","description":"Validation status (e.g., 'NEEDS_REVIEW', 'VERIFIED')"},"document_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Key","description":"Original line item name (for LLM extractions only)"}},"type":"object","required":["id","attribute_identifier","key","display_name","datatype","value","status"],"title":"LeafNode1099C","description":"One extracted attribute as a leaf in the 1099-C tree."},"LineCalculationStatusEnum":{"type":"string","enum":["PENDING","CALCULATED","ERROR","BLANK","MANUAL","CACHED","SUCCESS"],"title":"LineCalculationStatusEnum","description":"Per-line calculation status. DB: core_schema.line_calculation_status_enum."},"LineDataTypeEnum":{"type":"string","enum":["CURRENCY","NUMBER","STRING","DATE","PERCENTAGE","BOOLEAN"],"title":"LineDataTypeEnum","description":"Data type for line value display/validation."},"LineDetail":{"properties":{"line_number":{"type":"string","title":"Line Number","description":"e.g. 1, 7, 9a"},"pdf_field_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pdf Field Name","description":"AcroForm fully qualified field name for this line (PDF widget id for client viewers)."},"display_order":{"type":"integer","title":"Display Order","description":"Display order (lower = earlier)"},"data_type":{"anyOf":[{"$ref":"#/components/schemas/LineDataTypeEnum"},{"type":"null"}],"description":"CURRENCY, NUMBER, STRING, etc."},"field_type":{"anyOf":[{"$ref":"#/components/schemas/PdfFieldTypeEnum"},{"type":"null"}],"description":"PDF field type for rendering and editing. More granular than data_type: checkbox, currency, date, text, name, ssn, routing_number, account_number, other."},"bounding_box":{"anyOf":[{"$ref":"#/components/schemas/BoundingBox"},{"type":"null"}],"description":"PDF coordinates for overlay"},"line_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Line Label","description":"Human-readable line label"},"value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"title":"Value","description":"Calculated or entered value"},"status":{"$ref":"#/components/schemas/LineCalculationStatusEnum","description":"Line calculation status. PENDING: not yet calculated—provide items in missing_inputs. CALCULATED: value computed—see inputs_used and calculation_explanation. BLANK: no value (N/A for this client)—blank_display_message explains. ERROR: calculation failed—error_message explains."},"transmitted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Transmitted","description":"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":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Form Part","description":"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":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Formula","description":"Expression e.g. 0.2 * SCH_C_LINE_31"},"calculation_explanation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculation Explanation","description":"One-sentence summary of how this line was derived (e.g. '20% of Schedule C Line 31 ($25,000) = $5,000.')."},"calculation_breakdown":{"anyOf":[{"items":{"$ref":"#/components/schemas/CalculationStep"},"type":"array"},{"type":"null"}],"title":"Calculation Breakdown","description":"Equation steps for CPA (e.g. label + value + operator between steps)."},"needs_review":{"type":"boolean","title":"Needs Review","description":"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.","default":false},"review_severity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Severity","description":"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":{"anyOf":[{"items":{"$ref":"#/components/schemas/ReviewFlag"},"type":"array"},{"type":"null"}],"title":"Review Flags","description":"One entry per review flag on this line, for a review queue that does not parse the breakdown."},"dependencies":{"anyOf":[{"$ref":"#/components/schemas/Dependencies"},{"type":"null"}],"description":"What this line depends on"},"missing_inputs":{"anyOf":[{"$ref":"#/components/schemas/MissingInputs"},{"type":"null"}],"description":"What is missing for this line"},"inputs_used":{"anyOf":[{"$ref":"#/components/schemas/InputsUsed"},{"type":"null"}],"description":"What was used to compute this line"},"inputs_read":{"anyOf":[{"$ref":"#/components/schemas/InputsUsed"},{"type":"null"}],"description":"What was read/inspected for this line, including inputs that did not contribute a value."},"last_calculated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Calculated At","description":"When this line was last (re)calculated."},"last_calculated_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Last Calculated By","description":"User id who triggered the calculation; null if system/unknown."},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"When status=ERROR, reason for failure"},"blank_display_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Blank Display Message","description":"When status=BLANK, short user-friendly reason for UI (e.g. 'No wages')"},"is_reconstructed":{"type":"boolean","title":"Is Reconstructed","description":"True when this line was synthesized from definitions/audit because no computed row was persisted.","default":false},"trace_completeness":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trace Completeness","description":"Trace quality: 'full' (manual annotations), 'auto' (proxy-only inputs/result), or None (no trace)."},"trace_version":{"type":"integer","title":"Trace Version","description":"Trace schema version for forward compatibility.","default":1}},"type":"object","required":["line_number","display_order","status"],"title":"LineDetail","description":"Per-line data for an eligible form (audit trail for CPA)."},"MatchSuggestionResponse":{"properties":{"document_id":{"type":"string","format":"uuid","title":"Document Id","description":"ID of the document"},"item_upload_id":{"type":"string","format":"uuid","title":"Item Upload Id","description":"ID of the intake request upload record (tenant_client_intake_request_uploads.id)"},"current_item_id":{"type":"string","format":"uuid","title":"Current Item Id","description":"ID of the current item (other/voluntary)"},"suggested_item":{"$ref":"#/components/schemas/MatchSuggestionSuggestedItem","description":"Suggested item details (id, document type, instance name, classification, confidence)"},"request_title":{"type":"string","title":"Request Title","description":"Title of the intake request","example":"2024 Tax Documents"}},"type":"object","required":["document_id","item_upload_id","current_item_id","suggested_item","request_title"],"title":"MatchSuggestionResponse","description":"Schema for match suggestion response"},"MatchSuggestionSuggestedItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"ID of the suggested item to match to"},"document_type":{"type":"string","title":"Document Type","description":"Document type of the suggested item","example":"W2"},"instance_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Instance Name","description":"Instance name requested for the suggested item","example":"ACME Corporation"},"document_classification":{"type":"string","title":"Document Classification","description":"DEPRECATED raw classification string from automatic classification. Prefer document_type_identifier (resolved from the canonical document_type_id).","example":"W2"},"document_type_identifier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Type Identifier","description":"Canonical document_identifier of the suggested-match document's CURRENT type, resolved from document_type_id. Stable routing/compare key; falls back to the legacy classification when the document has no canonical type id.","example":"W2"},"classified_instance_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Classified Instance Name","description":"Instance name from automatic classification","example":"ACME Corporation"},"match_confidence":{"type":"number","title":"Match Confidence","description":"Instance name match confidence score (0-100)","example":95.5}},"type":"object","required":["id","document_type","document_classification","match_confidence"],"title":"MatchSuggestionSuggestedItem","description":"Nested schema for suggested item details in match suggestion response."},"McpConnectionResponse":{"properties":{"mcp_enabled":{"type":"boolean","title":"Mcp Enabled","description":"Whether this organization may use the connector."},"server_url":{"type":"string","title":"Server Url","description":"The MCP endpoint. Must be entered EXACTLY as given — OAuth discovery compares this string rather than normalizing it. Empty when the server has no ELAN_MCP_RESOURCE_URL set, which means the deployment is not ready to accept connectors."},"transport":{"type":"string","title":"Transport","default":"streamable-http"},"auth_header":{"type":"string","title":"Auth Header","description":"Header carrying the credential.","default":"Authorization"},"auth_scheme":{"type":"string","title":"Auth Scheme","description":"Sent as ``Authorization: Bearer <api key>``.","default":"Bearer"},"active_key_count":{"type":"integer","title":"Active Key Count","description":"Live keys for this organization. Zero means the connector cannot be used yet however it is configured — the setup screen should lead with 'create a key' in that state."},"tools":{"items":{"$ref":"#/components/schemas/McpConnectionTool"},"type":"array","title":"Tools","default":[]},"setup":{"items":{"$ref":"#/components/schemas/McpSetupStep"},"type":"array","title":"Setup","default":[]},"notes":{"items":{"type":"string"},"type":"array","title":"Notes","description":"Caveats worth showing next to the steps rather than burying in docs — read-only scope, and that access follows the credential rather than the person holding it.","default":[]}},"type":"object","required":["mcp_enabled","server_url","active_key_count"],"title":"McpConnectionResponse","description":"Everything the Settings page needs to render connection details.\n\nDeliberately one call. The page has to answer \"is this on, where do I\npoint it, do I have a key, and how do I wire it up\" together — split\nacross four endpoints it renders half-configured states that read as\nbugs."},"McpConnectionTool":{"properties":{"name":{"type":"string","title":"Name"},"summary":{"type":"string","title":"Summary"}},"type":"object","required":["name","summary"],"title":"McpConnectionTool","description":"One tool, as the setup screen describes it to a firm."},"McpSetupStep":{"properties":{"client":{"type":"string","title":"Client","description":"Which AI tool this snippet is for."},"instructions":{"type":"string","title":"Instructions"},"snippet":{"type":"string","title":"Snippet","description":"Copy-paste command or config. ``<YOUR_API_KEY>`` is a placeholder — the real key is NEVER interpolated here, so this response stays safe to render, screenshot and paste into a support ticket.","default":""}},"type":"object","required":["client","instructions"],"title":"McpSetupStep","description":"One instruction in the connection guide."},"MemberUpdateRequest":{"properties":{"role":{"anyOf":[{"$ref":"#/components/schemas/UserRole"},{"type":"null"}]},"status":{"anyOf":[{"$ref":"#/components/schemas/TeamMemberStatus"},{"type":"null"}]}},"type":"object","title":"MemberUpdateRequest","description":"Change an existing member's role and/or status.\n\nBoth fields optional; at least one required. Only ACTIVE and INACTIVE are\nsettable — SUSPENDED is a platform-side action, and there is deliberately no\nvalue that deletes anybody."},"MemberUpdateResponse":{"properties":{"member":{"$ref":"#/components/schemas/TeamMemberResponse"},"assigned_workflow_count":{"type":"integer","title":"Assigned Workflow Count","default":0}},"type":"object","required":["member"],"title":"MemberUpdateResponse","description":"NOTE: revoked_invite_count reports invitations withdrawn as a side effect\nof offboarding, so the admin learns that an outgoing colleague's pending\ngrants went with them rather than discovering it from a confused invitee."},"MessageDetailResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Response status"},"message_id":{"type":"string","format":"uuid","title":"Message Id","description":"Unique identifier for the message"},"conversation_id":{"type":"string","format":"uuid","title":"Conversation Id","description":"Conversation this message belongs to"},"sender":{"$ref":"#/components/schemas/MessageSender","description":"Who sent the message (USER/SYSTEM)"},"message_type":{"$ref":"#/components/schemas/MessageType","description":"Type of message (USER/SYSTEM)"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Plain text message content"},"markdown_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Markdown Message","description":"Markdown formatted message content"},"sequence_number":{"type":"integer","minimum":1.0,"title":"Sequence Number","description":"Message sequence number in conversation"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the message was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the message was last updated"},"rating":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rating","description":"User rating (UP/DOWN) if rated"},"comment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment","description":"User comment with rating if provided"},"citations":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Citations","description":"Citations and references for the message"},"conversation_type":{"$ref":"#/components/schemas/ConversationType","description":"Type of conversation"},"conversation_status":{"$ref":"#/components/schemas/ConversationStatus","description":"Current status of the conversation"}},"type":"object","required":["status","message_id","conversation_id","sender","message_type","sequence_number","created_at","updated_at","conversation_type","conversation_status"],"title":"MessageDetailResponse","description":"Response model for detailed message information.","example":{"citations":{"irs_gov":{"title":"IRS Publication","url":"https://www.irs.gov/..."}},"comment":"Very helpful response","conversation_id":"123e4567-e89b-12d3-a456-426614174001","conversation_status":"ACTIVE","conversation_type":"TAX_RESEARCH","created_at":"2024-01-15T10:30:00Z","message":"Here's the answer to your tax question...","message_id":"123e4567-e89b-12d3-a456-426614174000","message_type":"SYSTEM","rating":"UP","sender":"SYSTEM","sequence_number":2,"status":"success","updated_at":"2024-01-15T10:30:00Z"}},"MessageHistoryItem":{"properties":{"role":{"type":"string","enum":["user","assistant"],"title":"Role"},"text":{"type":"string","title":"Text"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"}},"additionalProperties":false,"type":"object","required":["role","text"],"title":"MessageHistoryItem","description":"One displayable message — either the user's input or the assistant's\nparsed-narrative reply. Internal tool_use / tool_result messages are\nfiltered out by the route handler before this shape is produced."},"MessageHistoryResponse":{"properties":{"conversation_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Conversation Id","description":"None when no conversation exists yet for this scope."},"messages":{"items":{"$ref":"#/components/schemas/MessageHistoryItem"},"type":"array","title":"Messages"}},"additionalProperties":false,"type":"object","title":"MessageHistoryResponse","description":"Body of GET /internal/api/cpa-chat/messages."},"MessageRating":{"type":"string","enum":["UP","DOWN"],"title":"MessageRating"},"MessageRatingRequest":{"properties":{"rating":{"$ref":"#/components/schemas/MessageRating","description":"Rating for the message (UP or DOWN)"},"comment":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Comment","description":"Optional comment for the rating (max 2000 characters)"}},"type":"object","required":["rating"],"title":"MessageRatingRequest","description":"Request schema for rating a message.","example":{"comment":"Very helpful response","rating":"UP"}},"MessageRatingResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Status of the rating operation"},"message_id":{"type":"string","format":"uuid","title":"Message Id","description":"ID of the rated message"}},"type":"object","required":["status","message_id"],"title":"MessageRatingResponse","description":"Response schema for message rating.","example":{"message_id":"123e4567-e89b-12d3-a456-426614174000","status":"SUCCESS"}},"MessageSender":{"type":"string","enum":["USER","SYSTEM"],"title":"MessageSender"},"MessageStatus":{"type":"string","enum":["ACCEPTED","THINKING","CANCELLED","COMPLETED","FAILED"],"title":"MessageStatus"},"MessageType":{"type":"string","enum":["USER","SYSTEM"],"title":"MessageType"},"MissingInputs":{"properties":{"questions":{"items":{"$ref":"#/components/schemas/QuestionRef"},"type":"array","title":"Questions","description":"Questions not answered"},"documents":{"items":{"$ref":"#/components/schemas/DocumentRef"},"type":"array","title":"Documents","description":"Documents missing or suggested"},"form_lines":{"items":{"$ref":"#/components/schemas/FormLineRef"},"type":"array","title":"Form Lines","description":"Form lines we need but don't have"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"One-line user-facing reason (e.g. 'Answer the questions below to calculate this line.'). Set whenever any item is missing."}},"type":"object","title":"MissingInputs","description":"What is missing (same shape as Dependencies) plus a user-facing reason."},"PaginatedBulkDocumentStatusResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/DocumentExtractionStatusItem"},"type":"array","title":"Data","description":"List of document status data"},"meta":{"$ref":"#/components/schemas/app__schemas__common__pagination__PaginationMeta","description":"Pagination metadata"},"not_found":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Not Found","description":"List of document IDs not found in extraction table"}},"type":"object","required":["data","meta","not_found"],"title":"PaginatedBulkDocumentStatusResponse","description":"Paginated response schema for bulk document status polling using standard pagination structure"},"PartyDisplay":{"properties":{"initial":{"type":"string","title":"Initial","example":"P"},"short":{"type":"string","title":"Short","example":"Priya"},"full":{"type":"string","title":"Full","example":"Priya Raghunathan · Spouse"},"role_label":{"type":"string","title":"Role Label","example":"Spouse"}},"type":"object","required":["initial","short","full","role_label"],"title":"PartyDisplay","description":"How to render a document's owner. Built server-side, never derived in the browser.\n\n``full`` always carries the name AND the role (\"Priya Raghunathan · Spouse\") so it is safe\nas a tooltip and an accessible name — a wrong guess at ``short`` can then only degrade\ndisplay, never meaning."},"PdfFieldTypeEnum":{"type":"string","enum":["checkbox","currency","date","text","name","ssn","routing_number","account_number","other"],"title":"PdfFieldTypeEnum","description":"Wire/API PDF form field type (LineDetail.field_type).\n\nControls how the field is rendered and edited by the frontend. Lowercase\nvalues are retained for API compatibility — the DB column\n``tax_form_line_definitions.field_type`` was narrowed to a 4-label Postgres\nenum in migration V5.0.29 (see :class:`FieldTypeEnum`); the broader\nlowercase taxonomy here is normalised at the adapter boundary."},"PhaseState":{"properties":{"state":{"type":"string","title":"State"},"must_resolve":{"type":"integer","title":"Must Resolve"},"review_items":{"type":"integer","title":"Review Items"}},"type":"object","required":["state","must_resolve","review_items"],"title":"PhaseState"},"PlanSelection":{"properties":{"document_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Document Ids","description":"App document ids to include. Omit or null for every document."},"questionnaire_groups":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Questionnaire Groups","description":"Questionnaire group keys to include — the first segment of a question code, e.g. 'basic_info'. Omit or null for every group."},"acknowledge_warnings":{"type":"boolean","title":"Acknowledge Warnings","description":"Proceed even though the plan carries warnings a preparer should see first. Send false (the default) to be told about them; send true only after a human has read them and chosen to continue.","default":false}},"additionalProperties":false,"type":"object","title":"PlanSelection","description":"What the preparer ticked in the picker.\n\n☠ `null` AND `[]` MEAN DIFFERENT THINGS, AND THE DIFFERENCE IS THE SAFE DEFAULT.\n  Omitting a field (or sending `null`) means \"everything on that axis\" — so a client that\n  posts only `document_ids` still gets the whole questionnaire, which is what a partially\n  built frontend would expect. An EMPTY LIST means \"none of them\", which is a real choice a\n  preparer can make on one axis; making both axes empty is refused below rather than\n  producing an empty plan."},"PreferenceGroupResponse":{"properties":{"id":{"type":"string","title":"Id"},"label":{"type":"string","title":"Label"},"description":{"type":"string","title":"Description"},"display_order":{"type":"integer","title":"Display Order"}},"type":"object","required":["id","label","description","display_order"],"title":"PreferenceGroupResponse","description":"A section heading in the pane. Served rather than hardcoded so the\nsection copy lives in one place."},"PreferenceOptionResponse":{"properties":{"value":{"type":"string","title":"Value"},"label":{"type":"string","title":"Label"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"type":"object","required":["value","label"],"title":"PreferenceOptionResponse","description":"One choice of an ``ENUM`` preference."},"PreferenceResponse":{"properties":{"key":{"type":"string","title":"Key"},"type":{"$ref":"#/components/schemas/TenantSettingType"},"group":{"type":"string","title":"Group"},"label":{"type":"string","title":"Label"},"description":{"type":"string","title":"Description"},"value":{"title":"Value"},"default_value":{"title":"Default Value"},"is_overridden":{"type":"boolean","title":"Is Overridden"},"impact":{"$ref":"#/components/schemas/TenantSettingImpact"},"display_order":{"type":"integer","title":"Display Order"},"options":{"items":{"$ref":"#/components/schemas/PreferenceOptionResponse"},"type":"array","title":"Options"},"min_value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Min Value"},"max_value":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Value"},"max_length":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Length"},"effect_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Effect Note"},"requires_reevaluation":{"type":"boolean","title":"Requires Reevaluation","default":false},"editable":{"type":"boolean","title":"Editable"}},"type":"object","required":["key","type","group","label","description","value","default_value","is_overridden","impact","display_order","editable"],"title":"PreferenceResponse","description":"One preference: what it is, what it's set to, and who may change it."},"PreferencesMeta":{"properties":{"can_manage_preferences":{"type":"boolean","title":"Can Manage Preferences"},"last_updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Updated At"}},"type":"object","required":["can_manage_preferences"],"title":"PreferencesMeta"},"PreferencesResponse":{"properties":{"groups":{"items":{"$ref":"#/components/schemas/PreferenceGroupResponse"},"type":"array","title":"Groups"},"settings":{"items":{"$ref":"#/components/schemas/PreferenceResponse"},"type":"array","title":"Settings"},"meta":{"$ref":"#/components/schemas/PreferencesMeta"}},"type":"object","required":["groups","settings","meta"],"title":"PreferencesResponse"},"PreferencesUpdateRequest":{"properties":{"values":{"type":"object","minProperties":1,"title":"Values","description":"Preference key to new value. Only these keys are changed.","example":{"tax_return.form_1040sr.enabled":false}}},"type":"object","required":["values"],"title":"PreferencesUpdateRequest","description":"A partial update: only the keys present are touched.\n\nPartial rather than whole-document so two admins editing two sections of\nthe pane cannot clobber each other, and so a client running an older build\ncannot erase a preference it has never heard of by echoing back the map it\nwas given."},"PreviousYearReturnInfo":{"properties":{"is_reupload_allowed":{"type":"boolean","title":"Is Reupload Allowed","description":"True if reupload is allowed (no PREVIOUS_YEAR_RETURN document exists, or questionnaire/document checklist processing failed for that tax year).","example":true},"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id","description":"ID of the PREVIOUS_YEAR_RETURN document when reupload is not allowed."},"document_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Name","description":"Name of the PREVIOUS_YEAR_RETURN document when reupload is not allowed."}},"type":"object","required":["is_reupload_allowed"],"title":"PreviousYearReturnInfo","description":"Previous year return reupload eligibility and document reference for dashboard."},"PreviousYearReturnStateResponse":{"properties":{"tax_year":{"type":"integer","title":"Tax Year","description":"Engagement tax year this state describes"},"has_run":{"type":"boolean","title":"Has Run","description":"Whether any prior-year-return analysis has been recorded for this client and tax year."},"run_kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Kind","description":"'BACKFILLED' for a synthetic run minted for pre-migration data, whose attribution is best-effort and whose answers cannot be cleared automatically. NULL for an ordinary run."},"questionnaire_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Questionnaire Status","description":"Latest questionnaire status for the CURRENT run."},"checklist_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Checklist Status","description":"Latest document-checklist status for the CURRENT run."},"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id","description":"The file this run actually read — resolved from the run record, not from a document-type query. `is_latest` disambiguates within a version group and never across them, so a document query can name a more recently uploaded file than the one whose answers are on screen."},"document_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Name"},"document_unattributed":{"type":"boolean","title":"Document Unattributed","description":"A run exists but no file could be attributed to it — only possible for backfilled history. The panel must say so rather than render a blank current-file line.","default":false},"is_settled":{"type":"boolean","title":"Is Settled","description":"No further progress is expected from this run."},"has_failure":{"type":"boolean","title":"Has Failure","description":"Either half failed. NOTE: the questionnaire half may still have written ~150 answers before the checklist half failed, so this is not evidence that nothing landed."},"is_stale":{"type":"boolean","title":"Is Stale","description":"A non-terminal run whose last event is older than the presumed-dead threshold. FAILED is written only by an in-process except block, so a killed worker produces this state rather than a failure — and this, not FAILED, is the lockout CPAs actually hit."},"is_superseded":{"type":"boolean","title":"Is Superseded","description":"This run was RETIRED by a human decision — the CPA replaced its input — rather than finishing or failing. SUPERSEDED is a terminal status, so `is_settled` is true for it, and without this flag the panel could not tell a retired run from a completed one: it fell through to 'Analysis complete — this year's questionnaire and document checklist were drafted from this return', about a run whose answers had just been cleared. Deliberately NOT folded into `has_failure`: nothing failed, somebody changed their mind about the file, and 'Analysis failed — running it again is usually enough' is both wrong and alarming for that.","default":false},"can_retry":{"type":"boolean","title":"Can Retry","description":"The analysis may be re-run: it failed, or it is presumed dead."},"can_upload":{"type":"boolean","title":"Can Upload","description":"A new analysis may be dispatched. Keyed on RUN STATE, never on document count — a document-keyed rule is silently bypassed by 'Try again', which adds no document."},"last_event_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Event At"},"can_replace_with_file":{"type":"boolean","title":"Can Replace With File","description":"Whether this build offers replacing the return with a DIFFERENT file. False when the feature is off, and false when there is no file on record to supersede — a new return has to become the next version of an existing one, not a loose second document. The panel renders from this rather than probing the route, so a build without the feature shows one action instead of two and a 404.","default":false}},"type":"object","required":["tax_year","has_run","is_settled","has_failure","is_stale","can_retry","can_upload"],"title":"PreviousYearReturnStateResponse","description":"What a client-year's prior-year-return run permits, in one read.\n\nThe three booleans at the end are the point: the frontend should never have\nto re-derive \"can I act?\" from a status string. ``derivePyrCardStateFromFlags``\nalready demonstrates the cost of that — it maps anything that is neither\nFAILED nor both-COMPLETED to \"analysing\", and so has no way to express a run\nthat died, which is why a killed worker leaves the card spinning forever."},"PriorYearDeltaResponse":{"properties":{"current_year":{"type":"integer","title":"Current Year"},"prior_year":{"type":"integer","title":"Prior Year"},"new_sources":{"items":{"$ref":"#/components/schemas/AccountSourceOut"},"type":"array","title":"New Sources"},"disappeared_sources":{"items":{"$ref":"#/components/schemas/AccountSourceOut"},"type":"array","title":"Disappeared Sources"},"matched_sources":{"items":{"$ref":"#/components/schemas/AccountSourceOut"},"type":"array","title":"Matched Sources"},"confidence":{"type":"string","title":"Confidence"}},"type":"object","required":["current_year","prior_year","new_sources","disappeared_sources","matched_sources","confidence"],"title":"PriorYearDeltaResponse","description":"Year-over-year income-source delta — a heuristic review aid (see ``confidence``)."},"ProfileResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"email":{"type":"string","title":"Email"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"role":{"$ref":"#/components/schemas/UserRole"},"tenant":{"$ref":"#/components/schemas/TenantRef"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"last_login_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Login At"}},"type":"object","required":["id","email","role","tenant","created_at"],"title":"ProfileResponse","description":"The Profile pane. Read-only in v1 — password changes route through the\nexisting reset flow rather than a new endpoint."},"PublicDocumentUploadRequestItemResponse":{"properties":{"document_type":{"anyOf":[{"$ref":"#/components/schemas/DocumentTypeEnum"},{"type":"null"}],"description":"Type of document requested (None for voluntary documents)","example":"W2"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Additional instructions for this specific document type","example":"Please upload all W-2 forms from 2024"},"notes":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Notes","description":"Optional notes from CPA for this specific document type request","example":"Client mentioned they will upload this next week"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags","description":"Tags/instance names associated with this document item","example":["CORP - PERSON_ABC","CHASE BANK"]},"is_optional":{"type":"boolean","title":"Is Optional","description":"Whether this document is optional or required","default":false,"example":false},"is_additional_document":{"type":"boolean","title":"Is Additional Document","description":"Whether this is an additional document added by the client","default":false,"example":false},"is_voluntary_document":{"type":"boolean","title":"Is Voluntary Document","description":"Whether this is a voluntary document (no document type, not counted in totals)","default":false,"example":false},"extraction_enabled":{"type":"boolean","title":"Extraction Enabled","description":"Whether to automatically start document extraction after upload for this specific item","default":false,"example":false},"max_files_per_item":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Max Files Per Item","description":"Maximum number of files allowed for this specific document type","default":1},"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier for the request item (scoped to this upload request only, validated via token on each request)"},"display_order":{"type":"integer","title":"Display Order","description":"Display order in the UI"},"status":{"$ref":"#/components/schemas/IntakeRequestItemStatus","description":"Current status of this item"},"edit_count":{"type":"integer","title":"Edit Count","description":"Number of times this item has been edited/reuploaded"},"client_notes":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Client Notes","description":"Optional notes added by the client/user for this document item","example":"This is my W-2 from Acme Corporation"},"document_type_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Type Label","description":"Human-readable label for the document type (None for voluntary documents)","example":"W-2"},"can_modify":{"type":"boolean","title":"Can Modify","description":"Whether this item can still be modified (false if UPLOADED)","default":true,"example":true},"rejection_reason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Rejection Reason","description":"Reason provided when rejecting this document item (only set when status is REJECTED)","example":"Document not available"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the item was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the item was last updated"},"uploaded_documents":{"anyOf":[{"items":{"$ref":"#/components/schemas/UploadedDocumentInfo"},"type":"array"},{"type":"null"}],"title":"Uploaded Documents","description":"List of uploaded documents for this item (only included when status is UPLOADED). Document IDs are scoped to this upload request and validated via token. Sensitive fields (storage_reference, file_hash, folder_id, download_url) are NOT exposed."}},"type":"object","required":["id","display_order","status","edit_count","created_at","updated_at"],"title":"PublicDocumentUploadRequestItemResponse","description":"Schema for document upload request item response (public/client use - no sensitive IDs).\n\nSECURITY: This schema excludes sensitive internal IDs:\n- intake_request_id: Not exposed (prevents enumeration of other requests)\n- uploaded_by: Not exposed in public responses (only for CPA dashboard)\n- tenant_id/client_id: Never exposed in public APIs\n\nItem IDs are scoped to the upload token and validated on each request."},"PublicDocumentUploadResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether the upload was successful","default":true},"message":{"type":"string","title":"Message","description":"Success message","example":"Document uploaded successfully"},"item_id":{"type":"string","format":"uuid","title":"Item Id","description":"ID of the request item that was uploaded"},"document_id":{"type":"string","format":"uuid","title":"Document Id","description":"ID of the uploaded document"},"document_name":{"type":"string","title":"Document Name","description":"Name of the uploaded document"},"file_size":{"type":"integer","title":"File Size","description":"Size of the uploaded file in bytes"},"uploaded_at":{"type":"string","format":"date-time","title":"Uploaded At","description":"When the document was uploaded"},"request_info":{"$ref":"#/components/schemas/UploadRequestInfo","description":"Information about the upload request"}},"type":"object","required":["message","item_id","document_id","document_name","file_size","uploaded_at","request_info"],"title":"PublicDocumentUploadResponse","description":"Schema for successful public document upload"},"PublicUploadRequestDetailsResponse":{"properties":{"request_title":{"type":"string","title":"Request Title","description":"Title of the upload request"},"instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Instructions","description":"General instructions"},"tax_year":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tax Year","description":"Tax year"},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"When the upload link expires"},"status":{"$ref":"#/components/schemas/IntakeRequestStatus","description":"Current status of the request"},"max_edits_per_item":{"type":"integer","title":"Max Edits Per Item","description":"Maximum number of edits/reuploads allowed per item"},"completion_rate":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Completion Rate","description":"Completion rate as a decimal (0.0 to 1.0, e.g., 0.2 for 20%)","example":0.2},"completion_status":{"type":"string","title":"Completion Status","description":"Completion status: 'Pending', 'In Progress', or 'Completed'","example":"In Progress"},"total_documents":{"type":"integer","title":"Total Documents","description":"Total number of documents requested","example":8},"completed_documents":{"type":"integer","title":"Completed Documents","description":"Number of documents completed/uploaded","example":2},"pending_documents":{"type":"integer","title":"Pending Documents","description":"Number of documents still pending","example":6},"rejected_documents":{"type":"integer","title":"Rejected Documents","description":"Number of documents rejected by user","default":0,"example":0},"items":{"items":{"$ref":"#/components/schemas/PublicDocumentUploadRequestItemResponse"},"type":"array","title":"Items","description":"List of document types to upload (regular documents)"},"additional_documents":{"items":{"$ref":"#/components/schemas/PublicDocumentUploadRequestItemResponse"},"type":"array","title":"Additional Documents","description":"List of additional documents added by the client"},"voluntary_documents":{"items":{"$ref":"#/components/schemas/PublicDocumentUploadRequestItemResponse"},"type":"array","title":"Voluntary Documents","description":"List of voluntary documents uploaded without document type (not counted in totals)"},"questionnaire_from_pyr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Questionnaire From Pyr","description":"Questionnaire processing status for previous year return (if applicable for this intake request)","example":"COMPLETED"},"document_checklist_suggestion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Checklist Suggestion","description":"Document checklist processing status for previous year return (if applicable for this intake request)","example":"COMPLETED"}},"type":"object","required":["request_title","expires_at","status","max_edits_per_item","completion_rate","completion_status","total_documents","completed_documents","pending_documents","items"],"title":"PublicUploadRequestDetailsResponse","description":"Schema for public upload request details (what clients see).\n\nSECURITY: This schema excludes all sensitive information:\n- No tenant_id or client_id exposed\n- No internal request IDs exposed\n- No CPA user information exposed\n- Only information needed for client to upload documents"},"PyrFactFeedResponse":{"properties":{"tax_year":{"type":"integer","title":"Tax Year"},"facts":{"items":{"$ref":"#/components/schemas/PyrFactResponse"},"type":"array","title":"Facts"},"last_seq":{"type":"integer","title":"Last Seq","description":"Send back as `after_seq` on the next poll.","default":0},"is_settled":{"type":"boolean","title":"Is Settled","description":"Whether the run has finished. False means more facts are coming; the panel keeps polling.","default":false},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id","description":"The run this feed belongs to. The panel compares it to the one it is holding and, when it changes, clears the feed and rewinds its cursor — a replace starts a new story about a new file, and appending the new run's lines under the old run's would narrate two documents as one. Null when no run exists yet."},"has_run":{"type":"boolean","title":"Has Run","description":"Whether a run exists at all. `is_settled` cannot answer this: with no run there are no statuses, so it is False — indefinitely — and a panel that polls until settled polls forever on the ordinary empty screen.","default":false}},"type":"object","required":["tax_year"],"title":"PyrFactFeedResponse","description":"What the run has found so far.\n\nReadable WHILE the analysis runs, which is the whole point: the answers are\nwritten in one transaction and are invisible until it commits, so a feed\nderived from them would show nothing for fifteen minutes and then\neverything."},"PyrFactResponse":{"properties":{"seq":{"type":"integer","title":"Seq","description":"Monotonic within the run. The cursor a polling panel sends back as `after_seq`, so it appends rather than re-renders — which is what makes the feed read as something happening."},"kind":{"type":"string","title":"Kind","description":"IDENTITY | FIGURE | ENTITY | ANSWER | CHECKLIST | LIMIT | REFUSAL. An unrecognised kind renders as itself rather than breaking the feed — this is narration, and a new kind must never need a migration or a frontend release to appear."},"label":{"type":"string","title":"Label","description":"The fact, in the CPA's language."},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"},"value_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value Text","description":"The figure as text. Money never becomes a float on the way to a screen."},"source_page":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Source Page","description":"The page of the uploaded return this came from. This is what lets a CPA tie a figure to paper in three seconds, and it is the difference between evidence and an assertion."},"confidence":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Confidence"},"fills_question_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fills Question Code","description":"Where this fact is headed on the questionnaire — what turns an observation into something the CPA can see the point of."},"reasoning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reasoning","description":"The extraction's own words, quoted rather than paraphrased. Never phrased as a decision."},"line_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Line Key","description":"For a FIGURE: which headline concept this is — the same key the year-over-year row carries, which is what makes a correction typed on this panel in January and one typed on the comparison in March the SAME object rather than two.\n\nNone on every other kind, and on facts written before the column existed. A figure with no key can still be CONFIRMED (that addresses a `seq`) but must not offer a correction: there is nothing to address it to, and guessing the line from the label risks correcting the wrong one, which is worse than not being able to correct at all."},"question_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Question Label","description":"The questionnaire's own wording for `fills_question_code` — 'Taxpayer First Name', not `basic_info.taxpayer.first_name`. Resolved on read from the question catalog, so it is the wording as it reads today and it repairs facts written before this field existed. None when the fact fills nothing, or when the catalog no longer carries the code: render the code itself rather than a blank."},"question_group":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Question Group","description":"The catalog section the filled question belongs to — 'Business Income', 'Partnership, S Corporation & Estate/Trust Income (Schedule K-1)'. What lets the panel group a hundred answers into the handful of areas a CPA actually thinks in."},"section_order":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Section Order","description":"Where this answer sits in the QUESTIONNAIRE's own order — phase display_order, then phase_order, then the question's display_order, composed into one sortable integer. The panel sorts sections by the smallest value in each, so the prior-year page reads in the order the preparer will meet the questions, rather than by section size. Null for a fact that fills no question and for a code the catalog no longer carries; those sink to the end."},"occurred_at":{"type":"string","format":"date-time","title":"Occurred At"}},"type":"object","required":["seq","kind","label","occurred_at"],"title":"PyrFactResponse","description":"One thing the run found, as the feed renders it."},"QuestionInputUsed":{"properties":{"code":{"type":"string","title":"Code","description":"Question code (template form, e.g. dependents.{i}.first_name)"},"instance_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Instance Id","description":"Questionnaire instance/response id when available"},"instance_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Instance Number","description":"1-based instance number when the question is repeatable"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Question text from questionnaire (e.g. 'What is your filing status?'). Use for UI."},"data_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Type","description":"STRING, NUMBER, DATE, BOOLEAN, ENUM"},"value_used":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"title":"Value Used","description":"Value from questionnaire"},"phase_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phase Code","description":"Questionnaire phase for this question (e.g. Deductions, Income)."}},"type":"object","required":["code"],"title":"QuestionInputUsed","description":"One questionnaire answer that fed a line."},"QuestionRef":{"properties":{"code":{"type":"string","title":"Code","description":"Question code (e.g. q__filing_status)"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Question text from questionnaire definition (e.g. 'What is your filing status?'). Use for UI labels."},"suggestion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Suggestion","description":"User-facing suggestion (e.g. 'Please provide this information in the questionnaire.')"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Why this is needed (e.g. QUESTION_NOT_ANSWERED)"},"phase_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phase Code","description":"Questionnaire phase (e.g. Deductions, Income, Basic Info)."},"instance_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Instance Number","description":"1-based instance number when the question is repeatable (e.g. 1 for dependents.{i}.first_name instance 1)"}},"type":"object","required":["code"],"title":"QuestionRef","description":"One questionnaire reference in dependencies or missing_inputs."},"QuestionnaireResponseBatchCreateRequest":{"properties":{"responses":{"items":{"$ref":"#/components/schemas/QuestionnaireResponseCreate"},"type":"array","minItems":1,"title":"Responses","description":"List of questionnaire responses to create or update","example":[{"instance_number":1,"question_code":"has_w2","source":"manual","values":[{"value_boolean":true}]}]}},"type":"object","required":["responses"],"title":"QuestionnaireResponseBatchCreateRequest","description":"Schema for creating multiple questionnaire responses.","example":{"responses":[{"instance_number":1,"question_code":"has_w2","source":"manual","values":[{"value_boolean":true}]}]}},"QuestionnaireResponseCreate":{"properties":{"question_code":{"type":"string","maxLength":255,"minLength":1,"title":"Question Code","description":"Question code to respond to","example":"has_w2"},"values":{"items":{"$ref":"#/components/schemas/ResponseValueCreate"},"type":"array","minItems":0,"title":"Values","description":"Response values (one for single-value, multiple for multi_choice, empty array to clear)","example":[{"value_boolean":true}]},"source":{"type":"string","title":"Source","description":"Source of the response","default":"manual","example":"manual"},"change_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Change Reason","description":"Reason for change if updating existing response"},"client_comment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Comment","description":"Client comment/note for this question (visible to CPA)","example":"I'm not sure about this, please verify"},"instance_number":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Instance Number","description":"Instance number for repeating questions (1-1000, defaults to 1)","default":1,"example":1},"response_group_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Response Group Id","description":"Response group ID for grouping related responses"},"instance_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Instance Id","description":"Repeatable-group entry this answer belongs to. Required for any question inside a repeatable group; the tax-engine resolves the answer against this entry and DISCARDS an instance-less row."}},"type":"object","required":["question_code","values"],"title":"QuestionnaireResponseCreate","description":"Schema for creating a single questionnaire response.\n\n``instance_id`` IS PART OF THE CONTRACT, and leaving it out of this model was\na latent trap rather than an omission (TD-926). The endpoints the client\nportal actually calls take ``body: dict`` and are registered FIRST, so they\nwin the route match and forward the binding untouched — which is the only\nreason repeatable groups work today. The typed v2 routers are mounted at the\nsame prefixes; the moment the v1 ones are removed, or v2 is registered\nfirst, every answer past a group's first entry would bind to the wrong entry\nor vanish, with no 422 and no log line, because ``model_dump()`` simply drops\na field the model does not declare. The typed schema is also what OpenAPI\nadvertises, so anything generated from it was already wrong.\n\nTyped as ``UUID`` rather than ``str`` deliberately: the tax-engine's contract\nis a UUID and it rejects anything else with a 400 for the WHOLE batch. A\nclient-side ``temp-`` placeholder ([[TD-928]]) now fails at this boundary\nwith a 422 naming the field, which is a better error in the same situation,\nnot a new restriction.","example":{"instance_number":1,"question_code":"has_w2","source":"manual","values":[{"value_boolean":true}]}},"ReadinessResponse":{"properties":{"tax_year":{"type":"string","title":"Tax Year"},"overall_state":{"type":"string","title":"Overall State"},"must_resolve_total":{"type":"integer","title":"Must Resolve Total"},"review_items_total":{"type":"integer","title":"Review Items Total"},"info_total":{"type":"integer","title":"Info Total"},"phases":{"additionalProperties":{"$ref":"#/components/schemas/PhaseState"},"type":"object","title":"Phases"},"intake_completeness":{"anyOf":[{},{"type":"null"}],"title":"Intake Completeness"}},"type":"object","required":["tax_year","overall_state","must_resolve_total","review_items_total","info_total","phases"],"title":"ReadinessResponse","description":"The \"Ready to Prepare?\" gate for a client/tax-year (spec: panel v4)."},"ReasonCode":{"type":"string","enum":["NOT_APPLICABLE","RESOLVED_OUTSIDE","CLIENT_CONFIRMED","DEFERRED","FALSE_POSITIVE"],"title":"ReasonCode"},"RecaptchaVersion":{"type":"string","enum":["v2","v3"],"title":"RecaptchaVersion"},"ReclassifyDocumentRequest":{"properties":{"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"Client ID for the document"},"new_type_id":{"type":"string","format":"uuid","title":"New Type Id","description":"Target supported document type ID (from GET /types)."},"reason_code":{"$ref":"#/components/schemas/DocumentTypeChangeReasonEnum","description":"Why the document is being reclassified."},"reason_note":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Reason Note","description":"Optional free-text note."},"force":{"type":"boolean","title":"Force","description":"Re-apply the type and re-extract even when new_type_id is the type the document ALREADY has. Without this a same-type reclassify is a no-op, which is what blocks converting a document that was extracted by the older system but is already on the correct identifier: the conversion needs the extraction re-run, not a type change. Destructive by design — it supersedes the current review and its extracted attributes, then re-extracts on whichever flow the type is configured for. Rejected when extraction is disabled for the type (nothing to re-run) or the document is a split container.","default":false}},"type":"object","required":["client_id","new_type_id","reason_code"],"title":"ReclassifyDocumentRequest","description":"Request to reclassify a document's type (manual override) + re-extract if eligible."},"ReclassifyDocumentResponse":{"properties":{"document_id":{"type":"string","format":"uuid","title":"Document Id","description":"Document ID"},"new_type_id":{"type":"string","format":"uuid","title":"New Type Id","description":"The newly assigned document type ID"},"reextraction_triggered":{"type":"boolean","title":"Reextraction Triggered","description":"Whether a re-extraction job was enqueued."},"extraction_job_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Extraction Job Id","description":"Re-extraction job ID for polling (if triggered)."},"message":{"type":"string","title":"Message","description":"Human-readable outcome."}},"type":"object","required":["document_id","new_type_id","reextraction_triggered","message"],"title":"ReclassifyDocumentResponse","description":"Reclassify result (HTTP 202). reextraction_triggered is True when the new type has extraction\nenabled (is_active) — a re-extraction job is enqueued; False when the type is extraction-disabled\n— the document is reclassified (type set) but NOT re-extracted (extraction_job_id is null)."},"RecommendedFirstAction":{"properties":{"type":{"type":"string","title":"Type","description":"question | document | form_line"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code","description":"When type=question"},"document_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Type","description":"When type=document"},"form_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Form Code","description":"When type=form_line"},"line_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Line Number","description":"When type=form_line"},"display_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Label","description":"Human-readable label"},"suggestion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Suggestion","description":"User-facing suggestion"}},"type":"object","required":["type"],"title":"RecommendedFirstAction","description":"Single recommended action for indeterminate form (do this first)."},"ReextractWithDocumentTypeResponse":{"properties":{"document_id":{"type":"string","format":"uuid","title":"Document Id","description":"Document ID"},"extraction_job_id":{"type":"string","format":"uuid","title":"Extraction Job Id","description":"Extraction job ID for polling status"},"status":{"type":"string","title":"Status","description":"Initial job status (e.g. ACCEPTED)"}},"type":"object","required":["document_id","extraction_job_id","status"],"title":"ReextractWithDocumentTypeResponse","description":"Response schema for reextract-with-document-type (202 Accepted)."},"RegenerationDisplayStatusEnum":{"type":"string","enum":["IDLE","PENDING","RUNNING","COMPLETED","FAILED"],"title":"RegenerationDisplayStatusEnum","description":"Regeneration status for API (includes IDLE when no job). Same as job enum + IDLE."},"RejectDocumentRequest":{"properties":{"reason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Reason","description":"Optional reason for rejecting this document","example":"Document not available"}},"type":"object","title":"RejectDocumentRequest","description":"Schema for rejecting a document item"},"RelationshipEnum":{"type":"string","enum":["SON","DAUGHTER","FOSTER_CHILD","GRANDCHILD","STEPCHILD","GRANDPARENT","PARENT","BROTHER","HALF_BROTHER","STEP_BROTHER","SISTER","HALF_SISTER","STEP_SISTER","AUNT","UNCLE","NIECE","NEPHEW","NONE","OTHER"],"title":"RelationshipEnum","description":"Enumeration of possible relationships for dependents.\n\nUsed to classify the relationship between the client and their dependent\nfor tax filing purposes."},"RenamedDocumentInfo":{"properties":{"old_name":{"type":"string","title":"Old Name","description":"Original name of the document","example":"invoice.pdf"},"new_name":{"type":"string","title":"New Name","description":"New name after auto-rename","example":"invoice(1).pdf"}},"type":"object","required":["old_name","new_name"],"title":"RenamedDocumentInfo","description":"Information about a document that was renamed during bulk move"},"ReplaceHistoryEntry":{"properties":{"audit_id":{"type":"string","format":"uuid","title":"Audit Id"},"performed_by":{"type":"string","title":"Performed By"},"performed_at":{"type":"string","format":"date-time","title":"Performed At"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"},"wrong_taxpayer":{"type":"boolean","title":"Wrong Taxpayer","default":false},"replaced_the_file":{"type":"boolean","title":"Replaced The File","description":"A new file superseded the old one, rather than the same file being analysed again. The two read very differently.","default":false},"answers_cleared":{"type":"integer","title":"Answers Cleared","default":0},"entries_preserved":{"type":"integer","title":"Entries Preserved","default":0},"entries_removed":{"type":"integer","title":"Entries Removed","default":0},"review_items_opened":{"type":"integer","title":"Review Items Opened","default":0},"checklist_items_withdrawn":{"type":"integer","title":"Checklist Items Withdrawn","default":0},"retired_checklist":{"type":"boolean","title":"Retired Checklist","default":false},"checklist_rows_removed":{"type":"integer","title":"Checklist Rows Removed","default":0},"superseded_document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Superseded Document Id"},"superseded_document_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Superseded Document Name","description":"The NAME of the file this replace retired. Null for a same-file re-analysis, where nothing was superseded."},"new_document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"New Document Id"}},"type":"object","required":["audit_id","performed_by","performed_at"],"title":"ReplaceHistoryEntry","description":"One replace, as the panel's history line renders it."},"ReplaceHistoryResponse":{"properties":{"tax_year":{"type":"integer","title":"Tax Year"},"entries":{"items":{"$ref":"#/components/schemas/ReplaceHistoryEntry"},"type":"array","title":"Entries"}},"type":"object","required":["tax_year"],"title":"ReplaceHistoryResponse","description":"What has happened to this client-year's prior-year return."},"ReplacePreviousYearReturnRequest":{"properties":{"expected_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expected Version","description":"The version token the impact preview was rendered with. Supplied, a mismatch is a 409: the questionnaire changed while the dialog was open, so the ledger the CPA read no longer describes what would happen. Omit only for callers that rendered no preview."},"wrong_taxpayer":{"type":"boolean","title":"Wrong Taxpayer","description":"The return on file belongs to a different taxpayer. Widens the retract to clear machine-written rows under entries a human touched — they are another taxpayer's figures in this client's file. A human's own typed answers are still never deleted.","default":false},"retire_checklist":{"type":"boolean","title":"Retire Checklist","description":"Also retire the document checklist the replaced return produced. **Defaults to false, and that is the behaviour change:** the checklist is the only artefact in a replace the CLIENT can see, and a request already sent cannot be unsent, so it is now kept unless asked for. Left false, the re-analysis ADDS whatever the new return implies that the surviving rows do not already cover — it does not duplicate them. Forced true when `wrong_taxpayer` is set, because those rows ask this client for another person's documents; the dialog does not offer the box on that branch.","default":false},"reason":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Reason","description":"Why it is being replaced, for the operational history. Free text; the dialog offers wrong file, wrong year, incomplete, amended return, AI read it wrong."}},"additionalProperties":false,"type":"object","title":"ReplacePreviousYearReturnRequest","description":"What the CPA confirmed in the dialog."},"ReplacePreviousYearReturnResponse":{"properties":{"new_run_id":{"type":"string","format":"uuid","title":"New Run Id","description":"The run the re-analysis will write under."},"superseded_run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Superseded Run Ids"},"answers_cleared":{"type":"integer","title":"Answers Cleared","description":"Response rows removed. Compare against the preview's `answers_from_this_run`: they agree except for repeat gates, which are counted but never deleted — blank is not false to the fifteen rules that read them, so they are turned off at run completion instead.","default":0},"entries_preserved":{"type":"integer","title":"Entries Preserved","description":"Entries left whole because someone had edited under them.","default":0},"review_items_opened":{"type":"integer","title":"Review Items Opened","description":"Things the replace could not resolve. Each keeps the return out of a signable state until a CPA discharges it.","default":0},"reanalysis_dispatched":{"type":"boolean","title":"Reanalysis Dispatched","description":"Whether the re-analysis was handed to the worker. False means the replace committed and the dispatch did not — the run is recorded and the stale-run sweeper will surface it, rather than the replace being silently rolled back.","default":false},"new_document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"New Document Id","description":"The file the re-analysis will read, when a new one superseded the old. Null when the same file was analysed again."},"new_document_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"New Document Version","description":"Its version within the original document's version group. The old file is still there at the previous version — a replace never hard-deletes, because the return is evidence and the undo needs something to point at."},"checklist_retired":{"type":"boolean","title":"Checklist Retired","description":"Whether the checklist was retired at all. False is the default branch — `checklist_rows_removed` is then 0 and `checklist_rows_kept` carries the count instead. Reported as its own field because zero removed rows is otherwise ambiguous between 'kept by choice' and 'retired, and there was nothing to take'.","default":false},"checklist_rows_removed":{"type":"integer","title":"Checklist Rows Removed","description":"Checklist rows retired because the return they were derived from is gone. Rows the client has already uploaded against are never among them. Always 0 when `checklist_retired` is false.","default":0},"checklist_rows_kept":{"type":"integer","title":"Checklist Rows Kept","description":"Checklist rows from the replaced return left exactly as they are. The default branch's headline number: nothing left the client's list, and the re-analysis will add to it.","default":0},"checklist_items_withdrawn":{"type":"integer","title":"Checklist Items Withdrawn","description":"Requested documents taken off the client's list. Only a never-sent draft, or the wrong-taxpayer branch, produces any.","default":0},"requests_needing_notice":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Requests Needing Notice","description":"Intake requests that lost an item the client could already see. They may have gone looking for it, so these need a word."}},"type":"object","required":["new_run_id"],"title":"ReplacePreviousYearReturnResponse","description":"What the replace did — the same numbers the preview promised."},"ResearchChatRequest":{"properties":{"message":{"type":"string","maxLength":10000,"minLength":1,"title":"Message","description":"User's tax research query"},"conversation_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Conversation Id"},"conversation_type":{"$ref":"#/components/schemas/ConversationType","description":"Tax conversation_type for research (FEDERAL or STATE)","default":"TAX_RESEARCH"}},"type":"object","required":["message"],"title":"ResearchChatRequest"},"ResearchChatResponse":{"properties":{"status":{"type":"string","title":"Status"},"conversation_id":{"type":"string","format":"uuid","title":"Conversation Id"},"user_message_id":{"type":"string","format":"uuid","title":"User Message Id"},"system_message_id":{"type":"string","format":"uuid","title":"System Message Id"},"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id","description":"Background task ID for tracking AI response generation"}},"type":"object","required":["status","conversation_id","user_message_id","system_message_id"],"title":"ResearchChatResponse"},"ResendClientLinkResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether the email was sent successfully","default":true},"message":{"type":"string","title":"Message","description":"Success message","example":"Client link email sent successfully"},"recipient_email":{"type":"string","title":"Recipient Email","description":"Email address where the link was sent"},"status":{"$ref":"#/components/schemas/IntakeRequestStatus","description":"Current status of the intake request (unchanged by resend)","example":"EMAIL_SENT"},"status_label":{"type":"string","title":"Status Label","description":"Human-readable status for UI display.","readOnly":true}},"type":"object","required":["message","recipient_email","status","status_label"],"title":"ResendClientLinkResponse","description":"Schema for resend client link response"},"ResendVerificationRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email","example":"user@example.com"}},"type":"object","required":["email"],"title":"ResendVerificationRequest"},"ResendVerificationResponse":{"properties":{"message":{"type":"string","title":"Message","default":"Verification code has been resent to your email","example":"Verification code has been resent to your email"}},"type":"object","title":"ResendVerificationResponse"},"ResetConversationRequest":{"properties":{"client_id":{"type":"string","format":"uuid","title":"Client Id"},"tax_year":{"type":"integer","maximum":2100.0,"minimum":2000.0,"title":"Tax Year","default":2025}},"additionalProperties":false,"type":"object","required":["client_id"],"title":"ResetConversationRequest","description":"Body for POST /internal/api/cpa-chat/reset.\n\n``tenant_id`` is derived server-side from the JWT bearer token."},"ResetConversationResponse":{"properties":{"reset":{"type":"boolean","title":"Reset","description":"True if a conversation existed for this scope; False if no-op."}},"additionalProperties":false,"type":"object","required":["reset"],"title":"ResetConversationResponse"},"ResetPasswordRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"},"token":{"type":"string","title":"Token","description":"Temporary token received from OTP verification"},"new_password":{"type":"string","maxLength":128,"minLength":8,"title":"New Password","description":"New password with minimum 8 characters"}},"type":"object","required":["email","token","new_password"],"title":"ResetPasswordRequest"},"ResetPasswordResponse":{"properties":{"message":{"type":"string","title":"Message","default":"Password has been reset successfully."}},"type":"object","title":"ResetPasswordResponse"},"ResolutionAction":{"type":"string","enum":["keep_both","keep_selected","reopen"],"title":"ResolutionAction"},"ResponseValueCreate":{"properties":{"value_boolean":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Value Boolean","description":"Boolean value","example":true},"value_number":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"null"}],"title":"Value Number","description":"Number value"},"value_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value Text","description":"Text value","example":"ABC Corporation"},"value_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value Date","description":"Date value in YYYY-MM-DD format"},"choice_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Choice Value","description":"Choice value"}},"type":"object","title":"ResponseValueCreate","description":"Schema for creating a response value.","example":{"value_boolean":true}},"RestorePartyEntry":{"properties":{"document_id":{"type":"string","format":"uuid","title":"Document Id"},"party_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Party Role","description":"What it was before — null means it was undecided."}},"type":"object","required":["document_id"],"title":"RestorePartyEntry","description":"One document's PRIOR party, for undoing a bulk assign."},"ReturnDiagnostic":{"properties":{"code":{"type":"string","title":"Code","description":"Stable machine identifier, e.g. 'FOREIGN_PFIC_EVIDENCE_WITHOUT_GATE'."},"severity":{"type":"string","enum":["high","medium","low"],"title":"Severity","description":"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":{"type":"string","title":"Label","description":"Short headline, e.g. 'Form 8621 may be required'."},"reason":{"type":"string","title":"Reason","description":"What the engine observed and why it matters."},"resolution_hint":{"type":"string","title":"Resolution Hint","description":"The concrete action a preparer takes to clear the diagnostic."},"authority":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authority","description":"IRC/Reg citation supporting the concern."},"implicated_forms":{"items":{"type":"string"},"type":"array","title":"Implicated Forms","description":"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":{"items":{"type":"string"},"type":"array","title":"Evidence","description":"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."}},"type":"object","required":["code","severity","label","reason","resolution_hint"],"title":"ReturnDiagnostic","description":"A finding about the RETURN AS A WHOLE that no single line owns.\n\n``ReviewFlag`` is attached to a ``LineDetail``: it says \"this computed line\nneeds a human\". That channel structurally cannot express the finding that\nmatters most on an international return — *a form that should exist does\nnot*. A form the engine never materialized has no lines, so it has nowhere\nto hang a flag, and the return looks clean precisely when it is most wrong.\n\nForm 8621 is the worked example: its eligibility gate read a questionnaire\nquestion that was never seeded, so a CPA could not answer it, the form never\nmaterialized, and the Schedule K-3 Part VII PFIC data the engine had already\nextracted was silently discarded. Nothing in the response said so. Under IRC\n§6501(c)(8) an unfiled §1298(f) information return holds the assessment\nperiod open on the ENTIRE return, indefinitely — so \"no form, no flag\" is\nnot a cosmetic gap.\n\nDiagnostics are therefore addressed to the return, carry the forms they\nimplicate, and cite the evidence that triggered them. They are recomputed on\nevery read from persisted answers and documents — never stored — so they\ncannot go stale against the data they describe.\n\nStructured, not prose, for the same reason as ``ReviewFlag``: a review queue\nhas to count, group and suppress by ``code``, sort by ``severity``, and show\nthe preparer the one action that clears it."},"RevealApiKeyResponse":{"properties":{"api_key":{"type":"string","title":"Api Key","description":"The full credential. Treat every response carrying this as sensitive: do not log it, and do not cache it client-side."},"key":{"$ref":"#/components/schemas/ApiKeySummary"},"reveal_count":{"type":"integer","title":"Reveal Count","description":"How many times this key has now been read back, including this one. Surface it — a credential revealed repeatedly is a different risk from one revealed once."}},"type":"object","required":["api_key","key","reveal_count"],"title":"RevealApiKeyResponse","description":"Plaintext handed back to the Owner. Audited on the way out."},"ReviewBundleResponse":{"properties":{"doctype":{"type":"string","title":"Doctype"},"display_name":{"type":"string","title":"Display Name"},"schema_version":{"type":"integer","title":"Schema Version"},"tax_year":{"type":"integer","title":"Tax Year"},"fields":{"items":{"type":"object"},"type":"array","title":"Fields"},"layout":{"type":"object","title":"Layout"},"records":{"items":{"type":"object"},"type":"array","title":"Records"}},"additionalProperties":true,"type":"object","required":["doctype","display_name","schema_version","tax_year","fields","layout","records"],"title":"ReviewBundleResponse","description":"Wire payload of ``GET /scribe/review-bundle/...``.\n\nPydantic's default ``extra=\"forbid\"`` is intentionally relaxed\nhere because the bundle's ``fields`` / ``layout`` / ``records``\nshapes evolve faster than the response model can — the FE's\n``wireBundleAdapter`` is the actual type-checker on the consumer\nside. This model serves OpenAPI doc generation, not runtime\nenforcement."},"ReviewFlag":{"properties":{"code":{"type":"string","title":"Code","description":"Stable machine identifier, e.g. 'SCH_A_5B_ESCROW_OVERLAP'."},"severity":{"type":"string","enum":["high","medium","low"],"title":"Severity","description":"Matches ReviewStep.severity."},"label":{"type":"string","title":"Label","description":"Short headline for the flag."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Why the engine could not resolve it."},"resolution_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolution Hint","description":"The concrete action a preparer takes to clear the flag."},"authority":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authority","description":"IRC/Reg citation supporting the concern."}},"type":"object","required":["code","severity","label"],"title":"ReviewFlag","description":"A finding on a line that the engine could not resolve on its own.\n\nStructured rather than a prose string on purpose: a review queue needs to\ncount, group and suppress by ``code``, sort by ``severity``, and show the\npreparer ``resolution_hint`` — the action that clears the flag. A warning a\nreviewer cannot act on is noise."},"RevokeApiKeyResponse":{"properties":{"revoked":{"type":"boolean","title":"Revoked","description":"False when the key was already revoked or does not belong to your organization — revoking is idempotent."}},"type":"object","required":["revoked"],"title":"RevokeApiKeyResponse"},"RevokeShareResponse":{"properties":{"share_id":{"type":"string","format":"uuid","title":"Share Id","description":"UUID of the share that was revoked"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Non-empty when the client still has access to the document via an ancestor folder share after this direct share was revoked."}},"type":"object","required":["share_id"],"title":"RevokeShareResponse","description":"Response returned after revoking a share.\n\nwarnings is non-empty when the document is still accessible to the client\nthrough a folder share (e.g. the document lives inside a shared ancestor folder).\nThe CPA must also move the document out of the shared folder, or unshare\nthe folder, to fully revoke access."},"SSNInfoResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier for the SSN record"},"entity_type":{"$ref":"#/components/schemas/EntityTypeEnum","description":"Type of entity this SSN belongs to (CLIENT, SPOUSE, or DEPENDENT)"},"ssn_masked":{"type":"string","title":"Ssn Masked","description":"Masked SSN showing only last 4 digits"},"ssn_type":{"$ref":"#/components/schemas/SSNTypeEnum","description":"Type of SSN (SSN or ITIN)"}},"type":"object","required":["id","entity_type","ssn_masked","ssn_type"],"title":"SSNInfoResponse","description":"Response schema for SSN information.\n\nThis schema represents encrypted SSN information that is returned to the client.\nThe actual SSN is never returned in plain text - only masked versions are provided.","example":{"entity_type":"CLIENT","id":"550e8400-e29b-41d4-a716-446655440000","ssn_masked":"XXX-XX-1234","ssn_type":"SSN"}},"SSNTypeEnum":{"type":"string","enum":["SSN","ITIN"],"title":"SSNTypeEnum","description":"SSN types"},"SSNUnmaskRequest":{"properties":{"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"ID of the client whose entity's SSN to unmask"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id","description":"ID of the entity (spouse or dependent) whose SSN to unmask. Null for client SSN."},"entity_type":{"$ref":"#/components/schemas/EntityTypeEnum","description":"Type of entity (CLIENT, SPOUSE, or DEPENDENT)"},"reason":{"type":"string","maxLength":500,"minLength":1,"title":"Reason","description":"Reason for unmasking the SSN (for audit purposes)"}},"type":"object","required":["client_id","entity_type","reason"],"title":"SSNUnmaskRequest","description":"Request schema for unmasking SSN"},"SSNUnmaskResponse":{"properties":{"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"ID of the client"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id","description":"ID of the entity (spouse or dependent)"},"entity_type":{"$ref":"#/components/schemas/EntityTypeEnum","description":"Type of entity"},"entity_name":{"type":"string","title":"Entity Name","description":"Name of the entity"},"ssn_id":{"type":"string","format":"uuid","title":"Ssn Id","description":"ID of the SSN record"},"unmasked_ssn":{"type":"string","title":"Unmasked Ssn","description":"Unmasked SSN (only returned to authorized users)"},"reason":{"type":"string","title":"Reason","description":"Reason for unmasking the SSN"}},"type":"object","required":["client_id","entity_type","entity_name","ssn_id","unmasked_ssn","reason"],"title":"SSNUnmaskResponse","description":"Response schema for unmasked SSN"},"SaveAndSendRequest":{"properties":{},"additionalProperties":false,"type":"object","title":"SaveAndSendRequest","description":"Request body for Save and Send (no body required; request_id in path)."},"SaveAndSendResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether the email was sent successfully","default":true},"message":{"type":"string","title":"Message","description":"Success message","example":"Client link email sent successfully"},"recipient_email":{"type":"string","title":"Recipient Email","description":"Email address where the link was sent"},"status":{"$ref":"#/components/schemas/IntakeRequestStatus","description":"Request status after save-and-send (EMAIL_SENT when transitioned from DRAFT, unchanged when resending)","example":"EMAIL_SENT"},"status_label":{"type":"string","title":"Status Label","description":"Human-readable status for UI display.","readOnly":true}},"type":"object","required":["message","recipient_email","status","status_label"],"title":"SaveAndSendResponse","description":"Schema for save-and-send (intake link email) response"},"SaveProgressResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether the save was successful","default":true},"message":{"type":"string","title":"Message","description":"Short message confirming save","default":"Progress saved."},"saved_at":{"type":"string","format":"date-time","title":"Saved At","description":"When the progress was saved (server time)"},"new_uploads_count":{"type":"integer","title":"New Uploads Count","description":"Number of new uploads since last save (used for CPA notification decision)"},"cpas_notified":{"type":"boolean","title":"Cpas Notified","description":"Whether CPAs were notified this time (only when new uploads and debounce passed)"}},"type":"object","required":["saved_at","new_uploads_count","cpas_notified"],"title":"SaveProgressResponse","description":"Schema for save-progress response (client saves without completing)"},"ScheduleCMappingsResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SupportedDocumentAttributesResponse"},"type":"array","title":"Data","description":"List of supported attributes for Profit and Loss Statement"}},"type":"object","required":["data"],"title":"ScheduleCMappingsResponse","description":"Response schema for Schedule C mappings endpoint"},"SeatUsage":{"properties":{"used":{"type":"integer","title":"Used"},"limit":{"type":"integer","title":"Limit"}},"type":"object","required":["used","limit"],"title":"SeatUsage","description":"Seats consumed = ACTIVE users + PENDING invites.\n\nINACTIVE and SUSPENDED users are free on purpose: deactivating is how a firm\nfrees capacity without destroying the attribution history that IRC §6107(b)\nretention depends on."},"SectionNode1099C":{"properties":{"node_type":{"type":"string","const":"section","title":"Node Type","description":"Discriminator: this is a section","default":"section"},"section_key":{"type":"string","title":"Section Key","description":"Stable section key (e.g. PART_I, BOX_A)"},"section_label":{"type":"string","title":"Section Label","description":"Human-readable section label for the UI"},"children":{"items":{"oneOf":[{"$ref":"#/components/schemas/LeafNode1099C"},{"$ref":"#/components/schemas/SectionNode1099C"}],"discriminator":{"propertyName":"node_type","mapping":{"leaf":"#/components/schemas/LeafNode1099C","section":"#/components/schemas/SectionNode1099C"}}},"type":"array","title":"Children","description":"Child nodes (leaves and/or sub-sections)"}},"type":"object","required":["section_key","section_label"],"title":"SectionNode1099C","description":"A nested section in the 1099-C tree (e.g. Part I, or Box A — Basis Reported to IRS)."},"SendMessageRequest":{"properties":{"client_id":{"type":"string","format":"uuid","title":"Client Id"},"tax_year":{"type":"integer","maximum":2100.0,"minimum":2000.0,"title":"Tax Year","default":2025},"message":{"type":"string","maxLength":4000,"minLength":1,"title":"Message","description":"Free-text user message."},"selected_option_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Selected Option Id","description":"When the prior turn was a ClarificationRequest, the id of the option the CPA picked. Mutually compatible with ``message`` (free-text addendum)."},"expected_clarification_version":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Expected Clarification Version","description":"Monotonic clarification version the client expects to resolve. If the server's version is higher, another caller (e.g. second browser tab) already resolved the pending clarification — the router returns 409 ``StaleClarificationReply``."}},"additionalProperties":false,"type":"object","required":["client_id","message"],"title":"SendMessageRequest","description":"Body for POST /internal/api/cpa-chat/messages.\n\n``tenant_id`` and ``cpa_user_id`` are derived server-side from the JWT\nbearer token and are intentionally not part of this payload.\n\nClarification-reply fields (``selected_option_id``,\n``expected_clarification_version``) are optional and additive. When the\nserver-side conversation state is ``AWAITING_CLARIFICATION``, the router\ndispatches to ``Agent.resolve_clarification`` regardless of whether\n``selected_option_id`` was supplied; the agent treats option-id absence\nas a \"free-text reply\" path."},"SendMessageResponse":{"properties":{"outcome_kind":{"type":"string","title":"Outcome Kind","description":"answer | clarification"},"narrative":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Narrative"},"question":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Question"},"options":{"anyOf":[{"items":{"$ref":"#/components/schemas/TurnOptionPayload"},"type":"array"},{"type":"null"}],"title":"Options"},"iterations":{"type":"integer","title":"Iterations"},"tool_calls_made":{"type":"integer","title":"Tool Calls Made"},"tokens_in":{"type":"integer","title":"Tokens In"},"tokens_out":{"type":"integer","title":"Tokens Out"},"cache_read_tokens":{"type":"integer","title":"Cache Read Tokens","default":0},"elapsed_ms":{"type":"integer","title":"Elapsed Ms"},"conversation_id":{"type":"string","format":"uuid","title":"Conversation Id"},"correlation_id":{"type":"string","title":"Correlation Id"},"raw_outcome":{"type":"object","title":"Raw Outcome","description":"Full TurnOutcome JSON for clients that want the canonical shape."}},"additionalProperties":false,"type":"object","required":["outcome_kind","iterations","tool_calls_made","tokens_in","tokens_out","elapsed_ms","conversation_id","correlation_id","raw_outcome"],"title":"SendMessageResponse","description":"Body of the POST /messages response."},"SetDocumentPartyBulkRequest":{"properties":{"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"Client ID for the documents"},"document_ids":{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":500,"minItems":1,"title":"Document Ids","description":"Documents to assign"},"party_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Party Role","description":"TAXPAYER | SPOUSE | JOINT, or null to clear."}},"type":"object","required":["client_id","document_ids","party_role"],"title":"SetDocumentPartyBulkRequest","description":"Assign one party across a selection of documents."},"SetDocumentPartyRequest":{"properties":{"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"Client ID for the document"},"party_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Party Role","description":"TAXPAYER | SPOUSE | JOINT, or null to clear back to undecided. Rejected when the document's type does not permit the role, or when it is a v2-reserved role (DEPENDENT / NOT_ON_RETURN).","example":"SPOUSE"}},"type":"object","required":["client_id","party_role"],"title":"SetDocumentPartyRequest","description":"Set one document's party — whose document it is on a joint return."},"SetDocumentPartyResponse":{"properties":{"applied_count":{"type":"integer","title":"Applied Count"},"skipped_count":{"type":"integer","title":"Skipped Count"},"outcomes":{"items":{"$ref":"#/components/schemas/DocumentPartyOutcome"},"type":"array","title":"Outcomes"}},"type":"object","required":["applied_count","skipped_count","outcomes"],"title":"SetDocumentPartyResponse","description":"Result of a party assignment, single or bulk."},"SharedDocumentDownloadResponse":{"properties":{"download_url":{"type":"string","title":"Download Url","description":"Short-lived presigned S3 URL for downloading the document"}},"type":"object","required":["download_url"],"title":"SharedDocumentDownloadResponse","description":"Response for the shared document download URL endpoint."},"SortOrder":{"type":"string","enum":["asc","desc"],"title":"SortOrder","description":"Sort order enumeration"},"SpouseCreate":{"properties":{"full_name":{"type":"string","maxLength":255,"title":"Full Name","description":"Full legal name of the spouse","example":"Jane Doe"},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Email","description":"Email address for communication (optional)","example":"jane.doe@example.com"},"phone":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Phone","description":"Phone number with country code (optional)","example":"+1-555-123-4567"},"date_of_birth":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date Of Birth","description":"Date of birth in YYYY-MM-DD format (optional)","example":"1992-03-20"},"blind":{"type":"boolean","title":"Blind","description":"Is the spouse blind?","default":false,"example":false},"disabled":{"type":"boolean","title":"Disabled","description":"Is the spouse disabled?","default":false,"example":false},"same_as_taxpayer_address":{"type":"boolean","title":"Same As Taxpayer Address","description":"Whether the spouse uses the same address as the taxpayer (client)","default":false,"example":false},"relationship_type":{"type":"string","title":"Relationship Type","description":"Relationship type (always SPOUSE for spouse records)","default":"SPOUSE","example":"SPOUSE"},"ssn":{"anyOf":[{"type":"string","maxLength":11,"minLength":9},{"type":"null"}],"title":"Ssn","description":"Social Security Number (will be encrypted and stored securely)","example":"987-65-4321"},"address":{"anyOf":[{"$ref":"#/components/schemas/AddressCreate"},{"type":"null"}],"description":"Spouse's address (optional if same_as_taxpayer_address is True)"}},"type":"object","required":["full_name"],"title":"SpouseCreate","description":"Schema for creating a new spouse.\n\nIncludes all spouse information plus SSN for tax filing purposes.\nThe SSN will be encrypted and stored securely.","example":{"address":{"address_line_2":"Apt 4B","city":"New York","state":"NY","street_address":"123 Main Street","zip_code":"10001"},"blind":false,"date_of_birth":"1992-03-20","disabled":false,"email":"jane.doe@example.com","full_name":"Jane Doe","phone":"+1-555-987-6543","same_as_taxpayer_address":false,"ssn":"987-65-4321"}},"SpouseResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier for the spouse record","example":"770f9511-f39c-52e5-b827-557766551111"},"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"ID of the client this spouse belongs to","example":"550e8400-e29b-41d4-a716-446655440000"},"tenant_id":{"type":"string","format":"uuid","title":"Tenant Id","description":"Tenant organization ID","example":"440d7300-d18b-31c3-9605-335544330000"},"full_name":{"type":"string","title":"Full Name","description":"Full legal name of the spouse","example":"Jane Doe"},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Email","description":"Email address","example":"jane.doe@example.com"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone","description":"Phone number","example":"+1-555-987-6543"},"date_of_birth":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date Of Birth","description":"Date of birth","example":"1992-03-20"},"blind":{"type":"boolean","title":"Blind","description":"Is the spouse blind?","example":false},"disabled":{"type":"boolean","title":"Disabled","description":"Is the spouse disabled?","example":false},"same_as_taxpayer_address":{"type":"boolean","title":"Same As Taxpayer Address","description":"Whether the spouse uses the same address as the taxpayer (client)","example":true},"relationship_type":{"type":"string","title":"Relationship Type","description":"Relationship type (always SPOUSE for spouse records)","default":"SPOUSE","example":"SPOUSE"},"address":{"anyOf":[{"$ref":"#/components/schemas/app__schemas__client__address__AddressResponse"},{"type":"null"}],"description":"Spouse's address (if different from taxpayer address)"},"ssn_info":{"anyOf":[{"$ref":"#/components/schemas/SSNInfoResponse"},{"type":"null"}],"description":"Encrypted SSN information (masked for security)"}},"type":"object","required":["id","client_id","tenant_id","full_name","blind","disabled","same_as_taxpayer_address"],"title":"SpouseResponse","description":"Schema for spouse response data.\n\nReturns complete spouse information including encrypted SSN info.\nThe SSN is never returned in plain text for security purposes.","example":{"address":{"address_line_2":"Apt 4B","city":"New York","id":"660f9511-f39c-52e5-b827-557766551111","state":"NY","street_address":"123 Main Street","zip_code":"10001"},"blind":false,"client_id":"550e8400-e29b-41d4-a716-446655440000","date_of_birth":"1992-03-20","disabled":false,"email":"jane.doe@example.com","full_name":"Jane Doe","id":"770f9511-f39c-52e5-b827-557766551111","phone":"+1-555-987-6543","same_as_taxpayer_address":false,"ssn_info":{"entity_type":"SPOUSE","id":"880f9622-f49d-63f6-c938-668877662222","ssn_masked":"XXX-XX-4321","ssn_type":"SSN"},"tenant_id":"440d7300-d18b-31c3-9605-335544330000"}},"SpouseUpdate":{"properties":{"full_name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Full Name","description":"Updated full name","example":"Jane Smith"},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Email","description":"Updated email address","example":"jane.smith@example.com"},"phone":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Phone","description":"Updated phone number","example":"+1-555-987-6543"},"date_of_birth":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date Of Birth","description":"Updated date of birth","example":"1992-03-20"},"blind":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Blind","description":"Updated blind status","example":false},"disabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Disabled","description":"Updated disabled status","example":false},"same_as_taxpayer_address":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Same As Taxpayer Address","description":"Updated same as taxpayer address status","example":false},"ssn":{"anyOf":[{"type":"string","maxLength":11,"minLength":9},{"type":"null"}],"title":"Ssn","description":"Social Security Number (optional - will be encrypted and stored securely if provided)","example":"987-65-4321"},"address":{"anyOf":[{"$ref":"#/components/schemas/AddressCreate"},{"type":"null"}],"description":"Updated spouse address (optional if same_as_taxpayer_address is True)"}},"type":"object","title":"SpouseUpdate","description":"Schema for updating an existing spouse.\n\nAll fields are optional to support partial updates.\nNote: SSN cannot be updated for security reasons.","example":{"address":{"address_line_2":"Suite 200","city":"Los Angeles","state":"CA","street_address":"456 Oak Avenue","zip_code":"90210"},"blind":false,"disabled":false,"email":"jane.smith@example.com","full_name":"Jane Smith","phone":"+1-555-987-6543","same_as_taxpayer_address":false}},"StateListItem":{"properties":{"name":{"type":"string","maxLength":255,"title":"Name","description":"Name of the state","example":"New York"},"iso_code":{"type":"string","maxLength":2,"minLength":2,"title":"Iso Code","description":"Two-letter state code","example":"NY"}},"type":"object","required":["name","iso_code"],"title":"StateListItem","description":"Readable summary of a state for lists and dropdowns.","example":{"iso_code":"NY","name":"New York"}},"StatesResponse":{"properties":{"states":{"items":{"$ref":"#/components/schemas/StateListItem"},"type":"array","title":"States","description":"List of US states","example":[{"iso_code":"AL","name":"Alabama"},{"iso_code":"AK","name":"Alaska"}]},"count":{"type":"integer","title":"Count","description":"Total number of US states","example":50}},"type":"object","required":["states","count"],"title":"StatesResponse","description":"All US states available.","example":{"count":50,"states":[{"iso_code":"AL","name":"Alabama"},{"iso_code":"AK","name":"Alaska"},{"iso_code":"AZ","name":"Arizona"}]}},"StatusEnum":{"type":"string","enum":["DRAFT","ACTIVE","INACTIVE"],"title":"StatusEnum"},"SupportedDocumentAttributesResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"display_name":{"type":"string","title":"Display Name"},"group_display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Group Display Name"},"datatype":{"type":"string","title":"Datatype"},"is_supported":{"type":"boolean","title":"Is Supported"},"is_user_updateable":{"type":"boolean","title":"Is User Updateable"},"is_shown_on_ui":{"type":"boolean","title":"Is Shown On Ui"},"is_active":{"type":"boolean","title":"Is Active"}},"type":"object","required":["id","display_name","group_display_name","datatype","is_supported","is_user_updateable","is_shown_on_ui","is_active"],"title":"SupportedDocumentAttributesResponse"},"SupportedDocumentTypesResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/app__schemas__document_extraction__SupportedDocumentType"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"SupportedDocumentTypesResponse"},"Tab1099C":{"properties":{"tab_key":{"type":"string","title":"Tab Key","description":"Stable tab key. One of: BASIC_INFO (top-of-form metadata: TaxYear, Payer.*, Recipient.*), FORM_1099_INT, FORM_1099_DIV, FORM_1099_OID, FORM_1099_MISC, FORM_1099_B."},"tab_label":{"type":"string","title":"Tab Label","description":"Human-readable tab label"},"nodes":{"items":{"oneOf":[{"$ref":"#/components/schemas/LeafNode1099C"},{"$ref":"#/components/schemas/SectionNode1099C"}],"discriminator":{"propertyName":"node_type","mapping":{"leaf":"#/components/schemas/LeafNode1099C","section":"#/components/schemas/SectionNode1099C"}}},"type":"array","title":"Nodes","description":"Top-level nodes inside this tab"}},"type":"object","required":["tab_key","tab_label"],"title":"Tab1099C","description":"One tab in the 1099-C UI (1099-INT, 1099-DIV, 1099-OID, 1099-MISC, or 1099-B)."},"TagAssignment":{"properties":{"key":{"type":"string","maxLength":100,"minLength":1,"title":"Key","description":"Tag key (must exist)"},"value":{"type":"string","maxLength":255,"minLength":1,"title":"Value","description":"Tag value"}},"type":"object","required":["key","value"],"title":"TagAssignment","description":"Simplified tag assignment schema - only key and value"},"TagDefinitionCreateRequest":{"properties":{"key":{"type":"string","maxLength":100,"minLength":1,"title":"Key","description":"Unique key for the tag"},"display_name":{"type":"string","maxLength":255,"minLength":1,"title":"Display Name","description":"Human-readable display name"},"data_type":{"type":"string","title":"Data Type","description":"Data type of the tag value","default":"string"},"allowed_values":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Values","description":"List of allowed values for enum types"},"color":{"type":"string","title":"Color","description":"Hex color code for UI display","default":"#6B7280"}},"type":"object","required":["key","display_name"],"title":"TagDefinitionCreateRequest","description":"Request schema for creating tag definition"},"TagDefinitionResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"key":{"type":"string","title":"Key"},"display_name":{"type":"string","title":"Display Name"},"data_type":{"type":"string","title":"Data Type"},"is_system":{"type":"boolean","title":"Is System"},"allowed_values":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Values"},"color":{"type":"string","title":"Color"}},"type":"object","required":["id","key","display_name","data_type","is_system","color"],"title":"TagDefinitionResponse","description":"Response schema for tag definition"},"TagDefinitionUpdateRequest":{"properties":{"display_name":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"null"}],"title":"Display Name","description":"Human-readable display name"},"data_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Type","description":"Data type of the tag value"},"allowed_values":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Values","description":"List of allowed values for enum types"},"color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Color","description":"Hex color code for UI display"}},"type":"object","title":"TagDefinitionUpdateRequest","description":"Request schema for updating tag definition"},"TagSchema":{"properties":{"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Id"},"key":{"type":"string","title":"Key"},"display_name":{"type":"string","title":"Display Name"},"value":{"type":"string","title":"Value"},"display_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Value"},"color":{"type":"string","title":"Color","default":"#6B7280"},"is_system":{"type":"boolean","title":"Is System","default":false},"data_type":{"type":"string","title":"Data Type","default":"string"},"allowed_values":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Allowed Values"}},"type":"object","required":["key","display_name","value"],"title":"TagSchema"},"TaxActivityOption":{"properties":{"value":{"type":"string","title":"Value","description":"Stable activity id — questionnaire-instance UUID, or a synthetic id."},"label":{"type":"string","title":"Label"},"activity_type":{"type":"string","title":"Activity Type","description":"SCH_C / SCH_E / SCH_F / FARM_RENTAL / K1_ENTITY / RESIDENCE."},"form":{"type":"string","title":"Form"},"property_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Property Label","description":"Groups co-located activities in the picker."}},"type":"object","required":["value","label","activity_type","form"],"title":"TaxActivityOption","description":"One selectable activity for the review-UI activity-link dropdown."},"TaxReturnGenerationRequestItem":{"properties":{"tax_return_id":{"type":"string","format":"uuid","title":"Tax Return Id","description":"Tax return id; use with workpaper status and GET workpaper."},"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"Client id"},"client_name":{"type":"string","title":"Client Name","description":"Client full name"},"client_readable_id":{"type":"string","title":"Client Readable Id","description":"Human-readable client id (e.g. AT-12345)"},"tax_year":{"type":"integer","title":"Tax Year","description":"Tax year"},"return_type":{"$ref":"#/components/schemas/TaxReturnTypeEnum","description":"ORIGINAL or AMENDED"},"return_status":{"$ref":"#/components/schemas/TaxReturnStatusEnum","description":"Tax return lifecycle status (same as GET workpaper return_status)."},"workpaper_pdf_storage_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workpaper Pdf Storage Key","description":"Full workpaper PDF storage key; same as GET workpaper workpaper_pdf_storage_key."},"workpaper_dirty":{"type":"boolean","title":"Workpaper Dirty","description":"True if return data changed since last successful generation (stale workpaper)."},"first_generation_at":{"type":"string","format":"date-time","title":"First Generation At","description":"When the first evaluation job was created for this tax return."},"last_generation_at":{"type":"string","format":"date-time","title":"Last Generation At","description":"Latest generation activity: job completed_at if set, else job updated_at."},"job_id":{"type":"string","format":"uuid","title":"Job Id","description":"Latest evaluation job id"},"job_status":{"$ref":"#/components/schemas/WorkpaperRegenerationJobStatusEnum","description":"Latest job status: PENDING, RUNNING, COMPLETED, or FAILED."},"job_last_outcome":{"anyOf":[{"$ref":"#/components/schemas/WorkpaperStatusOutcomeEnum"},{"type":"null"}],"description":"When job completed: COMPLETE, PARTIAL, or ERROR (workpaper_status on job row)."},"job_completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Job Completed At","description":"When the latest job finished (COMPLETED or FAILED)."},"job_error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Error Message","description":"Error message when latest job status is FAILED."},"display_status":{"type":"string","title":"Display Status","description":"Short UI label derived from job_status (e.g. Pending, Running, Completed, Failed)."}},"additionalProperties":false,"type":"object","required":["tax_return_id","client_id","client_name","client_readable_id","tax_year","return_type","return_status","workpaper_dirty","first_generation_at","last_generation_at","job_id","job_status","display_status"],"title":"TaxReturnGenerationRequestItem","description":"One row: client + tax return + latest evaluation job snapshot."},"TaxReturnGenerationRequestListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TaxReturnGenerationRequestItem"},"type":"array","title":"Data"},"meta":{"$ref":"#/components/schemas/app__schemas__common__pagination__PaginationMeta","description":"Pagination metadata"}},"additionalProperties":false,"type":"object","required":["meta"],"title":"TaxReturnGenerationRequestListResponse","description":"Paginated list of tax return generation requests for the tenant."},"TaxReturnStatusEnum":{"type":"string","enum":["DRAFT","REVIEW","FILED","ACCEPTED"],"title":"TaxReturnStatusEnum","description":"Tax return lifecycle. DB: core_schema.tax_return_status_enum."},"TaxReturnTypeEnum":{"type":"string","enum":["ORIGINAL","AMENDED"],"title":"TaxReturnTypeEnum","description":"Return type: ORIGINAL | AMENDED. DB: core_schema.tax_return_type_enum."},"TeamListMeta":{"properties":{"total":{"type":"integer","title":"Total"},"seats":{"$ref":"#/components/schemas/SeatUsage"},"pending_invites":{"type":"integer","title":"Pending Invites"},"expired_invites":{"type":"integer","title":"Expired Invites","default":0},"can_manage_team":{"type":"boolean","title":"Can Manage Team"},"can_transfer_ownership":{"type":"boolean","title":"Can Transfer Ownership"},"current_user_role":{"$ref":"#/components/schemas/UserRole"}},"type":"object","required":["total","seats","pending_invites","can_manage_team","can_transfer_ownership","current_user_role"],"title":"TeamListMeta"},"TeamListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TeamMemberResponse"},"type":"array","title":"Data"},"meta":{"$ref":"#/components/schemas/TeamListMeta"}},"type":"object","required":["data","meta"],"title":"TeamListResponse"},"TeamMemberResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"type":{"$ref":"#/components/schemas/TeamMemberType"},"email":{"type":"string","title":"Email"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"role":{"$ref":"#/components/schemas/UserRole"},"status":{"$ref":"#/components/schemas/TeamMemberStatus"},"last_login_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Login At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"invited_by":{"anyOf":[{"$ref":"#/components/schemas/InvitedByRef"},{"type":"null"}]},"invite_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Invite Expires At"},"is_self":{"type":"boolean","title":"Is Self","default":false}},"type":"object","required":["id","type","email","role","status","created_at"],"title":"TeamMemberResponse","description":"One roster row — a real user or a pending invite."},"TeamMemberStatus":{"type":"string","enum":["ACTIVE","INACTIVE","SUSPENDED","INVITED","EXPIRED"],"title":"TeamMemberStatus","description":"Roster status — the union of user status and invite lifecycle."},"TeamMemberType":{"type":"string","enum":["user","invite"],"title":"TeamMemberType","description":"Discriminates the two sources merged into one roster row.\n\nThe client keys rows on ``f\"{type}:{id}\"`` and otherwise never needs to know\nthat users and invites are separate tables."},"TenantRef":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"}},"type":"object","required":["id","name"],"title":"TenantRef"},"TenantSettingImpact":{"type":"string","enum":["PRESENTATION","WORKFLOW"],"title":"TenantSettingImpact","description":"What flipping this preference actually changes.\n\nSurfaced to the UI so an admin knows whether they are changing paperwork or\nchanging behaviour. See the module docstring for why there is no\ncalculation-altering member and why adding one is a deliberate act."},"TenantSettingType":{"type":"string","enum":["BOOLEAN","ENUM","INTEGER","STRING"],"title":"TenantSettingType","description":"Control type. The frontend renders purely from this — see the renderer\nregistry in ``settings/panes/preferences/controls``.\n\nAdding a member here means the frontend will receive a type it has never\nseen until it ships. That is expected and safe: the renderer registry skips\nunknown types rather than crashing the pane, so the backend can deploy\nfirst. It is also tested, because \"the API added a control we don't know\nabout\" is the single most likely cross-repo ordering in this design."},"TurnOptionPayload":{"properties":{"id":{"type":"string","title":"Id"},"label":{"type":"string","title":"Label"},"canonical_ref":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Canonical Ref"},"context":{"type":"string","title":"Context","default":""}},"additionalProperties":false,"type":"object","required":["id","label"],"title":"TurnOptionPayload","description":"Single option from a ClarificationRequest."},"UndoDocumentPartyRequest":{"properties":{"client_id":{"type":"string","format":"uuid","title":"Client Id"},"entries":{"items":{"$ref":"#/components/schemas/RestorePartyEntry"},"type":"array","maxItems":500,"minItems":1,"title":"Entries"}},"type":"object","required":["client_id","entries"],"title":"UndoDocumentPartyRequest","description":"Revert a bulk assign to the exact prior state.\n\nA separate shape from the assign request because an undo is NOT a decision: it restores\nwhat was there, per document, and must not lock. Sending it back through the normal PATCH\nwould record every entry as MANUAL_EDIT — locking documents at \"undecided\" forever and\npromoting mere suggestions into human decisions."},"UpdateClientNotesRequest":{"properties":{"notes":{"type":"string","maxLength":1000,"title":"Notes","description":"Notes to add or update for this document item","example":"This is my W-2 from Acme Corporation"}},"type":"object","required":["notes"],"title":"UpdateClientNotesRequest","description":"Schema for updating client notes on a document item"},"UpdateMcpSettingsRequest":{"properties":{"mcp_enabled":{"type":"boolean","title":"Mcp Enabled","description":"Master switch for THIS organization. A valid API key does nothing while this is false, so an operator can suspend one firm without revoking credentials their team has already deployed."},"rate_limit_per_minute":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Rate Limit Per Minute","description":"Requests per minute across the whole connector for this organization. Null means no cap. Connector traffic is driven by a third-party host on a schedule you do not control, so this is the ceiling that keeps a looping host from becoming an availability problem for the rest of Signals.","example":60},"daily_spend_cap_cents":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Daily Spend Cap Cents","description":"Ceiling on AI spend through the connector per UTC day, in cents. Null means uncapped. Checked before each question, so the cap can be passed by at most one question.","example":5000}},"additionalProperties":false,"type":"object","required":["mcp_enabled"],"title":"UpdateMcpSettingsRequest"},"UploadPolicyResponse":{"properties":{"max_file_size_bytes":{"type":"integer","title":"Max File Size Bytes","description":"Maximum allowed size for a single uploaded file, in bytes.","example":104857600},"max_files_per_upload":{"type":"integer","title":"Max Files Per Upload","description":"Maximum number of files accepted in a single upload action.","example":10},"allowed_extensions":{"items":{"type":"string"},"type":"array","title":"Allowed Extensions","description":"Lowercase dotted extensions accepted by the DMS upload gate.","example":[".pdf",".png",".jpg"]},"allowed_mime_types":{"additionalProperties":{"type":"string"},"type":"object","title":"Allowed Mime Types","description":"Mapping of allowed extension -> canonical MIME type.","example":{".pdf":"application/pdf"}},"extraction_supported_extensions":{"items":{"type":"string"},"type":"array","title":"Extraction Supported Extensions","description":"Subset of allowed_extensions the extraction pipeline can consume. Uploads outside this set are stored but not auto-extracted.","example":[".pdf",".png",".jpg"]},"extraction_max_bytes":{"type":"integer","title":"Extraction Max Bytes","description":"Scribe hard byte ceiling before rasterize/OCR (OOM safety rail). Deliberately above max_file_size_bytes.","example":157286400},"extraction_absolute_max_pages":{"type":"integer","title":"Extraction Absolute Max Pages","description":"Scribe hard page ceiling that always applies.","example":500},"pyr_max_file_size_bytes":{"type":"integer","title":"Pyr Max File Size Bytes","description":"Previous-year-return (PYR) dropoff upload size ceiling (separate from, and typically stricter than, max_file_size_bytes).","example":33554432}},"type":"object","required":["max_file_size_bytes","max_files_per_upload","allowed_extensions","allowed_mime_types","extraction_supported_extensions","extraction_max_bytes","extraction_absolute_max_pages","pyr_max_file_size_bytes"],"title":"UploadPolicyResponse","description":"Read-only upload constraints served to the frontend upload components."},"UploadRequestInfo":{"properties":{"request_title":{"type":"string","title":"Request Title","description":"Title of the upload request","example":"2024 Tax Documents"},"completed_items":{"type":"integer","title":"Completed Items","description":"Number of completed items","example":2},"total_items":{"type":"integer","title":"Total Items","description":"Total number of items (excluding voluntary documents)","example":3},"remaining_items":{"type":"integer","title":"Remaining Items","description":"Number of remaining items to upload","example":1},"uploaded_items":{"type":"integer","title":"Uploaded Items","description":"Number of uploaded items (alias for completed_items, kept for backward compatibility)","example":2},"status":{"type":"string","title":"Status","description":"Status of the upload request","example":"ACTIVE"},"can_submit":{"type":"boolean","title":"Can Submit","description":"Whether the request can be submitted","example":true}},"type":"object","required":["request_title","completed_items","total_items","remaining_items","uploaded_items","status","can_submit"],"title":"UploadRequestInfo","description":"Schema for upload request information"},"UploadedDocumentInfo":{"properties":{"id":{"type":"string","title":"Id","description":"Document ID (scoped to upload request)"},"name":{"type":"string","title":"Name","description":"Document name"},"original_filename":{"type":"string","title":"Original Filename","description":"Original filename"},"file_size":{"type":"integer","title":"File Size","description":"File size in bytes"},"mime_type":{"type":"string","title":"Mime Type","description":"MIME type"},"uploaded_at":{"type":"string","format":"date-time","title":"Uploaded At","description":"When the document was uploaded"},"extraction_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extraction Status","description":"Document extraction status"},"document_matching":{"anyOf":[{"$ref":"#/components/schemas/DocumentMatchingInfo"},{"type":"null"}],"description":"Document type matching information (if available)"}},"type":"object","required":["id","name","original_filename","file_size","mime_type","uploaded_at"],"title":"UploadedDocumentInfo","description":"Schema for uploaded document information (non-sensitive)"},"UserDetails":{"properties":{"id":{"type":"string","title":"Id","example":"123e4567-e89b-12d3-a456-426614174000"},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Email","example":"user@example.com"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","example":"John Doe"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","example":"ACTIVE"}},"type":"object","title":"UserDetails"},"UserLoginRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email","example":"user@example.com"},"password":{"type":"string","title":"Password","example":"hashedpassword123"},"recaptcha_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recaptcha Token","description":"Google reCAPTCHA token (v3 or v2)"},"recaptcha_version":{"anyOf":[{"$ref":"#/components/schemas/RecaptchaVersion"},{"type":"null"}],"description":"reCAPTCHA version used (v3 or v2)"}},"type":"object","required":["email","password"],"title":"UserLoginRequest"},"UserLoginResponse":{"properties":{"access_token":{"type":"string","title":"Access Token","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"token_type":{"type":"string","title":"Token Type","example":"bearer"},"access_token_expire_in_minutes":{"type":"integer","title":"Access Token Expire In Minutes","example":30},"user_details":{"$ref":"#/components/schemas/UserDetails","example":{"email":"user@example.com","id":"123e4567-e89b-12d3-a456-426614174000","name":"John Doe","status":"ACTIVE"}}},"type":"object","required":["access_token","token_type","access_token_expire_in_minutes","user_details"],"title":"UserLoginResponse"},"UserRole":{"type":"string","enum":["OWNER","ADMIN","USER","SUPER_ADMIN","REVIEWER","PREPARER","MANAGER"],"title":"UserRole"},"UserSignUpResponse":{"properties":{"access_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"token_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token Type","example":"bearer"},"access_token_expire_in_minutes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Access Token Expire In Minutes","example":30},"user_details":{"$ref":"#/components/schemas/UserDetails","example":{"email":"user@example.com","id":"123e4567-e89b-12d3-a456-426614174000","name":"John Doe","status":"ACTIVE"}},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Message about the signup status","example":"Please verify your email to complete signup"},"requires_verification":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Requires Verification","description":"Whether email verification is required","example":true}},"type":"object","required":["user_details"],"title":"UserSignUpResponse","description":"Original signup response with optional fields for backward compatibility"},"UserSignUpResponseV2":{"properties":{"user_details":{"$ref":"#/components/schemas/UserDetails","example":{"email":"user@example.com","id":"123e4567-e89b-12d3-a456-426614174000","name":"John Doe","status":"ACTIVE"}},"message":{"type":"string","title":"Message","description":"Message about the signup status","example":"Please verify your email to complete signup. A verification code has been sent to your email."},"requires_verification":{"type":"boolean","title":"Requires Verification","description":"Whether email verification is required","example":true}},"type":"object","required":["user_details","message","requires_verification"],"title":"UserSignUpResponseV2","description":"New signup response - simplified for OTP verification flow"},"UserSignupRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email","example":"newuser@example.com"},"password":{"type":"string","maxLength":128,"minLength":8,"title":"Password","example":"S3cure!Passw0rd"},"name":{"type":"string","minLength":1,"title":"Name","example":"Jane Doe"},"recaptcha_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recaptcha Token","description":"Google reCAPTCHA token (v3 or v2)"},"recaptcha_version":{"anyOf":[{"$ref":"#/components/schemas/RecaptchaVersion"},{"type":"null"}],"description":"reCAPTCHA version used (v3 or v2)"}},"type":"object","required":["email","password","name"],"title":"UserSignupRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VerifyEmailRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email","example":"user@example.com"},"otp":{"type":"string","maxLength":6,"minLength":6,"title":"Otp","description":"6-digit OTP received via email","example":"123456"}},"type":"object","required":["email","otp"],"title":"VerifyEmailRequest"},"VerifyEmailResponse":{"properties":{"access_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"token_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token Type","example":"bearer"},"access_token_expire_in_minutes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Access Token Expire In Minutes","example":30},"user_details":{"$ref":"#/components/schemas/UserDetails","example":{"email":"user@example.com","id":"123e4567-e89b-12d3-a456-426614174000","name":"John Doe","status":"ACTIVE"}},"message":{"type":"string","title":"Message","default":"Email verified successfully","example":"Email verified successfully"}},"type":"object","required":["user_details"],"title":"VerifyEmailResponse"},"VerifyOTPRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"},"otp":{"type":"string","maxLength":6,"minLength":6,"title":"Otp","description":"6-digit OTP received via email"}},"type":"object","required":["email","otp"],"title":"VerifyOTPRequest"},"VerifyOTPResponse":{"properties":{"message":{"type":"string","title":"Message","default":"OTP verified successfully."},"token":{"type":"string","title":"Token","description":"Temporary token for password reset"}},"type":"object","required":["token"],"title":"VerifyOTPResponse"},"WorkflowStatus":{"type":"string","enum":["CREATED","IN_PROGRESS","APPROVED","REJECTED","CANCELLED","REOPENED"],"title":"WorkflowStatus"},"WorkflowStatusResponse":{"properties":{"workflow_id":{"type":"string","format":"uuid","title":"Workflow Id","description":"ID of the workflow"},"document_id":{"type":"string","format":"uuid","title":"Document Id","description":"ID of the associated document"},"status":{"$ref":"#/components/schemas/WorkflowStatus","description":"Current workflow status"},"created_by":{"type":"string","title":"Created By","description":"User who created the workflow"},"assigned_to":{"type":"string","format":"uuid","title":"Assigned To","description":"User assigned to the workflow"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when workflow was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Timestamp when workflow was last updated"}},"type":"object","required":["workflow_id","document_id","status","created_by","assigned_to","created_at","updated_at"],"title":"WorkflowStatusResponse","description":"Response model for workflow status."},"WorkpaperAcceptedResponse":{"properties":{"tax_return_id":{"type":"string","format":"uuid","title":"Tax Return Id","description":"Tax return UUID; use in GET workpaper and future reevaluate requests."},"status":{"$ref":"#/components/schemas/WorkpaperRegenerationJobStatusEnum","description":"Evaluation job status at accept time; always PENDING. Poll GET workpaper/status for updates.","default":"PENDING","example":"PENDING"}},"additionalProperties":false,"type":"object","required":["tax_return_id"],"title":"WorkpaperAcceptedResponse","description":"202 Accepted response body: tax_return_id for polling and subsequent reevaluate."},"WorkpaperDisplayStatusEnum":{"type":"string","enum":["NO_RETURN","EVALUATING","STALE","READY","ERROR"],"title":"WorkpaperDisplayStatusEnum","description":"Single display status for GET workpaper (UI branch).\nBackend-computed; frontend uses this only."},"WorkpaperEvaluateBody":{"properties":{"tax_year":{"type":"integer","maximum":2100.0,"minimum":1900.0,"title":"Tax Year","description":"Tax year for workpaper evaluation","example":2024},"triggered_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Triggered By User Id","description":"User who triggered; defaults to current user when omitted."}},"additionalProperties":false,"type":"object","required":["tax_year"],"title":"WorkpaperEvaluateBody","description":"Request body for POST workpaper/evaluate (first-time). No tax_return_id."},"WorkpaperFormStatusEnum":{"type":"string","enum":["CALCULATED","PARTIAL","NOT_CALCULATED","ERROR"],"title":"WorkpaperFormStatusEnum","description":"Form-level calculation status for FormInstance in GET workpaper."},"WorkpaperMarkDirtyBody":{"properties":{"tax_year":{"type":"integer","maximum":2100.0,"minimum":1900.0,"title":"Tax Year","description":"Tax year for the workpaper to mark dirty","example":2025}},"additionalProperties":false,"type":"object","required":["tax_year"],"title":"WorkpaperMarkDirtyBody","description":"Request body for POST workpaper/mark-dirty. Call when inputs change (e.g. document upload)."},"WorkpaperMarkDirtyResponse":{"properties":{"updated":{"type":"boolean","title":"Updated","description":"True if a tax return was found and workpaper_dirty was set; false if no return."}},"additionalProperties":false,"type":"object","required":["updated"],"title":"WorkpaperMarkDirtyResponse","description":"Response for POST workpaper/mark-dirty."},"WorkpaperPdfUrlResponse":{"properties":{"url":{"type":"string","title":"Url","description":"Presigned URL to access the PDF (short-lived)."},"filename":{"type":"string","title":"Filename","description":"Suggested filename for download (e.g. 2025_workpaper.pdf)."}},"additionalProperties":false,"type":"object","required":["url","filename"],"title":"WorkpaperPdfUrlResponse","description":"Presigned URL for workpaper PDF (full or per-form). Frontend opens URL in new tab or uses for download."},"WorkpaperReevaluateBody":{"properties":{"tax_year":{"type":"integer","maximum":2100.0,"minimum":1900.0,"title":"Tax Year","description":"Tax year for workpaper evaluation","example":2024},"tax_return_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Tax Return Id","description":"Tax return ID from GET workpaper. Omit to look up by tax_year (400 if none)."},"triggered_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Triggered By User Id","description":"User who triggered; defaults to current user when omitted."}},"additionalProperties":false,"type":"object","required":["tax_year"],"title":"WorkpaperReevaluateBody","description":"Request body for POST workpaper/reevaluate (re-run). tax_return_id from GET workpaper."},"WorkpaperRegenerationJobStatusEnum":{"type":"string","enum":["PENDING","RUNNING","COMPLETED","FAILED"],"title":"WorkpaperRegenerationJobStatusEnum","description":"Job lifecycle. DB: workpaper_regeneration_job_status_enum. API adds IDLE in core."},"WorkpaperResponse":{"properties":{"tax_year":{"type":"integer","title":"Tax Year","description":"Tax year (request context)"},"client_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Client Id","description":"Client id (echo from path)"},"tax_return_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Tax Return Id","description":"Return id when return exists; null otherwise"},"return_status":{"anyOf":[{"$ref":"#/components/schemas/TaxReturnStatusEnum"},{"type":"null"}],"description":"DRAFT | REVIEW | FILED | ACCEPTED; null when no return"},"status":{"$ref":"#/components/schemas/WorkpaperDisplayStatusEnum","description":"NO_RETURN | EVALUATING | STALE | READY | ERROR"},"job":{"anyOf":[{"$ref":"#/components/schemas/JobResponse"},{"type":"null"}],"description":"Job block; null when no return"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When workpaper was last successfully updated"},"indeterminate_forms_count":{"type":"integer","title":"Indeterminate Forms Count","description":"Length of indeterminate_forms"},"eligible_forms_count":{"type":"integer","title":"Eligible Forms Count","description":"Length of forms"},"correlation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Correlation Id","description":"Request correlation id when provided"},"workpaper_pdf_storage_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workpaper Pdf Storage Key","description":"Storage key for full workpaper PDF; use with GET .../workpaper/pdf?storage_key= to get presigned URL."},"return_diagnostics_count":{"type":"integer","title":"Return Diagnostics Count","description":"Length of return_diagnostics","default":0},"indeterminate_forms":{"items":{"$ref":"#/components/schemas/IndeterminateForm"},"type":"array","title":"Indeterminate Forms","description":"Forms not yet determined"},"forms":{"items":{"$ref":"#/components/schemas/FormInstance"},"type":"array","title":"Forms","description":"Eligible forms only (form_eligibility_status=ELIGIBLE)"},"return_diagnostics":{"items":{"$ref":"#/components/schemas/ReturnDiagnostic"},"type":"array","title":"Return Diagnostics","description":"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."}},"type":"object","required":["tax_year","status","indeterminate_forms_count","eligible_forms_count"],"title":"WorkpaperResponse","description":"GET workpaper response contract.\n\nSingle shape: level 1 + job + indeterminate_forms + forms.\nFrontend uses status (display enum) and job; form_tabs removed."},"WorkpaperStatusOutcomeEnum":{"type":"string","enum":["COMPLETE","PARTIAL","ERROR"],"title":"WorkpaperStatusOutcomeEnum","description":"Workpaper/form outcome. DB: core_schema.workpaper_status_outcome_enum."},"WorkpaperStatusResponse":{"properties":{"status":{"anyOf":[{"type":"string","const":"IDLE"},{"$ref":"#/components/schemas/WorkpaperRegenerationJobStatusEnum"}],"title":"Status","description":"Current evaluation job status. Poll until COMPLETED or FAILED, then call GET workpaper.","examples":["IDLE","PENDING","RUNNING","COMPLETED","FAILED"]},"workpaper_status":{"anyOf":[{"$ref":"#/components/schemas/WorkpaperStatusOutcomeEnum"},{"type":"null"}],"description":"Outcome when status is COMPLETED or FAILED: COMPLETE, PARTIAL, or ERROR."},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When the job finished (COMPLETED or FAILED)."},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"Error details when status is FAILED."}},"additionalProperties":false,"type":"object","required":["status"],"title":"WorkpaperStatusResponse","description":"Response for GET workpaper/status: regeneration job status for polling by tax_return_id."},"YearGroup1099C":{"properties":{"year":{"type":"integer","title":"Year","description":"Tax year for this group"},"tabs":{"items":{"$ref":"#/components/schemas/Tab1099C"},"type":"array","title":"Tabs","description":"6 tabs in order: Basic Info (TaxYear, Payer.*, Recipient.* top-of-form metadata), 1099-INT, 1099-DIV, 1099-OID, 1099-MISC, 1099-B."}},"type":"object","required":["year"],"title":"YearGroup1099C","description":"One tax year's worth of 1099-C data, organized into 6 tabs."},"YearGroupedAttributes":{"properties":{"year":{"type":"integer","title":"Year","description":"Tax year for these attributes"},"items":{"items":{"$ref":"#/components/schemas/ExtractedAttributeItem"},"type":"array","title":"Items","description":"List of attributes for this year"}},"type":"object","required":["year","items"],"title":"YearGroupedAttributes","description":"Attributes grouped by year"},"YoyDigestResponse":{"properties":{"prior_year_available":{"type":"boolean","title":"Prior Year Available","default":false},"current_year":{"type":"integer","title":"Current Year","default":0},"prior_year":{"type":"integer","title":"Prior Year","description":"The year actually compared against — not always `current_year - 1`. A client whose most recent return is 2022 is compared against 2022, and the table must say so.","default":0},"headlines":{"items":{"$ref":"#/components/schemas/YoyHeadlineRow"},"type":"array","title":"Headlines"},"summary":{"type":"string","title":"Summary","default":""},"prior_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prior Source","description":"Where the prior figures came from, and HOW: `as_filed:TEXT_LAYER` is a read of the return's text layer, `as_filed:SCRIBE` a full extraction, `engine_computed` a year we prepared ourselves. The tier is part of it because a preparer decides whether to check a figure against the paper on exactly that."},"prior_unavailable_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prior Unavailable Reason","description":"WHY there is no comparison, when there is none. `no_return` — nothing uploaded. `never_read` — a return is on file and its figures were never read, because the run predates headline capture; nothing is wrong with the file. `unreadable` — we read it and could not get the figures off it, and the run recorded a refusal saying which guard fired. The middle one exists because without it the panel diagnoses an old-flow return as a bad scan and tells a preparer to replace a file that is perfectly good."},"current_computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Current Computed At","description":"When this year's figures were last calculated by the engine — the newest `calculated_at` across the headline lines. The prior column already says where it came from; without this the current column says nothing at all, and a preparer cannot tell a figure computed a minute ago from one computed before the last three questionnaire answers."},"current_stale":{"type":"boolean","title":"Current Stale","description":"At least one headline line is flagged dirty: the engine's answer no longer reflects the inputs. Dirtiness is tracked PER LINE, so this is an any() over the headline set rather than a property of the return — a return can be clean everywhere the table does not look.","default":false},"compared_count":{"type":"integer","title":"Compared Count","description":"How many headline lines were actually compared against the prior year. With `not_compared_count` this is an exhaustive partition of `headlines` — the two always sum to its length, asserted at the source. Defined as a partition rather than a filter because a filter silently drops a direction added later, and the symptom is not an exception but a printed count whose numbers stop accounting for each other on a document somebody has signed.","default":0},"not_compared_count":{"type":"integer","title":"Not Compared Count","description":"How many could not be compared, for any of the three reasons the direction vocabulary distinguishes.","default":0},"stale_line_keys":{"items":{"type":"string"},"type":"array","title":"Stale Line Keys","description":"Which headline concepts are dirty, so the table can mark the affected rows rather than hedging the whole comparison. A banner over thirteen rows when one moved teaches a preparer to ignore it."},"corrected_count":{"type":"integer","title":"Corrected Count","description":"How many prior figures a person has corrected. Counted from the overrides actually applied to THIS digest, never from what a client happens to be holding — a second preparer's correction has to show up here for the first preparer on the next read.","default":0},"correction_consequences":{"items":{"$ref":"#/components/schemas/CorrectionConsequenceOut"},"type":"array","title":"Correction Consequences","description":"What a correction invalidated downstream and we did NOT fix.\n\nMost prior figures are compared and feed nothing. A few are inputs to the year being prepared — prior AGI sets the §6654 safe harbour and signs the e-file; capital-loss, NOL and AMT-credit carryforwards rest on prior figures. Correcting one of those leaves something downstream we have not touched.\n\nNamed rather than applied, deliberately. Writing through would overwrite a figure a client supplied or a preparer has already reasoned about; staying quiet would leave a confident screen sitting on a stale carryforward. Naming it is the only move honest to both — and it is empty for the rows that merely compare, because hedging every correction teaches a preparer to stop reading the warning."}},"type":"object","title":"YoyDigestResponse","description":"The comparison table, in the 1040's own order."},"YoyHeadlineRow":{"properties":{"label":{"type":"string","title":"Label"},"line_key":{"type":"string","title":"Line Key"},"prior_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prior Value"},"current_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Value"},"delta":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delta"},"pct_change":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pct Change","description":"A FRACTION, not a percentage: 0.079 is +7.9%."},"direction":{"type":"string","title":"Direction","description":"up | down | flat | new | removed | prior_not_read | prior_inputs_not_read | prior_not_computable.\n\nThe last three each name a DIFFERENT reason the comparison could not be made, and none of them may collapse into `new` — `new` asserts this year introduced the figure, which is a claim about the client's return.\n\n* `prior_not_read` — the extractor never found the figure.\n* `prior_inputs_not_read` — a DERIVED row whose inputs were not read. The row was never a line on the return, so 'we did not find it there' describes a search nobody could have made; `derived_missing_inputs` names the figures that actually were not read.\n* `prior_not_computable` — a derived row whose inputs WERE read and which still cannot be worked out, because a zero or negative prior AGI makes the ratio meaningless. Telling a preparer we did not read a figure whose inputs we can cite pages for sends them to check a page that would show them exactly what we already have.","default":"flat"},"prior_present":{"type":"boolean","title":"Prior Present","description":"Whether last year's figure was actually read. False means the row shows no delta because we do not have the number, not because nothing changed.","default":true},"current_present":{"type":"boolean","title":"Current Present","default":true},"prior_source_page":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prior Source Page","description":"The page of the filed return the prior figure was read from. Present only for an as-filed basis; an engine-computed prior has no page and must not pretend to."},"low_confidence":{"type":"boolean","title":"Low Confidence","description":"The prior value came from an extraction flagged for review. The row should hedge rather than assert.","default":false},"derived":{"type":"boolean","title":"Derived","description":"This row is CALCULATED from other rows rather than transcribed from a line on the return. It changes what an absence means: telling a preparer we did not find the effective rate on the return is a false statement about a figure that was never a line on it to find. Sourced from DERIVED_CONCEPTS so a client selects on data rather than string-matching a line key.","default":false},"derived_missing_inputs":{"items":{"type":"string"},"type":"array","title":"Derived Missing Inputs","description":"For a derived row that could not be compared: the human names of the inputs that were required and not read, so the explanation names the missing figure rather than gesturing at the row."},"prior_value_source":{"type":"string","title":"Prior Value Source","description":"`extracted` | `corrected` — where THIS row's prior figure came from: the machine, or a person.\n\n`prior_source` on the digest cannot answer this. It describes how the EXTRACTION was performed and is one value for the whole table; provenance after a correction is per row, and a preparer deciding whether to check a figure against the paper needs to know which of the two this one is.","default":"extracted"},"prior_override":{"anyOf":[{"$ref":"#/components/schemas/FigureOverrideOut"},{"type":"null"}],"description":"The correction itself, when there is one: who, when, why, and the figure it replaced. Both halves stay on screen for ever — 'we read $114,600 and M. Rivera says $214,600' is a workpaper; '$214,600' alone is an assertion with no provenance."},"prior_extraction_disagrees":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prior Extraction Disagrees","description":"A LATER extraction read this line differently from the standing correction. The correction still wins and is what this row shows.\n\nSurfaced rather than resolved. Silently taking the machine's newer answer over a preparer's typed one is the failure that ends their use of the feature: they type six figures at 11pm, a re-run lands on Tuesday, and the work is gone with nothing on screen to say so."}},"type":"object","required":["label","line_key"],"title":"YoyHeadlineRow","description":"One line's comparison. Always present, never threshold-collapsed."},"app__schemas__client__address__AddressResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier for the address record"},"street_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Street Address","description":"The primary street address"},"address_line_2":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address Line 2","description":"Additional address information"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City","description":"The city name"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State","description":"The state"},"zip_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Zip Code","description":"The ZIP code"}},"type":"object","required":["id"],"title":"AddressResponse","example":{"address_line_2":"Apt 4B","city":"New York","id":"550e8400-e29b-41d4-a716-446655440000","state":"NY","street_address":"123 Main Street","zip_code":"10001"}},"app__schemas__client__client__AddressResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"street_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Street Address"},"address_line_2":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address Line 2"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"},"zip_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Zip Code"}},"type":"object","required":["id","street_address","address_line_2","city","state","zip_code"],"title":"AddressResponse"},"app__schemas__common__pagination__PaginationMeta":{"properties":{"page":{"type":"integer","title":"Page","description":"Current page number"},"page_size":{"type":"integer","title":"Page Size","description":"Number of items per page"},"total_count":{"type":"integer","minimum":0.0,"title":"Total Count","description":"Total number of items"},"total_pages":{"type":"integer","minimum":0.0,"title":"Total Pages","description":"Total number of pages"},"total":{"type":"integer","title":"Total","description":"Alias for total_count for backward compatibility","readOnly":true}},"type":"object","required":["page","page_size","total_count","total_pages","total"],"title":"PaginationMeta"},"app__schemas__dms__audit__PaginationMeta":{"properties":{"page":{"type":"integer","title":"Page","description":"Current page number"},"page_size":{"type":"integer","title":"Page Size","description":"Number of items per page"},"total_count":{"type":"integer","minimum":0.0,"title":"Total Count","description":"Total number of items"},"total_pages":{"type":"integer","minimum":0.0,"title":"Total Pages","description":"Total number of pages"}},"type":"object","required":["page","page_size","total_count","total_pages"],"title":"PaginationMeta","description":"Pagination metadata"},"app__schemas__dms__document__SupportedDocumentType":{"properties":{"value":{"type":"string","title":"Value","description":"Document type identifier","example":"W2"},"label":{"type":"string","title":"Label","description":"Human-readable label","example":"W-2"},"new_extraction_flow_enabled":{"type":"boolean","title":"New Extraction Flow Enabled","description":"When true, this document type uses the new (scribe) extraction flow; when false, the legacy flow. The frontend uses this to pick the old/new UI.","default":false,"example":true}},"type":"object","required":["value","label"],"title":"SupportedDocumentType","description":"Schema for supported document type in API responses.\n\nUsed for returning document types with value and label for UI consumption."},"app__schemas__document_extraction__SupportedDocumentType":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"display_name":{"type":"string","title":"Display Name"},"is_active":{"type":"boolean","title":"Is Active"},"attributes":{"items":{"$ref":"#/components/schemas/SupportedDocumentAttributesResponse"},"type":"array","title":"Attributes"}},"type":"object","required":["id","display_name","is_active"],"title":"SupportedDocumentType"}},"securitySchemes":{"CustomOAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"/auth/login"}}}}}}