{"openapi":"3.1.0","info":{"title":"Bills — DayZero API","version":"1.0.0","description":"Accounts payable — create and manage vendor bills."},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/bills/upcoming":{"get":{"tags":["bills"],"summary":"List upcoming (expected) bills","description":"Forecast rows for bills the business expects — recurring contractor payments, retainers. These are estimates: they carry no journal entries and are excluded from AP totals, aged payables and the balance sheet.","operationId":"list_upcoming_bills","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by status: expected, converted, dismissed.","title":"Status"},"description":"Filter by status: expected, converted, dismissed."},{"name":"vendor_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by vendor.","title":"Vendor Id"},"description":"Filter by vendor."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Only occurrences expected on or after this date.","title":"Date From"},"description":"Only occurrences expected on or after this date."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Only occurrences expected on or before this date.","title":"Date To"},"description":"Only occurrences expected on or before this date."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Maximum rows to return.","default":200,"title":"Limit"},"description":"Maximum rows to return."},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_UpcomingBillListResponse_"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"list_upcoming_bills_api_v1_bills_upcoming_get"},"post":{"tags":["bills"],"summary":"Create an upcoming bill (optionally recurring)","description":"Create one expected bill, or a recurring series. A recurring request materialises every projected occurrence up front (capped by `recurrence.occurrences`), so each one can be edited, deleted or matched independently. Returns every occurrence created.","operationId":"create_upcoming_bill","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpcomingBillCreateRequest"},"example":{"description":"Quarterly liability insurance premium","estimated_amount":180000,"expected_date":"2026-04-01","vendor_id":"0192a4f0-1b2c-7d3e-8f4a-5b6c7d8e9f02"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_UpcomingBillListResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"create_upcoming_bill_api_v1_bills_upcoming_post"}},"/api/v1/bills/upcoming/{upcoming_bill_id}":{"get":{"tags":["bills"],"summary":"Get one upcoming bill","operationId":"get_upcoming_bill","parameters":[{"name":"upcoming_bill_id","in":"path","required":true,"schema":{"type":"string","title":"Upcoming Bill Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_UpcomingBillResponse_"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"get_upcoming_bill_api_v1_bills_upcoming__upcoming_bill_id__get"},"patch":{"tags":["bills"],"summary":"Edit an upcoming bill","description":"Edits this occurrence only, not the whole series — so a one-month change to a recurring estimate does not redefine the schedule.","operationId":"update_upcoming_bill","parameters":[{"name":"upcoming_bill_id","in":"path","required":true,"schema":{"type":"string","title":"Upcoming Bill Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpcomingBillUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_UpcomingBillResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"update_upcoming_bill_api_v1_bills_upcoming__upcoming_bill_id__patch"},"delete":{"tags":["bills"],"summary":"Delete an upcoming bill","description":"Deletes this occurrence. Pass `series=true` to also drop every later still-expected occurrence in the same series; occurrences already converted into real bills are never touched.","operationId":"delete_upcoming_bill","parameters":[{"name":"upcoming_bill_id","in":"path","required":true,"schema":{"type":"string","title":"Upcoming Bill Id"}},{"name":"series","in":"query","required":false,"schema":{"type":"boolean","description":"Also delete later still-expected occurrences.","default":false,"title":"Series"},"description":"Also delete later still-expected occurrences."},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__core__success__MessageResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"delete_upcoming_bill_api_v1_bills_upcoming__upcoming_bill_id__delete"}},"/api/v1/bills/upcoming/{upcoming_bill_id}/convert":{"post":{"tags":["bills"],"summary":"Push an upcoming bill into a real bill","description":"Creates a **draft** bill from the estimate and marks the forecast row converted. The bill posts nothing to the ledger until it is approved and marked received, exactly like a hand-entered bill.","operationId":"convert_upcoming_bill","parameters":[{"name":"upcoming_bill_id","in":"path","required":true,"schema":{"type":"string","title":"Upcoming Bill Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpcomingBillConvertRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_UpcomingBillResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"convert_upcoming_bill_api_v1_bills_upcoming__upcoming_bill_id__convert_post"}},"/api/v1/bills/upcoming/{upcoming_bill_id}/link":{"post":{"tags":["bills"],"summary":"Match an upcoming bill to a bill that arrived","description":"Links the forecast row to an existing bill so the obligation stops being counted twice — once as a projection and once as a payable.","operationId":"link_upcoming_bill","parameters":[{"name":"upcoming_bill_id","in":"path","required":true,"schema":{"type":"string","title":"Upcoming Bill Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpcomingBillLinkRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_UpcomingBillResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"link_upcoming_bill_api_v1_bills_upcoming__upcoming_bill_id__link_post"}},"/api/v1/bills":{"get":{"tags":["bills"],"summary":"List bills","description":"Retrieve all bills for a business with cursor-based pagination. Can filter by vendor name (fuzzy search) or associated journal entry.","operationId":"list_bills","parameters":[{"name":"id","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Filter bills by specific bill UUIDs (batch fetch — avoids N+1 single-bill requests)","default":[],"title":"Id"},"description":"Filter bills by specific bill UUIDs (batch fetch — avoids N+1 single-bill requests)"},{"name":"vendor_search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Fuzzy search bills by vendor name (uses PostgreSQL trigram matching)","title":"Vendor Search"},"description":"Fuzzy search bills by vendor name (uses PostgreSQL trigram matching)"},{"name":"journal_entry_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter bills by associated journal entry UUID","title":"Journal Entry Id"},"description":"Filter bills by associated journal entry UUID"},{"name":"payment_method","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter bills by payment method: 'Wire Transfer', 'ACH', 'Check', 'Credit Card'","title":"Payment Method"},"description":"Filter bills by payment method: 'Wire Transfer', 'ACH', 'Check', 'Credit Card'"},{"name":"vendor_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter bills by vendor UUID","title":"Vendor Id"},"description":"Filter bills by vendor UUID"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by bill status (e.g. draft, approved, received, paid, canceled)","title":"Status"},"description":"Filter by bill status (e.g. draft, approved, received, paid, canceled)"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search bills by bill number, description, or vendor name (case-insensitive partial match)","title":"Search"},"description":"Search bills by bill number, description, or vendor name (case-insensitive partial match)"},{"name":"bill_number","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter bills by invoice/bill number (case-insensitive partial match)","title":"Bill Number"},"description":"Filter bills by invoice/bill number (case-insensitive partial match)"},{"name":"due_date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter bills with due date on or after this date (YYYY-MM-DD)","title":"Due Date From"},"description":"Filter bills with due date on or after this date (YYYY-MM-DD)"},{"name":"due_date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter bills with due date on or before this date (YYYY-MM-DD)","title":"Due Date To"},"description":"Filter bills with due date on or before this date (YYYY-MM-DD)"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Cursor for pagination","title":"Cursor"},"description":"Cursor for pagination"},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":1000,"minimum":1},{"type":"null"}],"description":"Pagination limit","title":"Limit"},"description":"Pagination limit"},{"name":"direction","in":"query","required":false,"schema":{"type":"string","description":"Pagination direction: 'next' or 'prev'","default":"next","title":"Direction"},"description":"Pagination direction: 'next' or 'prev'"},{"name":"include_total_count","in":"query","required":false,"schema":{"type":"boolean","description":"Whether to include total count (expensive - avoid if possible)","default":false,"title":"Include Total Count"},"description":"Whether to include total count (expensive - avoid if possible)"},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Column name to sort by (e.g. 'created_at', 'amount', 'name'). When changing sort, reset cursor to None.","title":"Sort By"},"description":"Column name to sort by (e.g. 'created_at', 'amount', 'name'). When changing sort, reset cursor to None."},{"name":"descending","in":"query","required":false,"schema":{"type":"boolean","description":"Sort direction: true for descending (newest/largest first), false for ascending","default":true,"title":"Descending"},"description":"Sort direction: true for descending (newest/largest first), false for ascending"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillsListResponse_"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"list_bills_api_v1_bills_get"},"post":{"tags":["bills"],"summary":"Create bill","description":"Create a new bill in draft status. Optionally include 'recurring' config to also create a recurring template.","operationId":"create_bill","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillCreateRequest"},"example":{"description":"Monthly office rent - January 2024","expected_amount":250000,"expected_paid_on_date":"2024-01-31T00:00:00Z","type":"recurring","vendor_id":"019ab37c-ae0d-7000-8000-000000000001"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"create_bill_api_v1_bills_post"}},"/api/v1/bills/duplicate-check":{"get":{"tags":["bills"],"summary":"Check for possible duplicate bills","description":"Advisory, read-only check used during bill entry. Returns existing bills that may duplicate the one being entered (same bill number, or same vendor and amount within ~90 days). Never blocks creation — it is purely a heads-up so the user can confirm before saving.","operationId":"check_duplicate_bills","parameters":[{"name":"bill_number","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"In-progress bill/invoice number to match (optional).","title":"Bill Number"},"description":"In-progress bill/invoice number to match (optional)."},{"name":"vendor_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"In-progress vendor UUID to match (optional).","title":"Vendor Id"},"description":"In-progress vendor UUID to match (optional)."},{"name":"amount","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"In-progress amount in cents to match (optional).","title":"Amount"},"description":"In-progress amount in cents to match (optional)."},{"name":"received_on","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Invoice date (YYYY-MM-DD); bounds the vendor+amount lookback window.","title":"Received On"},"description":"Invoice date (YYYY-MM-DD); bounds the vendor+amount lookback window."},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_DuplicateBillCheckResponse_"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"check_duplicate_bills_api_v1_bills_duplicate_check_get"}},"/api/v1/bills/ai-create":{"post":{"tags":["bills"],"summary":"AI-extract draft bills from documents","description":"Upload pasted text, PDFs, images, Excel files, or a CSV to extract draft bill entities using AI. Returns draft bills in 'received' status format ready for user review before creation.","operationId":"ai_create_bill_payload","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillAICreatePayloadRequest"},"example":{"single_bill_s3_keys":["business-id/uuid-bill1.pdf","business-id/uuid-bill2.png"]}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillAICreatePayloadResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"ai_create_bill_payload_api_v1_bills_ai_create_post"}},"/api/v1/bills/received":{"post":{"tags":["bills"],"summary":"Create bill in received status","description":"Create a new bill directly in 'received' status, ready for payment. Creates both the bill AND journal entry when ledger_id is provided.","operationId":"create_bill_received","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillReceivedCreateRequest"},"example":{"amount":56135,"bill_number":"P054","currency":"USD","description":"Purchase Order (P054) issued by Artisan AI LLC","due_on":"2025-03-29T12:00:00Z","journal_entry_date":"2025-02-27T12:00:00Z","ledger_id":"019ab37c-1ed1-7000-8000-000000000001","received_on":"2025-02-27T12:00:00Z","s3_key":"attachments/019c30bb-dc4c-7e7e-8f9a-123456789abc","type":"one_time","vendor_id":"019ab37c-ae0d-7000-8000-000000000001"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"create_bill_received_api_v1_bills_received_post"}},"/api/v1/bills/bulk":{"post":{"tags":["bills"],"summary":"Bulk create bills","description":"Create multiple bills from CSV data in a single request.","operationId":"create_bulk_bills","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillBulkRequest"},"example":{"approve":false,"attachments":{"rent-jan.pdf":"attachments/019c30bb-dc4c-7e7e-8f9a-aaa","supplies-feb.pdf":"attachments/019c30bb-dc4c-7e7e-8f9a-bbb"},"create_as_received":false,"s3_key":"uploads/bills/batch-2024-01.csv"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillsListResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"create_bulk_bills_api_v1_bills_bulk_post"}},"/api/v1/bills/metrics":{"get":{"tags":["bills"],"summary":"Get bill metrics","description":"Retrieve aggregated bill metrics for the business: total due and total balance due across all received and partially paid bills, plus the overdue balance across bills past their due date.","operationId":"get_bill_metrics","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillMetricsResponse_"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"get_bill_metrics_api_v1_bills_metrics_get"}},"/api/v1/bills/aging":{"get":{"tags":["bills"],"summary":"AP aging summary","description":"Returns accounts payable aging data grouped by vendor with Current, 1-30, 31-60, 61-90, and 91+ day buckets. Includes per-bill detail for drill-down.","operationId":"get_bill_aging","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillAgingResponse_"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"get_bill_aging_api_v1_bills_aging_get"}},"/api/v1/bills/expense-candidates":{"get":{"tags":["bills"],"summary":"List expense candidates","description":"Return outgoing transactions that may represent bill payments. Filters to posted expense transactions with unallocated balances, useful for the Record Payment modal on the bills page.","operationId":"list_expense_candidates","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Max results","default":200,"title":"Limit"},"description":"Max results"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_ListExpenseCandidatesResponse_"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"list_expense_candidates_api_v1_bills_expense_candidates_get"}},"/api/v1/bills/payment-suggestions":{"get":{"tags":["bills"],"summary":"List bill payment suggestions","description":"List auto-detected matches between bank transactions and open bills.","operationId":"list_bill_payment_suggestions","parameters":[{"name":"bill_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by bill UUID","title":"Bill Id"},"description":"Filter by bill UUID"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by status","default":"pending","title":"Status"},"description":"Filter by status"},{"name":"min_confidence","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Minimum confidence threshold","title":"Min Confidence"},"description":"Minimum confidence threshold"},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Only include suggestions whose transaction date is on or after this date (YYYY-MM-DD)","title":"Start Date"},"description":"Only include suggestions whose transaction date is on or after this date (YYYY-MM-DD)"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Only include suggestions whose transaction date is on or before this date (YYYY-MM-DD)","title":"End Date"},"description":"Only include suggestions whose transaction date is on or before this date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Max results","default":100,"title":"Limit"},"description":"Max results"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillPaymentSuggestionsListResponse_"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"list_bill_payment_suggestions_api_v1_bills_payment_suggestions_get"}},"/api/v1/bills/payments/batch":{"post":{"tags":["bills"],"summary":"Split one transaction across multiple bills","description":"Apply a single bank transaction to multiple bills and/or direct expense lines in one atomic request. Validates the total allocation against the transaction's remaining unallocated balance before creating any payments.","operationId":"create_bill_payments_batch","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillBatchPaymentRequest"},"example":{"allocations":[{"amount":50000,"bill_id":"019ab37c-b111-7000-8000-000000000001"},{"amount":75000,"bill_id":"019ab37c-b111-7000-8000-000000000002"}],"transaction_id":"019ab37c-7801-7000-8000-000000000001"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillBatchPaymentResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"create_bill_payments_batch_api_v1_bills_payments_batch_post"}},"/api/v1/bills/{bill_id}":{"get":{"tags":["bills"],"summary":"Get bill","description":"Retrieve a specific bill by ID.","operationId":"get_bill","parameters":[{"name":"bill_id","in":"path","required":true,"schema":{"type":"string","title":"Bill Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillResponse_"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"get_bill_api_v1_bills__bill_id__get"},"put":{"tags":["bills"],"summary":"Update bill","description":"Update an existing bill. Optionally include 'recurring' config to create a recurring template.","operationId":"update_bill","parameters":[{"name":"bill_id","in":"path","required":true,"schema":{"type":"string","title":"Bill Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillUpdateRequest"},"example":{"amount":250000,"description":"Office rent - March","due_on":"2026-03-01","payment_method":"ACH"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"update_bill_api_v1_bills__bill_id__put"},"delete":{"tags":["bills"],"summary":"Delete bill","description":"Delete a bill and its associated records.","operationId":"delete_bill","parameters":[{"name":"bill_id","in":"path","required":true,"schema":{"type":"string","title":"Bill Id"}},{"name":"force","in":"query","required":false,"schema":{"type":"boolean","description":"Force delete even if bill has associated records","default":false,"title":"Force"},"description":"Force delete even if bill has associated records"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__core__success__MessageResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict - Resource already exists or is in an incompatible state","content":{"application/json":{"example":{"error":"conflict","message":"Resource already exists","code":"CONFLICT_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"delete_bill_api_v1_bills__bill_id__delete"}},"/api/v1/bills/{bill_id}/approval":{"patch":{"tags":["bills"],"summary":"Approve bill","description":"Approve a bill and change status to 'forecasted'","operationId":"approve_bill","parameters":[{"name":"bill_id","in":"path","required":true,"schema":{"type":"string","title":"Bill Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillResponse_"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"approve_bill_api_v1_bills__bill_id__approval_patch"}},"/api/v1/bills/{bill_id}/submit-for-approval":{"post":{"tags":["bills"],"summary":"Send bill for approval","description":"Submit a cleaned-up draft bill into the AP approval workflow. The bill moves to 'pending_approval' and is NOT posted to the general ledger until an approver signs off, at which point it posts to 'received'. Requires the business to have the approval workflow enabled.","operationId":"submit_bill_for_approval","parameters":[{"name":"bill_id","in":"path","required":true,"schema":{"type":"string","title":"Bill Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillReceivedRequest"},"example":{"amount":250000,"due_on":"2024-01-31T00:00:00Z","journal_entry_date":"2024-01-15T00:00:00Z","ledger_id":"019ab37c-1ed1-7000-8000-000000000001","received_on":"2024-01-15T00:00:00Z"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"submit_bill_for_approval_api_v1_bills__bill_id__submit_for_approval_post"}},"/api/v1/bills/{bill_id}/submit-for-ap-approval":{"post":{"tags":["bills"],"summary":"Submit bill for AP approval","description":"Manually route a forecasted bill into the firm's AP approval workflow. Use when a bill was approved before the workflow was provisioned or when automatic routing did not run. The bill moves from 'forecasted' to 'pending_approval' and posts to 'received' only once an approver signs off.","operationId":"submit_bill_for_ap_approval","parameters":[{"name":"bill_id","in":"path","required":true,"schema":{"type":"string","title":"Bill Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillReceivedRequest"},"example":{"amount":250000,"due_on":"2024-01-31T00:00:00Z","journal_entry_date":"2024-01-15T00:00:00Z","ledger_id":"019ab37c-1ed1-7000-8000-000000000001","received_on":"2024-01-15T00:00:00Z"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_SubmitBillForApApprovalResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"submit_bill_for_ap_approval_api_v1_bills__bill_id__submit_for_ap_approval_post"}},"/api/v1/bills/{bill_id}/resolve-approval":{"post":{"tags":["bills"],"summary":"Force-resolve a stuck pending-approval bill","description":"Manually drive a bill that is wedged in 'pending_approval' to a terminal state when the normal Approve/Reject card is unavailable (the approval run never started, crashed before suspending, or suspended on a gate with no approvers). Cancels any in-flight approval run for the bill, then either approves it to 'received' (posting the journal entry) or rejects it to 'canceled'.","operationId":"resolve_pending_approval","parameters":[{"name":"bill_id","in":"path","required":true,"schema":{"type":"string","title":"Bill Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolvePendingApprovalRequest"},"example":{"action":"approve","ledger_id":"0192a4f0-1b2c-7d3e-8f4a-5b6c7d8e9f11"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"resolve_pending_approval_api_v1_bills__bill_id__resolve_approval_post"}},"/api/v1/bills/{bill_id}/revert-to-draft":{"post":{"tags":["bills"],"summary":"Revert bill to draft","description":"Move a 'forecasted', 'pending_approval' or 'received' bill back to 'draft' so it can be edited. A received bill's journal entry is reversed on its original date (refused if that period is closed or any payment/credit is applied); a multi-account split is kept on the draft. Any in-flight approval run is cancelled. Bills raised by a purchase order or inventory transfer cannot be reverted.","operationId":"revert_bill_to_draft","parameters":[{"name":"bill_id","in":"path","required":true,"schema":{"type":"string","title":"Bill Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict - Resource already exists or is in an incompatible state","content":{"application/json":{"example":{"error":"conflict","message":"Resource already exists","code":"CONFLICT_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"revert_bill_to_draft_api_v1_bills__bill_id__revert_to_draft_post"}},"/api/v1/bills/{bill_id}/contract-comparison":{"post":{"tags":["bills"],"summary":"Compare bill against vendor contract","description":"Compare a bill's amount against the vendor's active contract/MSA.","operationId":"compare_bill_against_contract","parameters":[{"name":"bill_id","in":"path","required":true,"schema":{"type":"string","title":"Bill Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_CompareBillAgainstContractResponse_"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"compare_bill_against_contract_api_v1_bills__bill_id__contract_comparison_post"}},"/api/v1/bills/{bill_id}/receipt":{"patch":{"tags":["bills"],"summary":"Mark bill as received","description":"Mark a bill as received and create journal entry","operationId":"mark_bill_received","parameters":[{"name":"bill_id","in":"path","required":true,"schema":{"type":"string","title":"Bill Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillReceivedRequest"},"example":{"amount":250000,"due_on":"2024-01-31T00:00:00Z","journal_entry_date":"2024-01-15T00:00:00Z","ledger_id":"019ab37c-1ed1-7000-8000-000000000001","received_on":"2024-01-15T00:00:00Z"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"mark_bill_received_api_v1_bills__bill_id__receipt_patch"}},"/api/v1/bills/{bill_id}/journal-entry":{"post":{"tags":["bills"],"summary":"Generate bill journal entry","description":"Create the outstanding AP journal entry for a received bill that has none linked.","operationId":"generate_bill_journal_entry","parameters":[{"name":"bill_id","in":"path","required":true,"schema":{"type":"string","title":"Bill Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillJournalEntryGenerateRequest"},"example":{"journal_entry_date":"2026-02-15","ledger_id":"0192a4f0-1b2c-7d3e-8f4a-5b6c7d8e9f11"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict - Resource already exists or is in an incompatible state","content":{"application/json":{"example":{"error":"conflict","message":"Resource already exists","code":"CONFLICT_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"generate_bill_journal_entry_api_v1_bills__bill_id__journal_entry_post"}},"/api/v1/bills/{bill_id}/journal-entry/link":{"post":{"tags":["bills"],"summary":"Attach journal entry to bill","description":"Link an existing journal entry to a bill.","operationId":"attach_journal_entry_to_bill","parameters":[{"name":"bill_id","in":"path","required":true,"schema":{"type":"string","title":"Bill Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JournalEntryLinkRequest"},"example":{"journal_entry_id":"0192a4f0-1b2c-7d3e-8f4a-5b6c7d8e9f22"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict - Resource already exists or is in an incompatible state","content":{"application/json":{"example":{"error":"conflict","message":"Resource already exists","code":"CONFLICT_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"attach_journal_entry_to_bill_api_v1_bills__bill_id__journal_entry_link_post"}},"/api/v1/bills/{bill_id}/cancellation":{"patch":{"tags":["bills"],"summary":"Cancel bill","description":"Cancel a bill and change status to 'canceled'","operationId":"cancel_bill","parameters":[{"name":"bill_id","in":"path","required":true,"schema":{"type":"string","title":"Bill Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillResponse_"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"cancel_bill_api_v1_bills__bill_id__cancellation_patch"}},"/api/v1/bills/{bill_id}/payment-initiation":{"patch":{"tags":["bills"],"summary":"Mark or clear bill payment-initiated","description":"Track money in flight: mark that payment was initiated outside DayZero (e.g. a bank with no API) before the bank transaction exists to reconcile against.","operationId":"set_bill_payment_initiation","parameters":[{"name":"bill_id","in":"path","required":true,"schema":{"type":"string","title":"Bill Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillPaymentInitiationRequest"},"example":{"initiated":true,"initiated_on":"2026-02-20T15:30:00Z"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"set_bill_payment_initiation_api_v1_bills__bill_id__payment_initiation_patch"}},"/api/v1/bills/{bill_id}/payments":{"post":{"tags":["bills"],"summary":"Add payment to bill","description":"Create a new payment for a specific bill.","operationId":"create_bill_payment","parameters":[{"name":"bill_id","in":"path","required":true,"schema":{"type":"string","title":"Bill Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillPaymentRequest"},"example":{"amount":125000,"transaction_id":"019ab37c-7801-7000-8000-000000000001"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillPaymentResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"create_bill_payment_api_v1_bills__bill_id__payments_post"},"get":{"tags":["bills"],"summary":"List bill payments","description":"Retrieve all payments for a specific bill.","operationId":"list_bill_payments","parameters":[{"name":"bill_id","in":"path","required":true,"schema":{"type":"string","title":"Bill Id"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Cursor for pagination","title":"Cursor"},"description":"Cursor for pagination"},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":1000,"minimum":1},{"type":"null"}],"description":"Pagination limit","title":"Limit"},"description":"Pagination limit"},{"name":"direction","in":"query","required":false,"schema":{"type":"string","description":"Pagination direction: 'next' or 'prev'","default":"next","title":"Direction"},"description":"Pagination direction: 'next' or 'prev'"},{"name":"include_total_count","in":"query","required":false,"schema":{"type":"boolean","description":"Whether to include total count (expensive - avoid if possible)","default":false,"title":"Include Total Count"},"description":"Whether to include total count (expensive - avoid if possible)"},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Column name to sort by (e.g. 'created_at', 'amount', 'name'). When changing sort, reset cursor to None.","title":"Sort By"},"description":"Column name to sort by (e.g. 'created_at', 'amount', 'name'). When changing sort, reset cursor to None."},{"name":"descending","in":"query","required":false,"schema":{"type":"boolean","description":"Sort direction: true for descending (newest/largest first), false for ascending","default":true,"title":"Descending"},"description":"Sort direction: true for descending (newest/largest first), false for ascending"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_ListBillPaymentsResponse_"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"list_bill_payments_api_v1_bills__bill_id__payments_get"}},"/api/v1/bills/{bill_id}/payments/{payment_id}":{"delete":{"tags":["bills"],"summary":"Remove payment from bill","description":"Un-link a payment record from a bill and recalculate status.","operationId":"delete_bill_payment","parameters":[{"name":"bill_id","in":"path","required":true,"schema":{"type":"string","title":"Bill Id"}},{"name":"payment_id","in":"path","required":true,"schema":{"type":"string","title":"Payment Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__core__success__MessageResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"delete_bill_payment_api_v1_bills__bill_id__payments__payment_id__delete"}},"/api/v1/bills/upload":{"post":{"tags":["bills"],"summary":"Upload bill document","description":"Upload a PDF or image file for a bill. Returns s3_key to use when creating/updating bills.","operationId":"upload_bill_file","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_bill_file_api_v1_bills_upload_post"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_UploadBillFileResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"upload_bill_file_api_v1_bills_upload_post"}},"/api/v1/bills/{bill_id}/attachment":{"patch":{"tags":["bills"],"summary":"Attach file to existing bill","description":"Attach a document file to an existing bill by updating its s3_key.","operationId":"attach_file_to_bill","parameters":[{"name":"bill_id","in":"path","required":true,"schema":{"type":"string","title":"Bill Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_attach_file_to_bill_api_v1_bills__bill_id__attachment_patch"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"attach_file_to_bill_api_v1_bills__bill_id__attachment_patch"}},"/api/v1/bills/suggest-payment-priority":{"post":{"tags":["bills"],"summary":"AI payment priority suggestions","description":"Get AI-powered bill payment priority recommendations.","operationId":"suggest_payment_priority","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_SuggestPaymentPriorityResponse_"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"suggest_payment_priority_api_v1_bills_suggest_payment_priority_post"}},"/api/v1/bills/payment-suggestions/trigger":{"post":{"tags":["bills"],"summary":"Trigger bill payment matching","description":"Run the AP matching engine to find bank transactions that match open bills.","operationId":"trigger_bill_payment_matching","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TriggerBillMatchingRequest","default":{"auto_match":false}}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_TriggerBillMatchingResponse_"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"trigger_bill_payment_matching_api_v1_bills_payment_suggestions_trigger_post"}},"/api/v1/bills/payment-suggestions/{suggestion_id}/accept":{"post":{"tags":["bills"],"summary":"Accept a bill payment suggestion","description":"Accept a suggestion and create the actual BillPayment.","operationId":"accept_bill_payment_suggestion","parameters":[{"name":"suggestion_id","in":"path","required":true,"schema":{"type":"string","title":"Suggestion Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillPaymentResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"accept_bill_payment_suggestion_api_v1_bills_payment_suggestions__suggestion_id__accept_post"}},"/api/v1/bills/payment-suggestions/{suggestion_id}/reject":{"post":{"tags":["bills"],"summary":"Reject a bill payment suggestion","description":"Reject a suggestion so it is no longer shown.","operationId":"reject_bill_payment_suggestion","parameters":[{"name":"suggestion_id","in":"path","required":true,"schema":{"type":"string","title":"Suggestion Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BillPaymentSuggestionRejectResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"reject_bill_payment_suggestion_api_v1_bills_payment_suggestions__suggestion_id__reject_post"}},"/api/v1/bills/payment-suggestions/bulk-approve":{"post":{"tags":["bills"],"summary":"Bulk approve bill payment suggestions","description":"Accept all pending suggestions above a confidence threshold.","operationId":"bulk_approve_bill_suggestions","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkApproveSuggestionsRequest","default":{"min_confidence":0.85}}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_BulkApproveSuggestionsResponse_"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"bulk_approve_bill_suggestions_api_v1_bills_payment_suggestions_bulk_approve_post"}}},"components":{"schemas":{"AgingBillItem":{"properties":{"id":{"type":"string","title":"Id"},"bill_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bill Number"},"vendor_id":{"type":"string","title":"Vendor Id"},"vendor_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Name"},"status":{"type":"string","title":"Status"},"amount":{"type":"integer","title":"Amount","description":"Bill amount in cents."},"total_paid":{"type":"integer","title":"Total Paid","description":"Total paid in cents.","default":0},"credits_applied":{"type":"integer","title":"Credits Applied","description":"Vendor credits applied to this bill in cents.","default":0},"balance_due":{"type":"integer","title":"Balance Due","description":"Remaining balance in cents."},"due_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Due Date"},"days_past_due":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Days Past Due"},"bucket":{"type":"string","title":"Bucket","description":"Aging bucket: 'current', '1_30', '31_60', '61_90', '91_plus'."}},"type":"object","required":["id","vendor_id","status","amount","balance_due","bucket"],"title":"AgingBillItem","description":"A single bill with its aging bucket assignment."},"AgingVendorSummary":{"properties":{"vendor_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Id"},"vendor_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Name"},"current":{"type":"integer","title":"Current","default":0},"days_1_30":{"type":"integer","title":"Days 1 30","default":0},"days_31_60":{"type":"integer","title":"Days 31 60","default":0},"days_61_90":{"type":"integer","title":"Days 61 90","default":0},"days_91_plus":{"type":"integer","title":"Days 91 Plus","default":0},"total":{"type":"integer","title":"Total","default":0},"unapplied_credits":{"type":"integer","title":"Unapplied Credits","description":"Issued vendor credits not yet applied to bills (cents).","default":0},"net_total":{"type":"integer","title":"Net Total","description":"Total open AP minus unapplied vendor credits (cents).","default":0}},"type":"object","title":"AgingVendorSummary","description":"Per-vendor aging bucket totals (all amounts in cents)."},"BillAICreatePayloadRequest":{"properties":{"pasted_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pasted Text","description":"Raw text content to extract a bill from. Limit 1 bill per text input. Mutually exclusive with pasted_text_s3_key."},"pasted_text_s3_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pasted Text S3 Key","description":"S3 key of pasted text content. Limit 1 bill per text input. Mutually exclusive with pasted_text."},"single_bill_s3_keys":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Single Bill S3 Keys","description":"S3 keys of individual bill documents (PDFs, images, Excel). Each file is processed independently."},"multi_bill_s3_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Multi Bill S3 Key","description":"S3 key of a CSV file containing multiple bills."}},"type":"object","title":"BillAICreatePayloadRequest","description":"Request schema for AI-powered bill extraction from uploaded documents.\n\nProvide one or more source inputs. The AI will analyze each source and\nextract draft bill entities from the content.\n\nSource types:\n- pasted_text: Raw text content to extract a bill from (limit 1 bill)\n- pasted_text_s3_key: S3 key of pasted text content (limit 1 bill)\n- single_bill_s3_keys: S3 keys of individual bill documents (PDFs, images, Excel)\n- multi_bill_s3_key: S3 key of a CSV or Excel file containing multiple bills","example":{"single_bill_s3_keys":["business-id/uuid-bill1.pdf","business-id/uuid-bill2.png"]},"examples":[{"single_bill_s3_keys":["business-id/uuid-bill1.pdf","business-id/uuid-bill2.png"]}]},"BillAICreatePayloadResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/DraftBill"},"type":"array","title":"Items","description":"List of draft bill entities extracted by AI."},"errors":{"items":{"$ref":"#/components/schemas/FileProcessingError"},"type":"array","title":"Errors","description":"List of per-file errors for files that could not be processed."}},"type":"object","required":["items"],"title":"BillAICreatePayloadResponse","description":"Response schema for AI-powered bill extraction.\n\nReturns a list of draft bill entities extracted from the uploaded documents.\nEach draft bill contains all fields needed to create a bill in 'received' status.\nFiles that fail are reported in the ``errors`` list rather than causing\nthe entire request to fail.","example":{"errors":[],"items":[{"amount":15000,"bill_number":"INV-12345","confidence":0.92,"currency":"USD","description":"Office supplies","expense_category":"Office Supplies","source":"single_file","type":"one_time","vendor_name":"Office Depot"}]},"examples":[{"errors":[],"items":[{"amount":15000,"bill_number":"INV-12345","confidence":0.92,"currency":"USD","description":"Office supplies","expense_category":"Office Supplies","source":"single_file","type":"one_time","vendor_name":"Office Depot"}]}]},"BillAgingResponse":{"properties":{"as_of_date":{"type":"string","title":"As Of Date","description":"Report date in YYYY-MM-DD format."},"vendors":{"items":{"$ref":"#/components/schemas/AgingVendorSummary"},"type":"array","title":"Vendors","description":"Per-vendor aging summary rows."},"bills":{"items":{"$ref":"#/components/schemas/AgingBillItem"},"type":"array","title":"Bills","description":"Individual bills with aging bucket for drill-down."},"totals":{"$ref":"#/components/schemas/AgingVendorSummary","description":"Grand totals across all vendors."}},"type":"object","required":["as_of_date","vendors","bills","totals"],"title":"BillAgingResponse","description":"AP Aging Summary with per-vendor buckets and bill-level detail."},"BillBatchExpenseLine":{"properties":{"ledger_id":{"type":"string","title":"Ledger Id","description":"UUID of the expense ledger account to debit."},"amount":{"type":"integer","exclusiveMinimum":0.0,"title":"Amount","description":"Amount in cents to categorize as expense. Must be > 0."},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description","description":"Optional memo stored on the journal-entry line."}},"type":"object","required":["ledger_id","amount"],"title":"BillBatchExpenseLine","description":"Direct expense categorization for a slice of the bank transaction."},"BillBatchPaymentAllocation":{"properties":{"bill_id":{"type":"string","title":"Bill Id","description":"UUID of the bill receiving this slice of the transaction."},"amount":{"type":"integer","exclusiveMinimum":0.0,"title":"Amount","description":"Amount in cents to allocate to this bill. Must be > 0."}},"type":"object","required":["bill_id","amount"],"title":"BillBatchPaymentAllocation","description":"A single bill allocation inside a batch payment request."},"BillBatchPaymentRequest":{"properties":{"transaction_id":{"type":"string","title":"Transaction Id","description":"UUID of the bank transaction representing the payment."},"allocations":{"items":{"$ref":"#/components/schemas/BillBatchPaymentAllocation"},"type":"array","title":"Allocations","description":"Bill slices (0+). Each `bill_id` must be unique."},"expense_lines":{"items":{"$ref":"#/components/schemas/BillBatchExpenseLine"},"type":"array","title":"Expense Lines","description":"Optional expense lines for any remaining balance. Each line debits an expense ledger on the transaction's journal entry."},"paid_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Paid On","description":"Override payment date applied to every allocation. Defaults to the transaction datetime if omitted."}},"type":"object","required":["transaction_id"],"title":"BillBatchPaymentRequest","description":"Schema for splitting a single bank transaction across multiple bills.\n\nAll allocations are applied atomically *after* up-front validation: if\nthe total allocation would exceed the transaction's remaining\nunallocated balance, or any bill is invalid, no payment records are\ncreated.","example":{"allocations":[{"amount":50000,"bill_id":"019ab37c-b111-7000-8000-000000000001"},{"amount":75000,"bill_id":"019ab37c-b111-7000-8000-000000000002"}],"transaction_id":"019ab37c-7801-7000-8000-000000000001"},"examples":[{"allocations":[{"amount":50000,"bill_id":"019ab37c-b111-7000-8000-000000000001"},{"amount":75000,"bill_id":"019ab37c-b111-7000-8000-000000000002"}],"transaction_id":"019ab37c-7801-7000-8000-000000000001"}]},"BillBatchPaymentResponse":{"properties":{"transaction_id":{"type":"string","title":"Transaction Id","description":"Bank transaction UUID."},"total_allocated":{"type":"integer","title":"Total Allocated","description":"Total cents allocated across all bills in this batch."},"total_expense_allocated":{"type":"integer","title":"Total Expense Allocated","description":"Total cents categorized as direct expense in this batch.","default":0},"payment_count":{"type":"integer","title":"Payment Count","description":"Number of BillPayment records created."},"expense_line_count":{"type":"integer","title":"Expense Line Count","description":"Number of expense lines categorized in this batch.","default":0},"payments":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Payments","description":"Per-bill payment payloads (mirrors BillPaymentResponse)."}},"type":"object","required":["transaction_id","total_allocated","payment_count"],"title":"BillBatchPaymentResponse","description":"Response for a batch payment split across multiple bills."},"BillBulkRequest":{"properties":{"s3_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"S3 Key","description":"S3 key of the uploaded CSV file containing bill data."},"approve":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Approve","description":"If true, created bills are set to 'forecasted' status (approved). If false, bills remain as 'draft'.","default":false},"create_as_received":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Create As Received","description":"If true, every row is created in 'received' status with an accounting journal entry. Each row must have a resolvable expense ledger (ledger_id, ledger_name, or expense_account column) and a valid amount. Overrides `approve` when set.","default":false},"attachments":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Attachments","description":"Optional mapping of source filename → pre-uploaded S3 key (from POST /bills/upload). Rows whose `attachment_filename` matches a key in this map have the corresponding document attached."}},"additionalProperties":true,"type":"object","title":"BillBulkRequest","description":"Request schema for bulk bill creation via CSV upload.\n\nUpload a CSV file to S3 first, then provide the s3_key here.\n\nCSV columns (required):\n- vendor_email: Email of the vendor (must exist in the system)\n- expected_amount: Expected bill amount in dollars. Accepts plain numbers\n  (1500.00, 1500), currency symbols ($1,500.00), and thousands separators.\n\nCSV columns (optional):\n- description: Description of the bill\n- bill_number: Vendor's bill/invoice number (auto-generated when blank)\n- type: 'recurring' or 'one_time' (defaults to 'one_time')\n- currency: USD/CAD/AUD/EUR/GBP (defaults to business default)\n- due_date: Payment due date (YYYY-MM-DD)\n- expected_paid_on_date: Expected payment date (YYYY-MM-DD)\n- received_on: Date bill was received (YYYY-MM-DD). Required when\n  create_as_received=True.\n- journal_entry_date: Date for accounting journal entry (YYYY-MM-DD).\n  Defaults to received_on when create_as_received=True.\n- ledger_id / ledger_name / expense_account: Expense ledger for the\n  journal entry. Required when create_as_received=True. ledger_id takes\n  precedence; ledger_name/expense_account are matched (case-insensitive)\n  against active expense ledgers in the business.\n- attachment_filename: Filename matching a key in the request `attachments`\n  map. The corresponding s3_key is attached to the created bill.","example":{"approve":false,"attachments":{"rent-jan.pdf":"attachments/019c30bb-dc4c-7e7e-8f9a-aaa","supplies-feb.pdf":"attachments/019c30bb-dc4c-7e7e-8f9a-bbb"},"create_as_received":false,"s3_key":"uploads/bills/batch-2024-01.csv"},"examples":[{"approve":false,"attachments":{"rent-jan.pdf":"attachments/019c30bb-dc4c-7e7e-8f9a-aaa","supplies-feb.pdf":"attachments/019c30bb-dc4c-7e7e-8f9a-bbb"},"create_as_received":false,"s3_key":"uploads/bills/batch-2024-01.csv"}]},"BillCreateRequest":{"properties":{"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description of what the bill is for."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"Currency for the bill (USD, CAD, AUD, EUR, or GBP). Defaults to business default.","default":"USD"},"vendor_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Id","description":"UUID of the vendor this bill is from."},"bill_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bill Number","description":"Bill/invoice number from the vendor. Auto-generated if not provided."},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type","description":"Bill type: 'recurring' (monthly rent, subscriptions) or 'one_time'."},"expected_amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expected Amount","description":"Expected bill amount in cents."},"expected_paid_on_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"},{"type":"null"}],"title":"Expected Paid On Date","description":"Expected payment date (ISO 8601 format)."},"s3_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"S3 Key","description":"S3 key of uploaded bill document (PDF/image)."},"recurring":{"anyOf":[{"$ref":"#/components/schemas/RecurringConfig"},{"type":"null"}],"description":"If provided, creates a recurring template for this bill."},"submitted_for_review":{"type":"boolean","title":"Submitted For Review","description":"When true, marks this draft as a client-submitted expense and notifies the assigned advisor to confirm or deny it.","default":false}},"type":"object","title":"BillCreateRequest","description":"Schema for creating a new bill (expense from a vendor).\n\nBills track money owed to vendors for goods or services received.\nThey progress through statuses: draft → forecasted → received → paid.","example":{"description":"Monthly office rent - January 2024","expected_amount":250000,"expected_paid_on_date":"2024-01-31T00:00:00Z","type":"recurring","vendor_id":"019ab37c-ae0d-7000-8000-000000000001"},"examples":[{"description":"Monthly office rent - January 2024","expected_amount":250000,"expected_paid_on_date":"2024-01-31T00:00:00Z","type":"recurring","vendor_id":"019ab37c-ae0d-7000-8000-000000000001"}]},"BillJournalEntryGenerateRequest":{"properties":{"ledger_id":{"type":"string","title":"Ledger Id","description":"UUID of the expense ledger account to debit."},"journal_entry_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"},{"type":"string"},{"type":"null"}],"title":"Journal Entry Date","description":"Date for the accounting journal entry (ISO 8601 or YYYY-MM-DD). Defaults to received_on."}},"type":"object","required":["ledger_id"],"title":"BillJournalEntryGenerateRequest","description":"Generate the outstanding AP journal entry for a received bill.","example":{"journal_entry_date":"2026-02-15","ledger_id":"0192a4f0-1b2c-7d3e-8f4a-5b6c7d8e9f11"},"examples":[{"journal_entry_date":"2026-02-15","ledger_id":"0192a4f0-1b2c-7d3e-8f4a-5b6c7d8e9f11"}]},"BillMetricsResponse":{"properties":{"total_due":{"type":"integer","title":"Total Due","description":"Sum of the amount for all bills in 'received' or 'partially_paid' status (in cents)."},"total_balance_due":{"type":"integer","title":"Total Balance Due","description":"Sum of (amount - total_paid - applied vendor credits) for all bills in 'received' or 'partially_paid' status (in cents)."},"overdue_balance":{"type":"integer","title":"Overdue Balance","description":"Sum of remaining balances (amount - total_paid - applied vendor credits, floored at 0 per bill) for bills whose effective due date is in the past, across all statuses except 'paid'/'canceled' (in cents).","default":0}},"type":"object","required":["total_due","total_balance_due"],"title":"BillMetricsResponse","description":"Response schema for bill aggregate metrics."},"BillPaymentInitiationRequest":{"properties":{"initiated":{"type":"boolean","title":"Initiated","description":"True to mark payment initiated; False to clear the marker."},"initiated_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Initiated On","description":"When the payment was initiated. Defaults to now when marking."}},"type":"object","required":["initiated"],"title":"BillPaymentInitiationRequest","description":"Request for ``PATCH /bills/{bill_id}/payment-initiation``.\n\nMarks (or clears) the \"money is in flight\" flag for bills paid from an\nexternal bank with no API: initiated outside DayZero, awaiting the bank\ntransaction to reconcile against.","example":{"initiated":true,"initiated_on":"2026-02-20T15:30:00Z"},"examples":[{"initiated":true,"initiated_on":"2026-02-20T15:30:00Z"}]},"BillPaymentRequest":{"properties":{"transaction_id":{"type":"string","title":"Transaction Id","description":"UUID of the bank transaction representing the payment."},"amount":{"type":"integer","exclusiveMinimum":0.0,"title":"Amount","description":"Payment amount in cents. Must be > 0."},"paid_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Paid On","description":"Override payment date (ISO 8601). Defaults to the transaction datetime if omitted."}},"type":"object","required":["transaction_id","amount"],"title":"BillPaymentRequest","description":"Schema for recording a payment against a bill.\n\nLinks a bank transaction to a bill to track partial or full payment.\nSupports split payments (one transaction paying multiple bills) and\npartial payments (multiple transactions paying one bill).","example":{"amount":125000,"transaction_id":"019ab37c-7801-7000-8000-000000000001"},"examples":[{"amount":125000,"transaction_id":"019ab37c-7801-7000-8000-000000000001"}]},"BillPaymentResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Payment record UUID."},"bill_id":{"type":"string","title":"Bill Id","description":"UUID of the bill being paid."},"transaction_id":{"type":"string","title":"Transaction Id","description":"UUID of the bank transaction."},"amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Amount","description":"Payment amount in cents."},"currency":{"type":"string","title":"Currency","description":"Currency for the payment (USD, CAD, AUD, EUR, or GBP).","default":"USD"},"paid_on":{"type":"string","format":"date-time","title":"Paid On","description":"Payment date."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Record creation timestamp."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last update timestamp."},"business_id":{"type":"string","title":"Business Id","description":"Business UUID."}},"type":"object","required":["id","bill_id","transaction_id","amount","paid_on","created_at","updated_at","business_id"],"title":"BillPaymentResponse","description":"Response schema for a bill payment record.\n\nRepresents a payment made against a bill, linking to the bank transaction.","example":{"amount":250000,"bill_id":"019ab37c-b111-7000-8000-000000000001","business_id":"019ab37c-b051-7000-8000-000000000001","created_at":"2024-01-25T10:30:00Z","id":"019ab37c-9a41-7000-8000-000000000001","paid_on":"2024-01-25T00:00:00Z","transaction_id":"019ab37c-7801-7000-8000-000000000001","updated_at":"2024-01-25T10:30:00Z"},"examples":[{"amount":250000,"bill_id":"019ab37c-b111-7000-8000-000000000001","business_id":"019ab37c-b051-7000-8000-000000000001","created_at":"2024-01-25T10:30:00Z","id":"019ab37c-9a41-7000-8000-000000000001","paid_on":"2024-01-25T00:00:00Z","transaction_id":"019ab37c-7801-7000-8000-000000000001","updated_at":"2024-01-25T10:30:00Z"}]},"BillPaymentSuggestionRejectResponse":{"properties":{"status":{"type":"string","title":"Status"},"suggestion_id":{"type":"string","title":"Suggestion Id"}},"additionalProperties":true,"type":"object","required":["status","suggestion_id"],"title":"BillPaymentSuggestionRejectResponse","description":"Acknowledgement for ``reject_bill_payment_suggestion``."},"BillPaymentSuggestionResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Suggestion UUID"},"bill_id":{"type":"string","title":"Bill Id","description":"Bill UUID"},"bill_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bill Number","description":"Bill number"},"vendor_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Name","description":"Vendor name"},"transaction_id":{"type":"string","title":"Transaction Id","description":"Transaction UUID"},"transaction_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Transaction Description","description":"Transaction description"},"transaction_counterparty":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Transaction Counterparty","description":"Transaction counterparty"},"transaction_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Transaction Date","description":"Date of the transaction"},"transaction_account_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Transaction Account Name","description":"Name of the ledger/bank account the transaction posted to"},"business_id":{"type":"string","title":"Business Id","description":"Business UUID"},"amount":{"type":"integer","title":"Amount","description":"Suggested payment amount in cents"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","description":"Match confidence (0–1)"},"signals":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Signals","description":"Signal score breakdown"},"match_group_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Match Group Id","description":"Group ID for multi-bill matches"},"status":{"type":"string","title":"Status","description":"pending | accepted | rejected | expired"},"reviewed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reviewed At","description":"When reviewed"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When created"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When updated"}},"type":"object","required":["id","bill_id","transaction_id","business_id","amount","confidence","status"],"title":"BillPaymentSuggestionResponse","description":"Response schema for a bill payment suggestion."},"BillPaymentSuggestionsListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/BillPaymentSuggestionResponse"},"type":"array","title":"Items","description":"List of suggestions"},"pending_count":{"type":"integer","title":"Pending Count","description":"Total pending suggestions","default":0}},"type":"object","title":"BillPaymentSuggestionsListResponse","description":"Response schema for listing bill payment suggestions."},"BillReceivedCreateRequest":{"properties":{"vendor_id":{"type":"string","title":"Vendor Id","description":"UUID of the vendor this bill is from (required)."},"amount":{"type":"integer","title":"Amount","description":"Bill amount in cents (required)."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description of what the bill is for."},"bill_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bill Number","description":"Bill/invoice number from the vendor. Auto-generated if not provided."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"Currency for the bill (USD, CAD, AUD, EUR, or GBP). Defaults to business default.","default":"USD"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type","description":"Bill type: 'recurring' or 'one_time'. Defaults to 'one_time'.","default":"one_time"},"received_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"},{"type":"null"}],"title":"Received On","description":"Date the bill was received (ISO 8601). Defaults to now."},"due_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"},{"type":"null"}],"title":"Due On","description":"Payment due date (ISO 8601)."},"s3_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"S3 Key","description":"S3 key of uploaded bill document (PDF/image)."},"ledger_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ledger Id","description":"UUID of the expense ledger for journal entry creation. If provided, creates journal entry automatically. Ignored when line_items is provided."},"line_items":{"anyOf":[{"items":{"$ref":"#/components/schemas/JournalEntryLineItem"},"type":"array"},{"type":"null"}],"title":"Line Items","description":"Split journal entry lines. Each line specifies a debit account and amount. The credit side is always Accounts Payable. When provided, ledger_id is ignored."},"journal_entry_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"},{"type":"string"},{"type":"null"}],"title":"Journal Entry Date","description":"Date for the accounting journal entry (ISO 8601 or YYYY-MM-DD). Defaults to received_on if not provided."}},"type":"object","required":["vendor_id","amount"],"title":"BillReceivedCreateRequest","description":"Schema for creating a bill directly in 'received' status.\n\nThis endpoint bypasses the draft stage and creates a bill that's ready\nfor payment. Useful for manually entering bills that have already been received.\n\nWhen ledger_id is provided, this endpoint will also create the associated\njournal entry (debit to expense ledger, credit to accounts payable).\n\nFor split journal entries, provide line_items instead of ledger_id.\nEach line_item specifies a debit account and amount; the credit side\nis always Accounts Payable for the full bill amount.","example":{"amount":56135,"bill_number":"P054","currency":"USD","description":"Purchase Order (P054) issued by Artisan AI LLC","due_on":"2025-03-29T12:00:00Z","journal_entry_date":"2025-02-27T12:00:00Z","ledger_id":"019ab37c-1ed1-7000-8000-000000000001","received_on":"2025-02-27T12:00:00Z","s3_key":"attachments/019c30bb-dc4c-7e7e-8f9a-123456789abc","type":"one_time","vendor_id":"019ab37c-ae0d-7000-8000-000000000001"},"examples":[{"amount":56135,"bill_number":"P054","currency":"USD","description":"Purchase Order (P054) issued by Artisan AI LLC","due_on":"2025-03-29T12:00:00Z","journal_entry_date":"2025-02-27T12:00:00Z","ledger_id":"019ab37c-1ed1-7000-8000-000000000001","received_on":"2025-02-27T12:00:00Z","s3_key":"attachments/019c30bb-dc4c-7e7e-8f9a-123456789abc","type":"one_time","vendor_id":"019ab37c-ae0d-7000-8000-000000000001"}]},"BillReceivedRequest":{"properties":{"bill_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bill Id","description":"UUID of the bill (set automatically from URL path)."},"amount":{"type":"integer","exclusiveMinimum":0.0,"title":"Amount","description":"Actual bill amount in cents. Must be greater than 0."},"ledger_id":{"type":"string","title":"Ledger Id","description":"UUID of the expense ledger account to categorize this bill. Required for creating the journal entry."},"s3_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"S3 Key","description":"S3 key of the bill document."},"journal_entry_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"},{"type":"string"},{"type":"null"}],"title":"Journal Entry Date","description":"Date for the accounting journal entry (ISO 8601 or YYYY-MM-DD)."},"received_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"},{"type":"string"},{"type":"null"}],"title":"Received On","description":"Date the bill/goods were received (ISO 8601 or YYYY-MM-DD)."},"due_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"},{"type":"string"},{"type":"null"}],"title":"Due On","description":"Payment due date (ISO 8601 or YYYY-MM-DD)."}},"type":"object","required":["amount","ledger_id"],"title":"BillReceivedRequest","description":"Schema for marking a bill as received and creating journal entries.\n\nWhen a bill is marked as received, accounting journal entries are created\nto record the liability (Accounts Payable).","example":{"amount":250000,"due_on":"2024-01-31T00:00:00Z","journal_entry_date":"2024-01-15T00:00:00Z","ledger_id":"019ab37c-1ed1-7000-8000-000000000001","received_on":"2024-01-15T00:00:00Z"},"examples":[{"amount":250000,"due_on":"2024-01-31T00:00:00Z","journal_entry_date":"2024-01-15T00:00:00Z","ledger_id":"019ab37c-1ed1-7000-8000-000000000001","received_on":"2024-01-15T00:00:00Z"}]},"BillResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Bill UUID."},"business_id":{"type":"string","title":"Business Id","description":"Business UUID."},"currency":{"type":"string","title":"Currency","description":"Currency for the bill (USD, CAD, AUD, EUR, or GBP).","default":"USD"},"status":{"anyOf":[{"type":"integer"},{"type":"string"}],"title":"Status","description":"Bill status (see schema description)."},"payment_initiated_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Payment Initiated On","description":"When set, payment was initiated outside DayZero (e.g. a bank with no API) but no bank transaction has been linked yet. Cleared automatically when a payment is linked."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Bill description."},"bill_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bill Number","description":"Bill/invoice number from vendor."},"vendor_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Id","description":"Vendor UUID."},"vendor_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Name","description":"Vendor name (resolved)."},"vendor_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Email","description":"Vendor email (resolved)."},"type":{"anyOf":[{"type":"integer"},{"type":"string"}],"title":"Type","description":"Type: 'recurring' or 'one_time'."},"expected_amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expected Amount","description":"Expected amount in cents."},"expected_paid_on_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expected Paid On Date","description":"Expected payment date."},"total_paid":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Paid","description":"Total amount paid so far in cents."},"amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Amount","description":"Actual bill amount in cents."},"s3_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"S3 Key","description":"S3 key of attached document."},"received_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Received On","description":"Date bill/goods received."},"due_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Due On","description":"Payment due date."},"paid_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Paid On","description":"Date fully paid."},"payment_method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Method","description":"Payment method (Wire Transfer, ACH, Check, Credit Card). Prefers the user-set override; otherwise inferred from a linked payment."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last update timestamp."},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url","description":"Signed URL to download the attached document (Content-Disposition: attachment)."},"attachment_unavailable_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Attachment Unavailable Reason","description":"Why `signed_url` is null despite the bill having an attachment (e.g. the malware scan is pending, or the file predates scanning and must be re-uploaded). Lets the UI say whether retrying will ever help. Populated on the bill-detail response only."},"view_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"View Url","description":"Signed URL to preview the attached document inline (Content-Disposition: inline). Populated on the bill-detail response; falls back to null elsewhere."},"payments":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Payments","description":"List of payments made.","default":[]},"vendor_credit_applications":{"items":{"$ref":"#/components/schemas/BillVendorCreditApplicationResponse"},"type":"array","title":"Vendor Credit Applications","description":"Vendor credits applied to this bill (reduces balance due)."},"total_credits_applied":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Credits Applied","description":"Sum of applied vendor credits in cents."},"balance_due":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Balance Due","description":"Remaining balance in cents (amount - total_paid - total_credits_applied). Zero for paid/canceled bills."},"journal_entries":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Journal Entries","description":"Associated accounting entries.","default":[]},"recurring_template_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recurring Template Id","description":"ID of recurring template if this bill was generated from one, or if one was created."},"source_inventory_order_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Inventory Order Id","description":"Source PO that produced this bill via the PO lifecycle. Non-null means this bill is visible on the Inventory -> Accounts Payable tab."},"match_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Match Status","description":"Three-way match outcome: matched, qty_variance, price_variance, qty_and_price_variance, unmatched, no_po. None until the matcher has run on the bill."},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Origin channel for bills not created by a signed-in user, e.g. 'vendor_portal' for invoices submitted through a public bill request link. Null for in-app bills."},"submitter_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Submitter Name","description":"Name typed by the anonymous submitter (vendor portal)."},"submitter_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Submitter Email","description":"Email typed by the anonymous submitter (vendor portal)."},"match_variance_qty":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Match Variance Qty","description":"Signed unit variance across all lines (received - ordered). Positive = over-received; negative = short."},"match_variance_amount_cents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Match Variance Amount Cents","description":"Signed amount variance in cents (bill amount - PO total). Positive = vendor billed more than ordered; negative = less."},"contract_match":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contract Match","description":"Vendor contract comparison: matched, over_contract, needs_review, no_contract, or unknown."},"vendor_contract_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Contract Id","description":"Vendor contract UUID used for the last contract comparison."},"thread":{"anyOf":[{"$ref":"#/components/schemas/BillThreadResponse"},{"type":"null"}],"description":"Discussion thread and comment summary for this bill"}},"type":"object","required":["id","business_id","status","type","created_at","updated_at"],"title":"BillResponse","description":"Response schema for a bill.\n\nContains all bill details including vendor info, payment status,\nand associated journal entries for accounting.\n\n**Status values:**\n- `draft`: Bill created but not yet approved\n- `forecasted`: Approved, expected to be paid\n- `received`: Bill/goods received, liability recorded\n- `partially_paid`: Some payments and/or vendor credits applied\n- `paid`: Fully paid (cash and/or vendor credits)\n- `canceled`: Cancelled, will not be paid","example":{"amount":250000,"business_id":"019ab37c-b051-7000-8000-000000000001","created_at":"2024-01-10T10:30:00Z","description":"Monthly office rent - January 2024","due_on":"2024-01-31T00:00:00Z","expected_amount":250000,"id":"019ab37c-b111-7000-8000-000000000001","journal_entries":[],"payments":[],"received_on":"2024-01-15T00:00:00Z","status":"received","type":"recurring","updated_at":"2024-01-15T14:00:00Z","vendor_email":"billing@abcproperty.com","vendor_id":"019ab37c-ae0d-7000-8000-000000000001","vendor_name":"ABC Property Management"},"examples":[{"amount":250000,"business_id":"019ab37c-b051-7000-8000-000000000001","created_at":"2024-01-10T10:30:00Z","description":"Monthly office rent - January 2024","due_on":"2024-01-31T00:00:00Z","expected_amount":250000,"id":"019ab37c-b111-7000-8000-000000000001","journal_entries":[],"payments":[],"received_on":"2024-01-15T00:00:00Z","status":"received","type":"recurring","updated_at":"2024-01-15T14:00:00Z","vendor_email":"billing@abcproperty.com","vendor_id":"019ab37c-ae0d-7000-8000-000000000001","vendor_name":"ABC Property Management"}]},"BillThreadResponse":{"properties":{"thread_id":{"type":"string","title":"Thread Id","description":"Thread UUID"},"comment_count":{"type":"integer","title":"Comment Count","description":"Number of comments on the thread"},"comments":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Comments","description":"Thread comments (detail view)"}},"additionalProperties":true,"type":"object","required":["thread_id","comment_count"],"title":"BillThreadResponse","description":"Thread summary embedded on bill detail responses."},"BillUpdateRequest":{"properties":{"status":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"bill_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bill Number"},"vendor_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Id"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"expected_amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expected Amount"},"expected_paid_on_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"},{"type":"string"},{"type":"null"}],"title":"Expected Paid On Date"},"amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Amount"},"due_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"},{"type":"string"},{"type":"null"}],"title":"Due On"},"received_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"},{"type":"string"},{"type":"null"}],"title":"Received On"},"s3_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"S3 Key"},"source_inventory_order_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Inventory Order Id"},"payment_method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Method","description":"Payment method override: 'Wire Transfer', 'ACH', 'Check', 'Credit Card', or empty string to clear. Takes precedence over the method inferred from a linked payment transaction."},"recurring":{"anyOf":[{"$ref":"#/components/schemas/RecurringConfig"},{"type":"null"}],"description":"If provided, creates a recurring template from this bill."}},"type":"object","title":"BillUpdateRequest","description":"Schema for updating a bill.","example":{"amount":250000,"description":"Office rent - March","due_on":"2026-03-01","payment_method":"ACH"},"examples":[{"amount":250000,"description":"Office rent - March","due_on":"2026-03-01","payment_method":"ACH"}]},"BillVendorCreditApplicationResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Application record ID"},"vendor_credit_id":{"type":"string","title":"Vendor Credit Id","description":"Source vendor credit ID"},"bill_id":{"type":"string","title":"Bill Id","description":"Bill the credit was applied to"},"amount_applied":{"type":"integer","title":"Amount Applied","description":"Amount applied in cents"},"amount_applied_dollars":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Amount Applied Dollars","description":"Amount applied in dollars"},"applied_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Applied At","description":"When the credit was applied"},"applied_by_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Applied By User Id","description":"User who applied the credit"},"vendor_credit_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Credit Number","description":"Vendor credit number (e.g. VC-0001)"},"journal_entry_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Journal Entry Id","description":"Journal entry posted when the credit was applied to this bill"}},"type":"object","required":["id","vendor_credit_id","bill_id","amount_applied"],"title":"BillVendorCreditApplicationResponse","description":"Vendor credit applied against a bill (embedded on bill detail/list)."},"BillsListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/BillResponse"},"type":"array","title":"Items","description":"List of items"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total","description":"Total number of items (null when not calculated for performance)"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit","description":"Pagination limit"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Cursor for next page"},"prev_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prev Cursor","description":"Cursor for previous page"},"has_next":{"type":"boolean","title":"Has Next","description":"Whether there are more items"},"has_prev":{"type":"boolean","title":"Has Prev","description":"Whether there are previous items"}},"type":"object","required":["items","has_next","has_prev"],"title":"BillsListResponse","description":"Paginated list of bills with cursor-based navigation."},"Body_attach_file_to_bill_api_v1_bills__bill_id__attachment_patch":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_attach_file_to_bill_api_v1_bills__bill_id__attachment_patch"},"Body_upload_bill_file_api_v1_bills_upload_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_upload_bill_file_api_v1_bills_upload_post"},"BulkApproveSuggestionsRequest":{"properties":{"min_confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Min Confidence","description":"Only approve suggestions at or above this confidence","default":0.85}},"type":"object","title":"BulkApproveSuggestionsRequest","description":"Request schema for bulk approving bill payment suggestions."},"BulkApproveSuggestionsResponse":{"properties":{"accepted":{"type":"integer","title":"Accepted","description":"Successfully accepted","default":0},"failed":{"type":"integer","title":"Failed","description":"Failed to accept","default":0},"total":{"type":"integer","title":"Total","description":"Total suggestions processed","default":0}},"type":"object","title":"BulkApproveSuggestionsResponse","description":"Response schema for bulk approval results."},"CompareBillAgainstContractResponse":{"properties":{"bill_id":{"type":"string","title":"Bill Id"},"contract_match":{"type":"string","title":"Contract Match"},"vendor_contract_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Contract Id"}},"additionalProperties":true,"type":"object","required":["bill_id","contract_match"],"title":"CompareBillAgainstContractResponse","description":"Response for ``compare_bill_against_contract``."},"DraftBill":{"properties":{"vendor_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Name","description":"Vendor/company name extracted by AI. Use to match or create a vendor."},"amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Amount","description":"Bill amount in cents extracted by AI."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description of what the bill is for."},"bill_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bill Number","description":"Bill/invoice number from the vendor document."},"bill_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bill Date","description":"Date of the bill (YYYY-MM-DD) extracted by AI."},"expense_category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expense Category","description":"Expense category suggested by AI (e.g., 'Office Supplies', 'Rent')."},"vendor_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Id","description":"Matched vendor UUID (if the vendor was found in the system)."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"Currency code (USD, CAD, AUD, EUR, or GBP). Defaults to USD.","default":"USD"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type","description":"Bill type: 'recurring' or 'one_time'. Defaults to 'one_time'.","default":"one_time"},"received_on":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Received On","description":"Date bill was received (ISO 8601). Defaults to bill_date if available."},"due_on":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Due On","description":"Payment due date (ISO 8601). The extracted invoice due date, or — when the business counts terms from the receipt date — upload day plus payment terms (see ``due_date_policy``)."},"due_date_policy":{"anyOf":[{"$ref":"#/components/schemas/DraftBillDueDatePolicy"},{"type":"null"}],"description":"How ``due_on`` was derived when the business's due-date basis is ``received_date``. Null under the default invoice-date basis."},"s3_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"S3 Key","description":"S3 key of the source document for this bill."},"ledger_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ledger Id","description":"Matched expense ledger UUID (if matched from expense_category)."},"journal_entry_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Journal Entry Date","description":"Date for journal entry (ISO 8601). Defaults to received_on."},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence","description":"AI confidence score for this extraction (0.0-1.0)."},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Source type: 'pasted_text', 'single_file', or 'multi_file'."},"source_filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Filename","description":"Original filename or S3 key of the source document."}},"type":"object","title":"DraftBill","description":"A draft bill entity extracted by AI, ready for user review before creation.\n\nAssumes 'received' status — includes all possible params for creating a bill\nin the received status. Fields are optional since AI extraction may not\npopulate every field.","example":{"amount":15000,"bill_date":"2026-02-10","bill_number":"INV-12345","confidence":0.92,"currency":"USD","description":"Office supplies - paper and toner","due_on":"2026-03-12","expense_category":"Office Supplies","received_on":"2026-02-10","source":"single_file","type":"one_time","vendor_name":"Office Depot"},"examples":[{"amount":15000,"bill_date":"2026-02-10","bill_number":"INV-12345","confidence":0.92,"currency":"USD","description":"Office supplies - paper and toner","due_on":"2026-03-12","expense_category":"Office Supplies","received_on":"2026-02-10","source":"single_file","type":"one_time","vendor_name":"Office Depot"}]},"DraftBillDueDatePolicy":{"properties":{"basis":{"type":"string","enum":["invoice_date","received_date"],"title":"Basis","description":"Business due-date basis that produced ``due_on``."},"anchor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Anchor","description":"Date (YYYY-MM-DD) the payment terms were counted from — the receipt date."},"term_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Term Days","description":"Payment-term length in days that was applied."},"term_source":{"anyOf":[{"type":"string","enum":["vendor_default","invoice_span","business_default"]},{"type":"null"}],"title":"Term Source","description":"Where the term length came from: the matched vendor's default term, the span the invoice itself implies (due date minus invoice date), or the business's default term."},"invoice_due_on":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invoice Due On","description":"Due date as printed on / extracted from the invoice (YYYY-MM-DD), for reference."}},"type":"object","required":["basis"],"title":"DraftBillDueDatePolicy","description":"How a draft bill's ``due_on`` was derived from the business's due-date basis.\n\nPresent only when the business runs payment terms from the receipt date\n(``ap_due_date_basis = received_date``) and a due date was derived; absent\nunder the default invoice-date basis."},"DuplicateBillCheckResponse":{"properties":{"matches":{"items":{"$ref":"#/components/schemas/DuplicateBillMatch"},"type":"array","title":"Matches","description":"Possible duplicates, most recent first. Empty when none found."}},"type":"object","title":"DuplicateBillCheckResponse","description":"Advisory result for the pre-entry duplicate check. Never blocks submit."},"DuplicateBillMatch":{"properties":{"bill_id":{"type":"string","title":"Bill Id"},"bill_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bill Number"},"vendor_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Id"},"vendor_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Name"},"amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Amount","description":"Bill amount in cents (falls back to expected_amount for drafts)."},"status":{"type":"string","title":"Status"},"received_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Received On"},"match_reason":{"type":"string","enum":["bill_number","vendor_amount"],"title":"Match Reason","description":"Why it was flagged: 'bill_number' (same number ignoring case/punctuation) or 'vendor_amount' (same vendor and amount)."},"confidence":{"type":"string","enum":["high","medium"],"title":"Confidence"}},"type":"object","required":["bill_id","status","match_reason","confidence"],"title":"DuplicateBillMatch","description":"A single existing bill flagged as a possible duplicate of a new entry."},"ExpenseCandidateItem":{"properties":{"id":{"type":"string","title":"Id"},"amount":{"type":"integer","title":"Amount"},"unallocated":{"type":"integer","title":"Unallocated"},"date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"counterparty":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Counterparty"},"ledger_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ledger Name"},"currency":{"type":"string","title":"Currency","default":"USD"}},"additionalProperties":true,"type":"object","required":["id","amount","unallocated"],"title":"ExpenseCandidateItem","description":"Outgoing transaction eligible for bill payment linking."},"FileProcessingError":{"properties":{"s3_key":{"type":"string","title":"S3 Key","description":"S3 key of the file that failed."},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename","description":"Original filename (if determinable from the S3 key)."},"error":{"type":"string","title":"Error","description":"Human-readable error description."}},"type":"object","required":["s3_key","error"],"title":"FileProcessingError","description":"Error detail for a file that failed during AI extraction."},"JournalEntryLineItem":{"properties":{"ledger_id":{"type":"string","title":"Ledger Id","description":"UUID of the expense ledger account."},"amount":{"type":"integer","exclusiveMinimum":0.0,"title":"Amount","description":"Amount in cents for this line (must be > 0)."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional description for this line item."}},"type":"object","required":["ledger_id","amount"],"title":"JournalEntryLineItem","description":"A single line item for a split journal entry on bill creation."},"JournalEntryLinkRequest":{"properties":{"journal_entry_id":{"type":"string","title":"Journal Entry Id","description":"UUID of the journal entry to attach."}},"type":"object","required":["journal_entry_id"],"title":"JournalEntryLinkRequest","description":"Link an existing journal entry to a bill or invoice.","example":{"journal_entry_id":"0192a4f0-1b2c-7d3e-8f4a-5b6c7d8e9f22"},"examples":[{"journal_entry_id":"0192a4f0-1b2c-7d3e-8f4a-5b6c7d8e9f22"}]},"ListBillPaymentsResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/BillPaymentResponse"},"type":"array","title":"Items","description":"List of items"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total","description":"Total number of items (null when not calculated for performance)"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit","description":"Pagination limit"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Cursor for next page"},"prev_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prev Cursor","description":"Cursor for previous page"},"has_next":{"type":"boolean","title":"Has Next","description":"Whether there are more items"},"has_prev":{"type":"boolean","title":"Has Prev","description":"Whether there are previous items"}},"additionalProperties":true,"type":"object","required":["items","has_next","has_prev"],"title":"ListBillPaymentsResponse","description":"Response for ``list_bill_payments``."},"ListExpenseCandidatesResponse":{"items":{"$ref":"#/components/schemas/ExpenseCandidateItem"},"type":"array","title":"ListExpenseCandidatesResponse","description":"Response for ``list_expense_candidates`` — bare JSON array."},"PaymentPriorityItem":{"properties":{"bill_id":{"type":"string","title":"Bill Id","description":"Bill ID"},"vendor_name":{"type":"string","title":"Vendor Name","description":"Vendor name"},"amount":{"type":"integer","title":"Amount","description":"Amount in cents"},"due_date":{"type":"string","title":"Due Date","description":"Due date"},"priority_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Priority Score","description":"Priority score 0-1"},"reason":{"type":"string","title":"Reason","description":"Reason for priority ranking"}},"type":"object","required":["bill_id","vendor_name","amount","due_date","priority_score","reason"],"title":"PaymentPriorityItem"},"RecurringConfig":{"properties":{"frequency":{"type":"string","enum":["daily","weekly","biweekly","monthly","quarterly","annually"],"title":"Frequency","description":"How often to generate bills."},"start_date":{"type":"string","format":"date","title":"Start Date","description":"When to start generating bills (first occurrence)."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Name for the recurring template. Defaults to bill description."},"end_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"End Date","description":"Stop generating after this date (null = indefinite). If both end_date and max_occurrences are set, whichever is reached first stops generation."},"day_of_month":{"anyOf":[{"type":"integer","maximum":31.0,"minimum":1.0},{"type":"null"}],"title":"Day Of Month","description":"Day of month (1-31). Only applies to monthly/quarterly/annually frequencies; ignored for daily/weekly/biweekly. If the day doesn't exist in a month (e.g., 31 in February), generates on the last day instead. If omitted, uses the day from start_date."},"day_of_week":{"anyOf":[{"type":"integer","maximum":6.0,"minimum":0.0},{"type":"null"}],"title":"Day Of Week","description":"Day of week (0=Monday, 6=Sunday). Only applies to weekly/biweekly frequencies; ignored for other frequencies. If omitted, uses the weekday from start_date."},"days_until_due":{"type":"integer","maximum":365.0,"minimum":0.0,"title":"Days Until Due","description":"Days from generation until due date.","default":30},"max_occurrences":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Max Occurrences","description":"Stop after generating this many bills (null = unlimited). If both end_date and max_occurrences are set, whichever is reached first stops generation."}},"type":"object","required":["frequency","start_date"],"title":"RecurringConfig","description":"Recurring configuration that can be embedded in bill create/update requests.","example":{"day_of_month":1,"days_until_due":15,"frequency":"monthly","start_date":"2026-02-01"},"examples":[{"day_of_month":1,"days_until_due":15,"frequency":"monthly","start_date":"2026-02-01"}]},"ResolvePendingApprovalRequest":{"properties":{"action":{"type":"string","enum":["approve","reject"],"title":"Action","description":"'approve' posts the bill to 'received'; 'reject' moves it to 'canceled'."},"ledger_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ledger Id","description":"Expense ledger to debit when approving. Required unless the bill carries a persisted multi-account split. Ignored for 'reject'."},"reason":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Reason","description":"Optional reason captured in the audit trail when rejecting."}},"type":"object","required":["action"],"title":"ResolvePendingApprovalRequest","description":"Manually force a stuck ``pending_approval`` bill to a terminal state.\n\nEscape hatch for bills wedged in ``pending_approval`` that no longer have an\nactionable suspended execution to Approve/Reject (run never started, crashed\nbefore suspending, or suspended on a gate with no approvers).","example":{"action":"approve","ledger_id":"0192a4f0-1b2c-7d3e-8f4a-5b6c7d8e9f11"},"examples":[{"action":"approve","ledger_id":"0192a4f0-1b2c-7d3e-8f4a-5b6c7d8e9f11"}]},"SubmitBillForApApprovalResponse":{"properties":{"execution_id":{"type":"string","title":"Execution Id","description":"Started workflow execution UUID"},"bill_id":{"type":"string","title":"Bill Id","description":"Bill UUID submitted for approval"}},"type":"object","required":["execution_id","bill_id"],"title":"SubmitBillForApApprovalResponse","description":"Response when manually routing a bill into the AP approval workflow."},"SuccessEnvelope_BillAICreatePayloadResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/BillAICreatePayloadResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[BillAICreatePayloadResponse]"},"SuccessEnvelope_BillAgingResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/BillAgingResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[BillAgingResponse]"},"SuccessEnvelope_BillBatchPaymentResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/BillBatchPaymentResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[BillBatchPaymentResponse]"},"SuccessEnvelope_BillMetricsResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/BillMetricsResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[BillMetricsResponse]"},"SuccessEnvelope_BillPaymentResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/BillPaymentResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[BillPaymentResponse]"},"SuccessEnvelope_BillPaymentSuggestionRejectResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/BillPaymentSuggestionRejectResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[BillPaymentSuggestionRejectResponse]"},"SuccessEnvelope_BillPaymentSuggestionsListResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/BillPaymentSuggestionsListResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[BillPaymentSuggestionsListResponse]"},"SuccessEnvelope_BillResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/BillResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[BillResponse]"},"SuccessEnvelope_BillsListResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/BillsListResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[BillsListResponse]"},"SuccessEnvelope_BulkApproveSuggestionsResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/BulkApproveSuggestionsResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[BulkApproveSuggestionsResponse]"},"SuccessEnvelope_CompareBillAgainstContractResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/CompareBillAgainstContractResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[CompareBillAgainstContractResponse]"},"SuccessEnvelope_DuplicateBillCheckResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/DuplicateBillCheckResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[DuplicateBillCheckResponse]"},"SuccessEnvelope_ListBillPaymentsResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/ListBillPaymentsResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[ListBillPaymentsResponse]"},"SuccessEnvelope_ListExpenseCandidatesResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/ListExpenseCandidatesResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[ListExpenseCandidatesResponse]"},"SuccessEnvelope_SubmitBillForApApprovalResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/SubmitBillForApApprovalResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[SubmitBillForApApprovalResponse]"},"SuccessEnvelope_SuggestPaymentPriorityResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/SuggestPaymentPriorityResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[SuggestPaymentPriorityResponse]"},"SuccessEnvelope_TriggerBillMatchingResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/TriggerBillMatchingResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[TriggerBillMatchingResponse]"},"SuccessEnvelope_UpcomingBillListResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/UpcomingBillListResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[UpcomingBillListResponse]"},"SuccessEnvelope_UpcomingBillResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/UpcomingBillResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[UpcomingBillResponse]"},"SuccessEnvelope_UploadBillFileResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/UploadBillFileResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[UploadBillFileResponse]"},"SuggestPaymentPriorityResponse":{"properties":{"recommendations":{"items":{"$ref":"#/components/schemas/PaymentPriorityItem"},"type":"array","title":"Recommendations"},"projected_balance":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Projected Balance","description":"Projected balance in cents"}},"type":"object","title":"SuggestPaymentPriorityResponse"},"TriggerBillMatchingRequest":{"properties":{"min_confidence":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Min Confidence","description":"Minimum confidence threshold (0.0–1.0)"},"auto_match":{"type":"boolean","title":"Auto Match","description":"If true, automatically accept high-confidence matches (>= 0.85)","default":false},"bill_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Bill Ids","description":"Limit matching to specific bill UUIDs"}},"type":"object","title":"TriggerBillMatchingRequest","description":"Request schema for triggering bill payment matching."},"TriggerBillMatchingResponse":{"properties":{"suggestions_created":{"type":"integer","title":"Suggestions Created","description":"New suggestions created","default":0},"auto_linked":{"type":"integer","title":"Auto Linked","description":"Auto-accepted high-confidence matches","default":0},"total_candidates":{"type":"integer","title":"Total Candidates","description":"Total candidates evaluated","default":0}},"type":"object","title":"TriggerBillMatchingResponse","description":"Response schema for bill payment matching results."},"UpcomingBillConvertRequest":{"properties":{"amount":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Amount","description":"Actual amount in cents. Defaults to the estimate."},"due_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Due Date","description":"Due date for the bill. Defaults to the expected date."},"bill_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bill Number","description":"Vendor's invoice number, when known."},"s3_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"S3 Key","description":"Attachment key for the received document."}},"type":"object","title":"UpcomingBillConvertRequest","description":"Push an estimate into a real draft bill."},"UpcomingBillCreateRequest":{"properties":{"vendor_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Id","description":"Vendor this is expected from, when one exists."},"vendor_name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Vendor Name","description":"Payee name when there is no vendor record yet."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"What the bill is for."},"estimated_amount":{"type":"integer","minimum":0.0,"title":"Estimated Amount","description":"Estimated amount in cents. An estimate, not a payable."},"expected_date":{"type":"string","format":"date","title":"Expected Date","description":"When the bill is expected (first occurrence for a series)."},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes","description":"Free-form notes."},"recurrence":{"anyOf":[{"$ref":"#/components/schemas/UpcomingBillRecurrence"},{"type":"null"}],"description":"Omit for a single expected bill."}},"type":"object","required":["estimated_amount","expected_date"],"title":"UpcomingBillCreateRequest","description":"Create a one-off expected bill, or a recurring series of them.","example":{"description":"Quarterly liability insurance premium","estimated_amount":180000,"expected_date":"2026-04-01","vendor_id":"0192a4f0-1b2c-7d3e-8f4a-5b6c7d8e9f02"},"examples":[{"description":"Quarterly liability insurance premium","estimated_amount":180000,"expected_date":"2026-04-01","vendor_id":"0192a4f0-1b2c-7d3e-8f4a-5b6c7d8e9f02"}]},"UpcomingBillLinkRequest":{"properties":{"bill_id":{"type":"string","title":"Bill Id","description":"The real bill that satisfies this row."}},"type":"object","required":["bill_id"],"title":"UpcomingBillLinkRequest","description":"Match an expected bill to a bill that already arrived."},"UpcomingBillListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/UpcomingBillResponse"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total","description":"Number of rows returned."},"total_estimated_amount":{"type":"integer","title":"Total Estimated Amount","description":"Sum of estimated_amount over the returned `expected` rows, in cents. A forecast figure — never an AP balance."}},"type":"object","required":["items","total","total_estimated_amount"],"title":"UpcomingBillListResponse","description":"Expected bills within a date horizon.\n\nNot cursor-paginated: the list is bounded by the requested date window and\na hard row cap, and the client sums it for a forecast total, so a partial\npage would be actively misleading."},"UpcomingBillRecurrence":{"properties":{"frequency":{"type":"string","enum":["daily","weekly","biweekly","monthly","quarterly","annually"],"title":"Frequency","description":"How often the bill is expected."},"day_of_week":{"anyOf":[{"type":"integer","maximum":6.0,"minimum":0.0},{"type":"null"}],"title":"Day Of Week","description":"0=Monday … 6=Sunday. Used by weekly/biweekly series to pin the occurrence to a weekday; ignored otherwise."},"day_of_month":{"anyOf":[{"type":"integer","maximum":31.0,"minimum":1.0},{"type":"null"}],"title":"Day Of Month","description":"Day of month for monthly/quarterly/annual series. Clamped to the last day of shorter months."},"end_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"End Date","description":"Stop projecting occurrences after this date."},"occurrences":{"type":"integer","maximum":24.0,"minimum":1.0,"title":"Occurrences","description":"How many occurrences to project (max 24). Projection stops earlier if end_date is reached.","default":12}},"type":"object","required":["frequency"],"title":"UpcomingBillRecurrence","description":"Recurrence for an expected bill, e.g. \"every second Friday\"."},"UpcomingBillResponse":{"properties":{"id":{"type":"string","title":"Id"},"business_id":{"type":"string","title":"Business Id"},"vendor_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Id"},"vendor_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"estimated_amount":{"type":"integer","title":"Estimated Amount","description":"Estimated amount in cents."},"expected_date":{"type":"string","format":"date","title":"Expected Date"},"status":{"type":"string","title":"Status"},"series_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Series Id","description":"Shared by every occurrence generated together."},"frequency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Frequency"},"day_of_week":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Day Of Week"},"day_of_month":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Day Of Month"},"bill_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bill Id","description":"The real bill this became, once converted or matched."},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"},"is_estimate":{"type":"boolean","title":"Is Estimate","description":"Always true. Upcoming bills are forecast rows: they carry no journal entries and are excluded from AP totals, aged payables and the balance sheet.","default":true},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","business_id","estimated_amount","expected_date","status","created_at","updated_at"],"title":"UpcomingBillResponse","description":"A projected bill occurrence."},"UpcomingBillUpdateRequest":{"properties":{"vendor_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Id"},"vendor_name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Vendor Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"estimated_amount":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Estimated Amount"},"expected_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Expected Date"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"},"status":{"anyOf":[{"type":"string","enum":["expected","dismissed"]},{"type":"null"}],"title":"Status","description":"Only expected/dismissed are settable. `converted` is set by the convert endpoint, which is the only path that creates a bill."}},"type":"object","title":"UpcomingBillUpdateRequest","description":"Patch a single projected occurrence.\n\nEdits apply to the one occurrence, not the series: the point of\nmaterialised occurrences is that \"March's contractor invoice will be\nbigger\" is expressible without redefining the schedule."},"UploadBillFileResponse":{"properties":{"s3_key":{"type":"string","title":"S3 Key"}},"additionalProperties":true,"type":"object","required":["s3_key"],"title":"UploadBillFileResponse","description":"Response for ``upload_bill_file``."},"app__core__success__MessageResponse":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"}},"additionalProperties":true,"type":"object","title":"MessageResponse","description":"Envelope for data-less mutations: ``{success, message, code}``, no ``data``.\n\nCanonical ``response_model`` for deletes and other message-only mutations so\nthe generated TypeScript client gets a single, named ``MessageResponse`` type\ninstead of dozens of empty per-route stubs. Pairs with the\n``SuccessResponse.*`` builders (which already emit this exact shape)."},"ErrorResponse":{"title":"ErrorResponse","type":"object","description":"Envelope returned by every non-2xx response. Branch on `code` (stable) rather than `message` (human-readable, may change).","required":["error","message","code"],"properties":{"error":{"type":"string","description":"Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`."},"message":{"type":"string","description":"Human-readable explanation, safe to show to end users."},"code":{"type":"string","description":"Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`)."},"request_id":{"type":"string","description":"Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied."},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"Field-level validation messages keyed by field name. Present on 400/422 validation failures only."}}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}