{"openapi":"3.1.0","info":{"title":"POST /api/v1/payroll/gusto/reconcile/preview","version":"1.0.0","description":"Preview the Gusto payroll reconciliation"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/payroll/gusto/reconcile/preview":{"post":{"tags":["payroll"],"summary":"Preview the Gusto payroll reconciliation","description":"Reads the Gusto exports given (Payroll Journal / Register, Contractor Payments, Bank Transactions; uploaded via s3_key or pasted), matches them to the Gusto bank rows in the range and returns the plan: per row the new description, counterparty, ledger, the per-employee split of each NET lump, and the accrual bill each TAX / reimbursement debit pays; plus everything left outstanding on either side and a plan_hash for apply. Nothing is changed.","operationId":"gusto_reconcile_preview","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/GustoReconcileRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_GustoReconcilePreviewResponse_"}}}},"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":"gusto_reconcile_preview_api_v1_payroll_gusto_reconcile_preview_post"}}},"components":{"schemas":{"GustoBillLine":{"properties":{"ledger_key":{"type":"string","enum":["wages","taxes","contractors","reimbursements","fees"],"title":"Ledger Key"},"ledger_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ledger Id"},"ledger_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ledger Name"},"amount":{"type":"integer","title":"Amount","description":"Cents"},"description":{"type":"string","title":"Description"}},"type":"object","required":["ledger_key","amount","description"],"title":"GustoBillLine"},"GustoBillPlan":{"properties":{"action":{"type":"string","enum":["create","link_existing"],"title":"Action"},"bill_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bill Id","description":"Existing bill to pay"},"vendor_name":{"type":"string","title":"Vendor Name"},"bill_date":{"type":"string","format":"date","title":"Bill Date"},"due_date":{"type":"string","format":"date","title":"Due Date"},"amount":{"type":"integer","title":"Amount","description":"Cents"},"description":{"type":"string","title":"Description"},"lines":{"items":{"$ref":"#/components/schemas/GustoBillLine"},"type":"array","title":"Lines"}},"type":"object","required":["action","vendor_name","bill_date","due_date","amount","description"],"title":"GustoBillPlan"},"GustoLedgerOverrides":{"properties":{"wages":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Wages","description":"Net pay / wages ledger"},"taxes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Taxes","description":"Employer payroll tax ledger"},"contractors":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contractors","description":"Contractor expense ledger"},"reimbursements":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reimbursements","description":"Employee reimbursement ledger"},"fees":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fees","description":"Gusto subscription fee ledger"}},"type":"object","title":"GustoLedgerOverrides","description":"Book to these ledgers instead of the system payroll ledgers."},"GustoLedgerTarget":{"properties":{"key":{"type":"string","enum":["wages","taxes","contractors","reimbursements","fees"],"title":"Key"},"ledger_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ledger Id"},"ledger_name":{"type":"string","title":"Ledger Name"},"will_create":{"type":"boolean","title":"Will Create","default":false}},"type":"object","required":["key","ledger_name"],"title":"GustoLedgerTarget"},"GustoLinePlan":{"properties":{"transaction_id":{"type":"string","title":"Transaction Id"},"date":{"type":"string","format":"date","title":"Date"},"amount":{"type":"integer","title":"Amount","description":"Bank amount in cents (absolute)"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"counterparty":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Counterparty"},"kind":{"type":"string","enum":["net","tax","contractor_us","contractor_intl","reimbursement","fee","wire","unknown"],"title":"Kind"},"gusto_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gusto Id"},"payee":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payee"},"status":{"type":"string","enum":["matched","categorize_only","unmatched","already_applied"],"title":"Status"},"match_source":{"anyOf":[{"type":"string","enum":["payroll_register","contractor_report","bank_report","description"]},{"type":"null"}],"title":"Match Source"},"pay_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Pay Date"},"period_start":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Period Start"},"period_end":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Period End"},"date_offset_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Date Offset Days","description":"Bank date minus pay/payment date"},"amount_difference":{"type":"integer","title":"Amount Difference","description":"Bank amount minus matched report total (cents)","default":0},"new_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"New Description"},"new_counterparty":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"New Counterparty"},"ledger_key":{"anyOf":[{"type":"string","enum":["wages","taxes","contractors","reimbursements","fees"]},{"type":"null"}],"title":"Ledger Key"},"ledger_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ledger Id"},"ledger_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ledger Name"},"split":{"items":{"$ref":"#/components/schemas/GustoSplitLeg"},"type":"array","title":"Split"},"bill":{"anyOf":[{"$ref":"#/components/schemas/GustoBillPlan"},{"type":"null"}]},"notes":{"items":{"type":"string"},"type":"array","title":"Notes"}},"type":"object","required":["transaction_id","date","amount","description","counterparty","kind","status"],"title":"GustoLinePlan","description":"What the reconciliation does to one Gusto bank row."},"GustoOutstandingItem":{"properties":{"source":{"type":"string","enum":["payroll_register","contractor_report","bank_report","ledger"],"title":"Source"},"kind":{"type":"string","enum":["net","tax","contractor_us","contractor_intl","reimbursement","fee","wire","unknown"],"title":"Kind"},"date":{"type":"string","format":"date","title":"Date"},"amount":{"type":"integer","title":"Amount","description":"Cents"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"transaction_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Transaction Id"},"reason":{"type":"string","title":"Reason"}},"type":"object","required":["source","kind","date","amount","reason"],"title":"GustoOutstandingItem","description":"Something on one side with nothing on the other."},"GustoReconcilePreviewResponse":{"properties":{"start_date":{"type":"string","format":"date","title":"Start Date"},"end_date":{"type":"string","format":"date","title":"End Date"},"bank_ledger_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bank Ledger Id"},"reports":{"items":{"$ref":"#/components/schemas/GustoReportSummary"},"type":"array","title":"Reports"},"ledgers":{"items":{"$ref":"#/components/schemas/GustoLedgerTarget"},"type":"array","title":"Ledgers"},"lines":{"items":{"$ref":"#/components/schemas/GustoLinePlan"},"type":"array","title":"Lines"},"outstanding":{"items":{"$ref":"#/components/schemas/GustoOutstandingItem"},"type":"array","title":"Outstanding"},"counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Counts","description":"Rows per status (matched, categorize_only, unmatched, already_applied) plus outstanding."},"plan_hash":{"type":"string","title":"Plan Hash","description":"Pass to apply to refuse a plan that changed since."}},"type":"object","required":["start_date","end_date","plan_hash"],"title":"GustoReconcilePreviewResponse"},"GustoReconcileRequest":{"properties":{"reports":{"items":{"$ref":"#/components/schemas/GustoReportInput"},"type":"array","maxItems":10,"title":"Reports","description":"Gusto exports: Payroll Journal (or Payroll Register), Contractor Payments and/or Bank Transactions. Without any, only the bank lines' own descriptors are used (contractor payee, fee)."},"bank_ledger_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bank Ledger Id","description":"Bank account Gusto debits. Omit to consider every bank account of the business."},"start_date":{"type":"string","format":"date","title":"Start Date","description":"First bank date considered"},"end_date":{"type":"string","format":"date","title":"End Date","description":"Last bank date considered"},"ledger_overrides":{"anyOf":[{"$ref":"#/components/schemas/GustoLedgerOverrides"},{"type":"null"}]},"amount_tolerance_cents":{"type":"integer","maximum":500.0,"minimum":0.0,"title":"Amount Tolerance Cents","description":"Largest difference accepted between a payroll lump and the register total; the difference becomes a rounding leg.","default":0},"create_bills":{"type":"boolean","title":"Create Bills","description":"Book tax and reimbursement debits as an accrual bill per pay period (vendor Gusto) paid by the bank row. False categorizes them directly instead.","default":true}},"type":"object","required":["start_date","end_date"],"title":"GustoReconcileRequest","description":"Inputs for a Gusto reconciliation preview."},"GustoReportInput":{"properties":{"s3_key":{"anyOf":[{"type":"string","maxLength":1024},{"type":"null"}],"title":"S3 Key","description":"S3 key from POST /uploads (or generate_upload_url) of a CSV/XLSX exported from Gusto > Reports."},"content":{"anyOf":[{"type":"string","maxLength":2000000},{"type":"null"}],"title":"Content","description":"The report pasted as CSV / tab-separated text."},"filename":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Filename","description":"Original file name (format hint)."}},"type":"object","title":"GustoReportInput","description":"One Gusto export: an uploaded file (``s3_key``) or pasted CSV text."},"GustoReportSummary":{"properties":{"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename"},"kind":{"type":"string","enum":["payroll_register","contractor_payments","bank_transactions"],"title":"Kind"},"rows_read":{"type":"integer","title":"Rows Read"},"rows_skipped":{"type":"integer","title":"Rows Skipped"},"payroll_runs":{"type":"integer","title":"Payroll Runs","default":0},"contractor_payments":{"type":"integer","title":"Contractor Payments","default":0},"debits":{"type":"integer","title":"Debits","default":0}},"type":"object","required":["kind","rows_read","rows_skipped"],"title":"GustoReportSummary"},"GustoSplitLeg":{"properties":{"employee":{"type":"string","title":"Employee"},"amount":{"type":"integer","title":"Amount","description":"Cents"},"ledger_key":{"type":"string","enum":["wages","taxes","contractors","reimbursements","fees"],"title":"Ledger Key"},"ledger_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ledger Id"},"ledger_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ledger Name"},"counterparty_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Counterparty Name"},"description":{"type":"string","title":"Description"}},"type":"object","required":["employee","amount","ledger_key","description"],"title":"GustoSplitLeg"},"SuccessEnvelope_GustoReconcilePreviewResponse_":{"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/GustoReconcilePreviewResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[GustoReconcilePreviewResponse]"},"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":[]}]}