{"openapi":"3.1.0","info":{"title":"POST /api/v1/ledgers","version":"1.0.0","description":"Create ledger"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/ledgers":{"post":{"tags":["ledgers"],"summary":"Create ledger","description":"Create a new account in the chart of accounts.","operationId":"create_ledger_api_v1_ledgers_post","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/LedgerCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LedgerResponse"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"detail":"Invalid request parameters"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"detail":"Not authenticated"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"detail":"Not enough permissions"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"CashFlowClassEnum":{"type":"string","enum":["cash","ar","inventory","prepaid","other_current_asset","ppe","intangible","other_lt_asset","intercompany_asset","internal_transfer","ap","cc_payable","accrued","other_current_liability","lt_debt","intercompany_liability","equity_contribution","equity_distribution","retained_earnings","revenue","cogs","opex","non_cash_expense","interest_expense","tax_expense"],"title":"CashFlowClassEnum","description":"Indirect-method cash flow classification for ledgers.\n\nEach chart-of-account row carries one of these in addition to its\nbroader ``type``. The indirect cash flow statement is built by\ngrouping period-over-period balance deltas by this column.\nMirrors ``app.models.ledgers.CashFlowClassEnum`` for API surface."},"CashFlowSectionEnum":{"type":"string","enum":["operating","investing","financing","excluded"],"title":"CashFlowSectionEnum","description":"Cash flow statement section classification for ledgers."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LedgerCreateRequest":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name","description":"Ledger name (e.g., 'Operating Cash', 'Sales Revenue')."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"Currency for this account (USD, CAD, AUD, EUR, or GBP). Defaults to business default.","default":"USD"},"editable":{"type":"boolean","title":"Editable","description":"Whether journal entries can be manually posted to this account.","default":true},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type","description":"Account type: asset, liability, equity, revenue, expense. Required in Custom Mode."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional description of the account's purpose."},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Account status: 'active' or 'inactive'. Inactive accounts hidden from dropdowns.","default":"active"},"debit_credit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Debit Credit","description":"Normal balance: 'debit' (assets/expenses) or 'credit' (liabilities/equity/revenue). Required in Custom Mode."},"sort_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sort Code","description":"Sort code for chart ordering (e.g. 1000 for assets, 4000 for revenue). Required in Custom Mode."},"sub_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sub Type","description":"Sub-classification (current_assets, operating_expenses, etc.). Required in Custom Mode."},"report_cash_flow":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Report Cash Flow","description":"Include in cash flow statement. Required in Custom Mode."},"financial_account_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Financial Account Type","description":"Templated Mode: bank_account, credit_card, payments, payroll, loan, prepaid_card, accounts_receivable, accounts_payable."},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Id","description":"UUID of parent ledger for sub-accounts (e.g., 'Operating Expenses' → 'Office Supplies')."},"cfs_class":{"anyOf":[{"$ref":"#/components/schemas/CashFlowClassEnum"},{"type":"null"}],"description":"Indirect-method cash flow classification. Determines which row of the Statement of Cash Flows this account populates. If omitted, the system derives it from `type`/`sub_type`/`financial_account_type` on first save; un-derivable rows must be set explicitly to pass cash-flow validation."}},"type":"object","required":["name"],"title":"LedgerCreateRequest","description":"Request schema for creating a new ledger (chart of accounts entry).\n\nLedgers are the accounts in your chart of accounts (e.g., Cash, Accounts\nReceivable, Revenue). Supports two creation modes:\n\n**Templated Mode** (recommended for standard accounts):\n- Provide `name` and `financial_account_type`\n- Teal auto-configures accounting properties\n\n**Custom Mode** (for specialized accounts):\n- Provide all fields manually for full control\n- Required: name, type, debit_credit, sort_code, sub_type, report_cash_flow","examples":[{"editable":true,"financial_account_type":"bank_account","name":"Chase Business Checking"},{"debit_credit":"debit","editable":true,"name":"Advertising Expense","report_cash_flow":true,"sort_code":"6100","sub_type":"operating_expenses","type":"expense"}]},"LedgerResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Ledger UUID."},"teal_ledger_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Teal Ledger Id","description":"Linked Teal accounting system ID."},"name":{"type":"string","title":"Name","description":"Account name."},"currency":{"type":"string","title":"Currency","description":"Currency for this account (USD, CAD, AUD, EUR, or GBP).","default":"USD"},"type":{"type":"string","title":"Type","description":"Account type: asset, liability, equity, revenue, expense."},"balance":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Balance","description":"Current balance in cents (may be negative)."},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Id","description":"Parent ledger UUID for sub-accounts."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Account description."},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Status: 'active' or 'inactive'."},"debit_credit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Debit Credit","description":"Normal balance: 'debit' or 'credit'."},"sort_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sort Code","description":"Sort code for chart ordering."},"sub_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sub Type","description":"Sub-classification for reporting."},"report_cash_flow":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Report Cash Flow","description":"Whether included in cash flow statement."},"cash_flow_section":{"anyOf":[{"$ref":"#/components/schemas/CashFlowSectionEnum"},{"type":"null"}],"description":"Cash flow statement section: 'operating', 'investing', 'financing', or 'excluded'."},"cfs_class":{"anyOf":[{"$ref":"#/components/schemas/CashFlowClassEnum"},{"type":"null"}],"description":"Indirect-method cash flow classification used to populate the Statement of Cash Flows."},"editable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Editable","description":"Whether journal entries can be manually posted to this account."},"financial_account_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Financial Account Type","description":"Template type if created in Templated Mode."},"is_required":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Required","description":"True for system-required accounts that cannot be deleted."},"system_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Key","description":"Immutable key for system/base ledgers (e.g. 'accounts_receivable'). Null for user-created ledgers."},"teal_account_link_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Teal Account Link Id","description":"UUID of the TealAccountLink if this ledger is connected to a bank/Plaid source account. Null for unlinked ledgers."},"business_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Business Id","description":"Business UUID."},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"Creation timestamp."},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"Last update timestamp."}},"additionalProperties":true,"type":"object","required":["id","name","type"],"title":"LedgerResponse","description":"Response schema for a ledger (chart of accounts entry).\n\nA ledger represents an account in the chart of accounts. Each ledger\nhas a type (asset, liability, etc.), current balance, and configuration\nfor how it affects financial reports.","example":{"balance":1523450,"business_id":"019ab37c-bus1-7000-8000-000000000001","created_at":"2024-01-10T10:30:00Z","debit_credit":"debit","description":"Primary operating account","editable":true,"financial_account_type":"bank_account","id":"019ab37c-led1-7000-8000-000000000001","is_required":false,"name":"Chase Business Checking","report_cash_flow":true,"sort_code":"1010","status":"active","sub_type":"current_assets","teal_ledger_id":"led_abc123","type":"asset","updated_at":"2024-01-15T14:00:00Z"}},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}