{"openapi":"3.1.0","info":{"title":"POST /api/v1/payroll/gusto/reconcile/apply","version":"1.0.0","description":"Apply the Gusto payroll reconciliation"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/payroll/gusto/reconcile/apply":{"post":{"tags":["payroll"],"summary":"Apply the Gusto payroll reconciliation","description":"Recomputes the preview's plan from the same inputs and applies it: splits each NET lump one leg per employee (each leg names the employee), creates the per-pay-period Gusto bills for tax and reimbursement debits and pays them with the bank rows (or pays an open Gusto bill of the same amount), renames and categorizes contractor and fee rows, and saves the register as pay runs. Each row is applied on its own; failures are listed. Rows already applied are skipped, so repeating the call is safe. Pass plan_hash from the preview to refuse a plan that changed since.","operationId":"gusto_reconcile_apply","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/GustoApplyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_GustoReconcileApplyResponse_"}}}},"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_apply_api_v1_payroll_gusto_reconcile_apply_post"}}},"components":{"schemas":{"GustoApplyFailure":{"properties":{"transaction_id":{"type":"string","title":"Transaction Id"},"error":{"type":"string","title":"Error"}},"type":"object","required":["transaction_id","error"],"title":"GustoApplyFailure"},"GustoApplyRequest":{"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},"plan_hash":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Plan Hash","description":"plan_hash from the preview. When given, apply refuses if the plan it computes now differs (books changed since the preview)."},"transaction_ids":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":2000},{"type":"null"}],"title":"Transaction Ids","description":"Apply only these bank rows of the plan (default: all)."}},"type":"object","required":["start_date","end_date"],"title":"GustoApplyRequest","description":"Inputs for applying the plan; the same inputs as the preview."},"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."},"GustoReconcileApplyResponse":{"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."},"transactions_updated":{"type":"integer","title":"Transactions Updated","default":0},"splits_written":{"type":"integer","title":"Splits Written","default":0},"bills_created":{"type":"integer","title":"Bills Created","default":0},"bills_paid":{"type":"integer","title":"Bills Paid","default":0},"employees_created":{"type":"integer","title":"Employees Created","default":0},"pay_runs_saved":{"type":"integer","title":"Pay Runs Saved","default":0},"failures":{"items":{"$ref":"#/components/schemas/GustoApplyFailure"},"type":"array","title":"Failures"}},"type":"object","required":["start_date","end_date","plan_hash"],"title":"GustoReconcileApplyResponse"},"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_GustoReconcileApplyResponse_":{"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/GustoReconcileApplyResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[GustoReconcileApplyResponse]"},"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":[]}]}