Jaz API Skill

You are working with the Jaz REST API, the accounting platform backend. Also fully compatible with Juan Accounting (same API, same endpoints).

Prefer the configured OAuth connection. Local CLI/MCP shares clio auth login; hosted MCP uses its host's sign-in. Select the organization explicitly. For a direct integration, follow the repository's OAuth sign-in reference; the API-key header examples below describe the optional key-based route. Never copy a host's tokens into another application.

Pick the right invocation path first

• Running inside an MCP host (Claude Desktop, Cowork): use the MCP tools (execute_tool with create_invoice, list_bills, etc.). Do not write direct HTTP. The MCP server handles auth, retries, and field shape for you.
• Running Claude Code with the `jaz-clio` CLI: use the CLI commands (clio invoices list --json, etc.). Same code path, structured output.
• No agent surface, raw integration: write HTTP calls per the endpoints catalog below.

The rest of this skill (field names, gotchas, error catalog, dependency order, search filter syntax) applies regardless of invocation path. Read it for context, not for HTTP-call construction unless you're in the third bucket.

Reading Order

Core fundamentals (read first, every integration): Identifiers & Dates 1 to 3; Names & Fields 9 to 13; Transaction Creation 14 to 16; Chart of Accounts 17 to 22; Payments / Cross-Currency 4 to 8; Journals & Cash 23 to 26; Credit Notes & Refunds 27 to 28; Reports 36 to 37; Tax Profile Scoping 100; Transaction References 104; Draft Finalization Pipeline 81 to 88; Jaz Magic / PDF-JPG 57 to 63; Currency Rates 39, 49, 105; Withholding Tax 45, 98.

Integration depth (API clients, pipelines, batch jobs, MCP/CLI): Bulk Upsert (Items/Contacts/Rates); Background Jobs (filter resourceId not jobId); Export Records; Pagination (38); Search & Filter (50 to 56); Response Shape Gotchas (66 to 73); Cash Entry Response Shape (74 to 77); Entity Resolution (78 to 80); Bank Rules (89 to 90d); Fixed Assets (91 to 92c); Subscriptions & Scheduled (93 to 94); niche endpoints (95 to 102); Journals balance (103); Quick Fix (107, 111); TTB (108); Dynamic Strings (109 to 110); Sub-Resource Shapes (112); Nano-Classifier (113); Scheduler Asymmetry (114); Payment Record CRUD (115 to 117); Bulk Upserts transactions (118 to 122); Reconciliation write-side (123 to 127); Drafts lifecycle (128 to 135); Orders: Sale Quotes / Sale Orders / Purchase Requests / Purchase Orders (references/orders.md); Claims: records / lifecycle / bulk + conversion + payouts + Employees + Claim Settings (references/claims.md); Report templates and packs (161, references/report-templates.md).

When to Use This Skill

• Writing or modifying any code that calls the Jaz API
• Building API clients, integrations, or data pipelines
• Debugging API errors (422, 400, 404, 500)
• Adding support for new Jaz API endpoints
• Reviewing code that constructs Jaz API request payloads

Quick Reference

Base URL: https://api.getjaz.com Auth: x-jk-api-key: <key> header on every request; key has jk- prefix (e.g., jk-a1b2c3...). NOT Authorization: Bearer or x-api-key. Content-Type: application/json for all POST/PUT/PATCH (except multipart endpoints: createBusinessTransactionFromAttachment FILE mode, importBankStatementFromAttachment, and attachment uploads) All paths are prefixed: /api/v1/ (e.g., https://api.getjaz.com/api/v1/invoices)

Critical Rules

Identifiers & Dates

1. All IDs are `resourceId`, never id. References use <resource>ResourceId suffix.
2. All transaction dates are `valueDate`, not issueDate, invoiceDate, date. This is an accounting term meaning "date of economic effect."
3. All dates are `YYYY-MM-DD` strings; ISO datetime and epoch ms are rejected.

Payments (Cross-Currency Aware)

1. Payment amounts have two fields: paymentAmount = bank account currency (actual cash moved), transactionAmount = transaction document currency (invoice/bill/credit note: amount applied to balance). For same-currency, both are equal. For FX (e.g., USD invoice paid from SGD bank at 1.35): paymentAmount: 1350 (SGD), transactionAmount: 1000 (USD).
2. Payment date is `valueDate`, not paymentDate, not date.
3. Payment bank account is `accountResourceId`, not bankAccountResourceId.
4. Payments require 6 fields: paymentAmount, transactionAmount, accountResourceId, paymentMethod, reference, valueDate.
5. Payments wrapped in `{ payments: [...] }`, array recommended. Flat objects are now auto-wrapped by the API, but array format is preferred for clarity.

Names & Fields

1. Line item descriptions use `name`, not description.
2. Item names: canonical field is internalName, but name alias is accepted on POST. GET responses return both internalName and name.
3. Tag names: canonical field is tagName, but name alias is accepted on POST. GET responses return both tagName and name.
4. Custom field names: POST uses name, GET returns both customFieldName and name.
5. Invoice/bill number is `reference`, not referenceNumber.

Transaction Creation

1. `saveAsDraft` has OPPOSITE defaults on the two surfaces. Raw REST: omitting it creates a FINALIZED transaction (false). MCP/CLI tools: creates for invoices, bills, both credit notes, journals, sale quotes, purchase requests/orders, and the order-conversions inject true: omitting it creates a DRAFT; pass saveAsDraft: false to post immediately. When the landing state matters, pass the field explicitly and read status off the create response rather than assuming either default. Cash entries and cash transfers are the exception on both surfaces: they have no draft state, so saveAsDraft: true is refused with a 422 and the tools do not offer the field at all.
2. If `saveAsDraft: false` (or omitted on the raw REST surface; see Rule 14), every lineItem MUST have accountResourceId.
3. Phones MUST be E.164: +65XXXXXXXX (SG), +63XXXXXXXXXX (PH). No spaces.

Chart of Accounts

1. Tax profiles pre-exist; NEVER create them. Only GET and map.
2. Bank accounts are CoA entries with accountType: "Bank Accounts". A convenience endpoint GET /bank-accounts exists but returns a flat array [{...}], NOT the standard paginated { data, totalElements, totalPages } shape. Normalize before use.
3. CoA bulk-upsert wrapper is `accounts`, not chartOfAccounts.
4. CoA POST uses `currency`, not currencyCode. (Asymmetry: GET returns currencyCode.)
5. CoA POST uses `classificationType`; GET returns accountType. Same values. Both accept all 23 types: Bank Accounts, Cash, Current Asset, Non-current Asset, Fixed Asset, Inventory, Investment, Goodwill, Current Liability, Non-current Liability, Shareholders Equity, Operating Revenue, Other Revenue, Discontinued Income, Financing Income, Investing Income, Direct Costs, Operating Expense, Other Expense, Finance Cost, Investing Expense, Income Tax Expense, Discontinued Expense (nine of these are the IFRS 18 set added 2026-05, listed in rule 140). COGS is Direct Costs, never Operating Expense; "Cost of Goods Sold" is the default account NAME, not a type. Values are singular: a plural or invented value returns zero rows with no error, and search_accounts does not normalise (only create_account does). The set is GLOBAL (same for every org); confirm against the platform with list_account_classifications using limit: 100; its default page is 20 and there are 23.
6. CoA code mapping: match by NAME, not code; pre-existing accounts may have different codes. Resource IDs are the universal identifier.

Bulk Upsert (Items, Contacts & Rates)

• Items bulk-upsert (POST /items/bulk-upsert): max 500 per call. Provide resourceId per item to update (partial: only changed fields needed, server preserves existing values). Omit resourceId to create (defaults: status=ACTIVE, itemCategory=NON_INVENTORY). Response: { resourceId: null, resourceIds: [...] }. SYNC: returns resourceIds immediately.
• Contacts bulk-upsert (POST /contacts/bulk-upsert): max 500 per call. Provide resourceId to update (partial), omit to create. billingName required for create. ASYNC: returns { jobId, status: "QUEUED", totalRecords }. Poll search_background_jobs with filter: {resourceId:{eq:jobId}} until status is SUCCESS, FAILED, or PARTIAL_SUCCESS. Unlike items, contacts bulk-upsert is asynchronous.
• Rates bulk-upsert (POST /organization/currencies/rates/bulk-upsert): max 500 per call. Requires rateDirection per rate (FUNCTIONAL_TO_SOURCE or SOURCE_TO_FUNCTIONAL). Auto-enables currencies not yet enabled in the org; no need to call add_currency first. Response: { resourceId: null, resourceIds: [...] }.

Background Jobs (Universal Async Tracking)

• ANY operation that returns a `jobId` can be polled via search_background_jobs. This includes: contacts bulk-upsert (UPSERT_CONTACTS), items bulk-upsert (UPSERT_ITEMS), bank statement import (PROCESS_BANK_STATEMENT_FILES), and magic processing (MAGIC_TRANSACTION_*).
• 🚨 CRITICAL: Filter by `resourceId`, NOT `jobId`; filter: {jobId:{eq:...}} is silently ignored (returns ALL jobs). Must use filter: {resourceId:{eq:theJobId}}. The response field is named jobId but the filter path is resourceId.
• Poll until terminal status: SUCCESS, FAILED, or PARTIAL_SUCCESS. Use processedCount, failedCount, totalRecords for progress. PARTIAL_SUCCESS means some records succeeded and some failed; check errorDetails array for per-record errors.
• `startedAt` filter does NOT work; use createdAt for date range filtering.
• `errorDetails` is `[]` (empty array) on success, not null.
• Known jobTypes: UPSERT_CONTACTS, UPSERT_ITEMS, PROCESS_BANK_STATEMENT_FILES, MAGIC_TRANSACTION_PURCHASE, MAGIC_TRANSACTION_SALE, MAGIC_TRANSACTION_SALE_CREDIT_NOTE.

Export Records

• `outputFormat: "XLSX"` is always required; no other format is currently supported. Hardcode it.
• `query` + `filter` are mutually exclusive; the server returns INVALID_SEARCH_INPUT if both are provided. Pass query (structured search string, same syntax as dashboard) OR filter (raw JSON filter object), never both.
• Available entity types: INVOICE, BILL, CUSTOMER_CREDIT_NOTE, SUPPLIER_CREDIT_NOTE, SALE_PAYMENT, PURCHASE_PAYMENT, BATCH_PAYMENT, CONTACT, ITEM, CAPSULE, SCHEDULED_TRANSACTION, JOURNAL, BANK_RECORD, CASHFLOW_TRANSACTION, FIXED_ASSET, CHART_OF_ACCOUNT, TAX_PROFILE.
• `fileUrl` expires in ~5 minutes; it's a pre-signed S3 URL. Warn the user to download immediately.
• Preview first: use preview_export_records to confirm scope (count + sample rows) before calling export_records. The filterDescription field gives a human-readable summary like "2580 records | Status in: UNPAID".
• Column customization: use get_export_columns to discover available column paths and headers. Pass a columns array to select specific fields. Omit for default columns.
• `previewRows` keys are column headers, not field paths. E.g. {"Invoice Ref #": "INV-001", "Customer": "Acme"}. Use resolvedColumns to map headers back to paths.

Journals & Cash

1. Journals use `journalEntries` with amount + type: "DEBIT"|"CREDIT", NOT debit/credit number fields.
2. Journals support multi-currency via `currency` object, same format as invoices/bills: "currency": { "sourceCurrency": "USD" } (auto-fetch platform rate) or "currency": { "sourceCurrency": "USD", "exchangeRate": 0.74 } (custom rate). Must be enabled for the org. Omit for base currency. Direction: exchangeRate is functionalToSource (1 org-base unit = N sourceCurrency), usually the inverse of a quoted rate. Pass your figure as-is with rateDirection rather than inverting by hand; Rule 49. Three restrictions apply to foreign currency journals: (a) no controlled accounts: accounts with controlFlag (AR, AP) are off-limits (use invoices/bills instead), (b) no FX accounts: FX Unrealized Gain/Loss/Rounding are system-managed, (c) bank accounts must match: can only post to bank accounts in the same currency as the journal (e.g., USD journal → USD bank account only, not SGD bank account). All other non-controlled accounts (expenses, revenue, assets, liabilities) are available.
3. `currency` object is the SAME everywhere: invoices, bills, credit notes, AND journals all use currency: { sourceCurrency: "USD", exchangeRate?: number, rateDirection?: "FUNCTIONAL_TO_SOURCE" | "SOURCE_TO_FUNCTIONAL" }. Direction: exchangeRate is functionalToSource (1 org-base unit = N sourceCurrency), usually the inverse of a quoted rate. Pass your figure as-is with rateDirection rather than inverting by hand; Rule 49. Never use currencyCode: "USD" (silently ignored on invoices/bills) or currency: "USD" (string, causes 400 on invoices/bills).
4. Cash entries use `accountResourceId` at top level for the BANK account + lines array for offsets.

Credit Notes & Refunds

1. Credit note application wraps in `credits` array with amountApplied, not flat.
2. CN refunds use the same Payment shape as invoice/bill payments: paymentAmount, transactionAmount, accountResourceId, paymentMethod, valueDate, reference. The API also accepts aliases refundAmount/refundMethod (see Rule 53) but prefer canonical paymentAmount/paymentMethod for consistency.

Inventory Items

1. Inventory items (POST /inventory-items, verified live 2026-09-02): required are itemCode, name, unit (e.g. "pcs"; a blank unit returns ITEM_UNIT_EMPTY_ERROR), costingMethod ("FIXED" or "WAC"), cogsResourceId and blockInsufficientDeductions (send false explicitly; omitting it 422s, it is not defaulted server-side). Send name: the endpoint declares no name property and marks internalName required, but the API populates internalName from the name you send. The two account links are TYPE-constrained and the errors name the type: cogsResourceId must be Direct Costs (INVALID_ACCOUNT_TYPE_DIRECT_COST), purchaseAccountResourceId must be Inventory (INVALID_ACCOUNT_TYPE_INVENTORY); an inventory purchase debits the asset, and COGS is recognised on sale. The API reports purchaseAccountResourceId, saleAccountResourceId, appliesToSale and appliesToPurchase as "required if [cogsResourceId] is present", but cogsResourceId is itself always required, so all four are unconditional too. appliesToSale and appliesToPurchase must both be `true`, not merely present: false returns APPLIES_TO_SALE_ERROR / APPLIES_TO_PURCHASE_ERROR ("must be true when cogs selected"), so an inventory-tracked item with COGS is necessarily both sale- and purchase-applicable. There is no inventoryAccountResourceId; it appears in no request schema and a create succeeds without it.
2. Delete inventory items via `DELETE /items/:id`, not /inventory-items/:id.

Cash Transfers

1. Cash transfers use `cashOut`/`cashIn` sub-objects, NOT flat fromAccountResourceId/toAccountResourceId. Each: { accountResourceId, amount }.

Schedulers

1. Scheduled invoices/bills wrap in `{ invoice: {...} }` or `{ bill: {...} }`, not flat. Recurrence field is repeat (NOT frequency/interval). saveAsDraft: false required. `reference` is required inside the invoice/bill wrapper; omitting it causes 422.
2. Scheduled journals use FLAT structure with schedulerEntries, not nested in journal wrapper. `valueDate` is required at the top level (alongside startDate, repeat, etc.).

Bookmarks

1. Bookmarks use `items` array wrapper with name, value, categoryCode, datatypeCode.

Custom Fields

1. Custom fields: `appliesTo` WORKS and `type` does nothing (re-probed live 2026-09-02, reversing the previous entry). Send appliesTo as an OBJECT: {invoices, bills, customerCredits, supplierCredits, payments} sets the matching applyTo* to SHOW; omit it and the field appears on nothing. The old "do not send appliesTo" note came from an ARRAY example, which does 400. format is the ONLY control over the kind of field and the datatype is derived, not chosen: CUSTOM (default) yields datatypeCode: TEXT, any ALL_* value (ALL_CUSTOMERS/ALL_SUPPLIERS/ALL_CONTACTS/ALL_EMPLOYEES/ALL_USERS) yields LIST, a picklist of that population. There is no NUMBER, DATE or DROPDOWN custom field: type, fieldType, entityType, datatypeCode and options all return 200 and are silently dropped (an int on datatypeCode also returns 200, so the DTO does not declare it). printOnDocuments is required and not defaulted server-side.

35a. Custom field values on transactions: Set via customFields: [{ customFieldName: "PO Number", actualValue: "PO-123" }] on invoice/bill/customer-CN/supplier-CN/payment/item/fixed-asset create/update. NOT on journals, cash entries, or cash transfers. Read from GET responses in the same shape. 35b. Custom field search: POST /custom-fields/search with filter/sort/limit/offset. Filter by customFieldName (StringExpression), datatypeCode (StringExpression: TEXT, LIST, DATE; there is no DROPDOWN; see rule 35). 35c. Custom field GET: GET /custom-fields/:resourceId returns full definition including applyToSales, applyToPurchase, applyToCreditNote, applyToPayment, printOnDocuments, listOptions.

Tags on Transactions

35d. Tags are `tags: string[]` on ALL transaction create/update: invoices, bills, customer CNs, supplier CNs, journals, cash-in, cash-out, cash transfers. CLI uses --tag <name> (singular, wrapped to array). API accepts the array directly.

Nano Classifiers

35e. ClassifierConfig on line items: classifierConfig: [{ resourceId: "<capsuleTypeId>", type: "invoice"|"bill", selectedClasses: [{ className: "Class A", resourceId: "<classId>" }], printable: true }]. Applies to line items on invoices, bills, credit notes, journal entries, and cash entry details. Create capsule types first via POST /capsule-types, then reference them in classifierConfig. A selected class needs resourceId unless it sends entityResourceId instead (a classifier whose options are customers, suppliers, contacts, employees or users). Quick fix and Ledger Find & Fix add { resourceId, deleted: true } to remove one classifier and leave unnamed ones as they are (rule 107).

Reports

1. Report field names differ by type; this is the most error-prone area:

1. Ledger highlights is a simple GET: GET /api/v1/ledger/highlights returns org-wide GL summary metadata: transaction counts by type, date range, active accounts/currencies, cross-currency flag, and dynamic FX types. No parameters. Response dates are epoch ms (see Rule 52).

37a. Data exports use simpler field names: P&L export uses startDate/endDate (NOT primarySnapshotDate). AR/AP export uses endDate.

Pagination

1. All list/search endpoints use `limit`/`offset` pagination: NOT page/size. `offset` is a 0-indexed PAGE NUMBER, not a row-skip (offset=1 = second page of limit rows). Exceptions, where `offset` is a 0-indexed ROW offset (next page = offset + limit): POST /generate-reports/general-ledger and templated-general-ledger, the AR/AP details reports (ar-details-report, ap-details-report, templated-ar-details-report, templated-ap-details-report), /purchase-items (list and search), GET /organization/currencies/{code}/rates, and POST /employees/payouts/search. Paging one of these by page number re-reads overlapping rows and skips the rest. Default limit=100, offset=0. Max limit=1000, max offset=65536. page/size params are silently ignored. Response shape: { totalPages, totalElements, truncated, data: [...] }. When truncated: true, a _meta: { fetchedRows, maxRows } field explains why (offset cap or --max-rows soft cap: default 10,000). Use --max-rows <n> to override. Always check truncated before assuming the full dataset was returned. Payload tier (`view`): page-then-drill: search_* and the lean list_* tools (invoices, bills, contacts, items, journals, customer/supplier credit notes, sale/purchase orders) return a compact summary row by default (view:"lean": id + reference/status/date/contact/amount). Search lean to FIND a record, then read it in full via its get_*; pass view:"full" only when you need whole rows up front (heavier: avoid for broad searches). Other collections always return full. CLI defaults to full; use --view lean.

Other

1. Currency rates use `/organization/currencies/:code/rates`: enable currencies first via POST /organization/currencies, then set rates via POST /organization/currencies/:code/rates with body { "rate": 0.74, "rateApplicableFrom": "YYYY-MM-DD" } (see Rule 49 for direction). The older hyphenated /organization-currencies/... rate paths still resolve but are superseded: treat the nested form as the only supported path. The reference is migrating away from the hyphenated form, so do not rely on it being documented. Cannot set rates for org base currency. Full CRUD: POST (create), GET (list), GET/:id, PUT/:id, DELETE/:id.
2. FX invoices/bills MUST use `currency` object; currencyCode: "USD" (string) is silently ignored (transaction created in base currency!). Use currency: { sourceCurrency: "USD" } to auto-fetch platform rate (ECB/FRANKFURTER), or currency: { sourceCurrency: "USD", exchangeRate: 0.74 } for a custom rate. Rate hierarchy: org rate → platform/ECB → transaction-level. Direction: exchangeRate is functionalToSource (1 org-base unit = N sourceCurrency), usually the inverse of a quoted rate. Pass your figure as-is with rateDirection rather than inverting by hand; Rule 49.
3. Invoice GET uses `organizationAccountResourceId` for line item accounts; POST uses accountResourceId. Request-side aliases resolve issueDate → valueDate, bankAccountResourceId → accountResourceId, etc.
4. Scheduler GET returns `interval`; POST uses repeat. (Response-side asymmetry remains.)
5. Search sort is an object: { sort: { sortBy: ["valueDate"], order: "DESC" } }. Required when offset is present (even offset: 0).
6. Bank records. Create: Multipart CSV/OFX via POST /magic/importBankStatementFromAttachment or JSON via POST /bank-records/:accountResourceId with { records: [{amount, transactionDate, description?, payerOrPayee?, reference?}] } (positive = cash-in, negative = cash-out, response: {data: {errors: []}}). Search: POST /bank-records/:accountResourceId/search; filter fields: valueDate (DateExpression), status (StringExpression: UNRECONCILED, RECONCILED, ARCHIVED, POSSIBLE_DUPLICATE), description, extContactName (payer/payee), extReference, netAmount (BigDecimalExpression), extAccountNumber. Sort by valueDate DESC default.
7. Withholding tax (PH) has two sides. Expanded withholding (EWT) on what you pay sits on each bill / supplier credit note line as withholdingTax: copy code, rate, type and description from one list_withholding_codes row (a field left out is not stored, measured 2026-10-06). Creditable withholding (CWT) a customer deducts is recorded from the customer's BIR Form 2307 with record_withholding_tax_certificate, never on the invoice lines (rule 98). On WITHHOLDING_CODE_NOT_FOUND, check the code against list_withholding_codes (codes contain a space: WC 158); never strip the field silently, because the tax disappears from the bill.
8. Known API bugs (500s): none on this list today. Capsules POST, catalogs POST, inventory balances by status GET, contact groups PUT and custom fields PUT are NO LONGER on this list. Capsules POST creates the capsule and returns its resourceId. Catalogs POST returned 201 on a live probe 2026-09-23 (item unit omitted, it is optional); its response is counts (createdCatalogs, createdCatalogItems), not a resourceId, so find the new catalog with search_catalogs. Inventory balances by status works (Rule 97). Contact groups PUT and custom fields PUT were re-probed live 2026-09-02 and returned 200 and applied the change. Do not route around any of them.
9. Non-existent endpoints: POST /inventory/adjustments (and /inventory-adjustments, /inventory-items/:id/adjustments, /items/:id/inventory-adjustments; no stock-adjustment write path exists at any spelling), GET /payments (list), and POST /payments/search return 404; these endpoints are not implemented. For payments, per-payment CRUD is GET/PUT/DELETE /payments/:resourceId and there ARE two payment-scoped searches; see Rule 64. POST /deposits also 404s, but for a different reason, see Rule 47a; do not read it as a missing feature.

47a. Deposits are not an entity; the 404 on `/deposits` is by design. A deposit is a flag on a Chart of Accounts account, not a document: the account carries depositContactType = CUSTOMER (advance received, a liability) or SUPPLIER (advance paid, an asset). Once flagged, a deposit movement is an ordinary transaction against that account: top up with POST /journals / POST /cash-in-entries / POST /cash-out-entries (one leg on the flagged account), draw down with POST /invoices/:id/payments or POST /bills/:id/payments passing accountResourceId = the flagged account and `paymentMethod` set to something other than BANK_TRANSFER / CASH / CHEQUE (use OTHER; those three force a bank/cash account and 422 here, see Rule 80), read with POST /cashflow-transactions/search. Flagging the account is a web-app action: depositContactType is on no chart-of-accounts request or response model here, and the platform-backend mutation that sets it (configureDepositAccounts) is not proxied, so POST /chart-of-accounts cannot create a deposit account. Over the API you can only read and post against an account someone already flagged. Full walkthrough: references/endpoints.md → Deposits.

1. Attachments (full CRUD): Add: POST /:type/:id/attachments (multipart, file field, application/pdf or image/*, NOT text/plain). List: GET /:type/:id/attachments. Delete: DELETE /:type/:id/attachments/:attachmentResourceId (HTTP 200). CLI: clio attachments add --file <path> or --url <url>, clio attachments list, clio attachments delete <attachmentResourceId>. The list response shape depends on the entity. Measured raw 2026-09-07: /invoices/:id/attachments returns { reference, resourceId, attachments: [{fileName, fileType, fileId, attachmentResourceId}] }, while /bills/:id/attachments and /journals/:id/attachments return the conventional { data: [...] }. Both credit-note types were unmeasured (every sampled record was void; see below). listAttachments in core/api/attachments.ts reads either key, so through the CLI or a tool you get .data in all cases; only a raw request sees the split. The attachment ID field is attachmentResourceId (not resourceId). A VOIDED record 404s on three of the five types. Measured 2026-09-07: a voided invoice, customer credit note and supplier credit note each answer 404 not_found with "<Entity> is voided", while a voided bill and a voided journal return 200 and list normally. The 404 is about the record's status, not its existence (GET /invoices/:id on the same id works), so never read this 404 as a bad resourceId. Anything fanning out to attachments alongside other calls must treat that leg as degradable, or one voided record destroys the whole response; get_transaction_summary did exactly that until 5.55.1.
2. Currency rate direction: `rate` = functionalToSource (1 base = X foreign). POST rate: 0.74 for a SGD org means 1 SGD = 0.74 USD. If your data stores rates as "1 USD = 1.35 SGD" (sourceToFunctional), you MUST invert: `rate = 1 / 1.35 = 0.74`. GET confirms both: rateFunctionalToSource (what you POSTed) and rateSourceToFunctional (the inverse). You do not have to do the arithmetic: add_currency_rate, update_currency_rate and the currency object on the 8 FX create tools (invoice, bill, journal, both credit notes, both cash entries, TTB) accept an optional rateDirection (FUNCTIONAL_TO_SOURCE | SOURCE_TO_FUNCTIONAL): declare how your figure reads and pass it verbatim. Omitting it always means FUNCTIONAL_TO_SOURCE. The two families differ only in where the label is applied: the rate-table tools (plus bulk_upsert_currency_rates) send it on the wire and the server applies it, while the 8 FX create tools have no such field, so the client inverts and strips it there. Prefer either to inverting by hand: a wrong inversion is silent and wrong by rate². clio calc fx-reval REQUIRES the direction; that calculator historically assumed the opposite convention to the API.

Search & Filter

1. Search endpoint universal pattern: All 32 POST /*/search endpoints share identical structure: { filter?, sort: { sortBy: ["field"], order: "ASC"|"DESC" }, limit: 1-1000, offset: 0-65536 }. offset is a 0-indexed page number (not row-skip), except on the row-offset endpoints listed in Rule 38. Sort is REQUIRED when offset is present (even offset: 0). Default limit: 100. sortBy is always an array on all endpoints (no exceptions). See references/search-reference.md for per-endpoint filter/sort fields.

50a. `query` field (Jaz search operators): 14 endpoints accept an optional query string alongside filter: invoices, bills, customer/supplier credit notes, journals, cashflow-transactions, bank-records, contacts, items, capsules, fixed-assets, scheduled-transactions, chart-of-accounts, tax-profiles. Example: { "query": "status:unpaid AND $500+", "limit": 50 }. Key syntax: amounts ($500+, $100-500, amount:>2m, magnitude suffixes 5k/2m/1b), negative ($-500), absolute value (abs:1000+), dates (date:this month, date:-30d, due:overdue, submitted:last week, lastpayment:-7d), status/enum (status:unpaid, currency:SGD,USD; comma = OR), string fields (customer:acme, ref:INV-* wildcard, =ref:INV-001 exact, ref:/\d{4}/ regex), blank checks (ref:blank, tag:!blank), booleans (hasattachment:yes, customer:yes), negation (!status:paid or NOT status:void; never `-` for negation), logic (AND/OR with implicit AND on space), grouping, inline sort (sort:amount:desc). Full syntax spec (all fields, aliases, entity field lists, examples): `references/search-syntax.md`. 50b. `query` + `filter` merge: When both are present, they are merged at the filter level. Explicit filter keys win on conflict. Use query for human-readable shorthand, filter for programmatic precision, or combine both: { "query": "date:this year", "filter": { "currencyCode": { "in": ["SGD"] } } }. 50c. `query` error handling: Unknown field name → query_not_understood (400). Bad enum value (e.g. status:BADVALUE) → empty results, no error (silent miss). Unsupported endpoint → query_not_supported (400). Parser unavailable → query_parse_error (502). Empty/null/whitespace query → passthrough (ignored). In CLI/MCP: use --query / query param only on supported entities; unsupported entities have no --query flag.

1. Filter operator reference: An operator the target type does not declare is now rejected with a 400 naming it, not ignored, so use the exact set. String: eq, neq, contains, notContains, in (array, max 100), likeIn (array, max 100), reg (substring array, max 100; a term match despite the name, not a regex), startWith, notStartWith, endWith, notEndWith, isNull, isBlank, isNotBlank (each takes the string "true"/"false", not a bool). Numeric: eq, neq, gt, gte, lt, lte, in, inRange/notInRange (exactly 2 values, low then high). Date (YYYY-MM-DD): eq, gt, gte, lt, lte, between/notBetween (exactly 2 values), isNull, isNotNull. DateTime (RFC3339): eq, gt, gte, lt, lte, between, converted to epoch ms internally. Boolean: eq. JSON: jsonIn, jsonNotIn. Logical: and/or objects everywhere; andGroup/orGroup arrays on invoices, bills, journals, cashflow transactions, payments, batch payments and the order family (orders, quotes, requests, line items), not on credit notes. not exists only on contacts, items, tags, custom fields, tax profiles and nano classifiers; it is not available on invoices, bills or journals.
2. Date format asymmetry (CRITICAL). Request dates: YYYY-MM-DD strings (all create/update and DateExpression filters). Request datetimes: RFC3339 strings (DateTimeExpression filters for createdAt, updatedAt, approvedAt, submittedAt). ALL response dates: int64 epoch milliseconds, including valueDate, createdAt, updatedAt, approvedAt, submittedAt, matchDate. Convert: new Date(epochMs).toISOString().slice(0,10). Timezone convention: ALL business dates (valueDate, dueDate, startDate, endDate, etc.) are in the organization's timezone, never UTC. The epoch ms stored in the DB represents the org-local date (no timezone conversion is ever needed). Only audit timestamps (createdAt, updatedAt, action_at) are UTC.
3. Field aliases on create endpoints. Middleware transparently maps: issueDate/date → valueDate (invoices, bills, credit notes, journals). name → tagName (tags) or internalName (items). paymentDate → valueDate, bankAccountResourceId → accountResourceId (payments). paymentAmount → refundAmount, paymentMethod → refundMethod (credit note refunds). accountType → classificationType, currencyCode → currency (CoA). Canonical names always work; aliases are convenience only.
4. All search/list responses are flat: every search and list endpoint returns { totalElements, totalPages, data: [...] } directly (no outer data wrapper). Access the array via response.data, pagination via response.totalElements. Four exceptions: (a) GET /bank-accounts returns a plain array [{...}] (see Rule 18), (b) GET /invoices/:id returns a flat object {...} (no data wrapper), unlike GET /bills/:id, GET /contacts/:id, GET /journals/:id which wrap in { data: {...} }. Normalize the invoice GET response before use. (c) *The empty-result envelope on the scheduled-\ handlers changes shape: when the upstream search block comes back null, eight handlers short-circuit to `{ "data": [], "pagination": { "total": 0 } }`. No `totalElements`, no `totalPages`, and a third pagination key name. The SAME endpoint returns the normal flat envelope the moment one row exists. Affected: list AND attachment-list on scheduled invoices, scheduled bills, scheduled journals, scheduled subscriptions. Never read totalElements on a scheduled-\ response without falling back to `pagination.total` (`response.totalElements ?? response.pagination?.total ?? 0`) and count rows off `data.length`, which is correct in both shapes. (d) `GET /organization-report-template` returns its rows under `reportTemplates`, not `data`, and carries no counts: measured 2026-09-06 against an org holding 12 templates, where `data` was `[]` and `totalElements` `0`. The `list_organization_report_templates` tool normalizes it, so read `.data` as usual; the raw endpoint does not. Its `/search` sibling returns a bare array* with no envelope, the same shape as exception (a) above. So the two halves of one family disagree with each other. Both are normalized for you by the tools, so read .data as usual. The endpoint also ignores limit/offset entirely (probed at 1, 3 and 100; 12 rows every time), so it returns everything in one response.
5. Scheduled endpoints support date aliases: txnDateAliases middleware (mapping issueDate/date → valueDate) now applies to all scheduled create/update endpoints: POST/PUT /scheduled/invoices, POST/PUT /scheduled/bills, POST/PUT /scheduled/journals, POST/PUT /scheduled/subscriptions.
6. Kebab-case URL aliases. capsuleTypes endpoints also accept kebab-case paths: /capsule-types (list, search, CRUD). moveTransactionCapsules also accepts /move-transaction-capsules. Both camelCase and kebab-case work identically.

Jaz Magic: Extraction & Autofill

1. When the user starts from an attachment, always use Jaz Magic: if the input is a PDF, JPG, or any document image (invoice, bill, receipt), the correct path is POST /magic/createBusinessTransactionFromAttachment. Do NOT manually construct a POST /invoices or POST /bills payload from an attachment; Jaz Magic handles the entire extraction-and-autofill pipeline server-side: OCR, line item detection, contact matching, CoA auto-mapping via ML learning, and draft creation with all fields pre-filled. Only use POST /invoices or POST /bills when building transactions from structured data (JSON, CSV, database rows) where the fields are already known. If you hold the invoice/bill as raw HTML (e.g. an email body), pass it via sourceType: "HTML" with an html field; the backend renders it to a PDF then extracts, so you do NOT need to save it to a file first.
2. Three upload modes with different content types: sourceType: "FILE" requires multipart/form-data with sourceFile blob (JSON body fails with 400 "sourceFile is a required field"). sourceType: "URL" accepts application/json with sourceURL string. sourceType: "HTML" accepts the raw HTML body in an html field (JSON or multipart); the backend renders it to a PDF, then extracts (use this for an email body you already hold; no file needed). The OAS only documents URL mode; FILE and HTML modes are undocumented there.

58a. The server FETCHES the source; a local path is not a source at any spelling: in URL mode sourceURL is opened by the Jaz server, so it must be reachable from the public internet; in FILE mode you send the bytes yourself as a multipart blob. A path on the calling machine (/mnt/user-data/uploads/x.zip, /tmp/invoice.pdf) is neither: it is not a URL the server can open, and putting it in sourceURL (or in an MCP file.download_url, which the HOST populates and a caller must never author) fails after a round-trip with no indication that re-spelling the path is hopeless. Same rule for classify_documents: its source is fetched server-side, and a local folder/zip path is accepted only when the client is running on the caller's own machine. When you hold bytes but no shareable URL, switch to FILE mode or ask for a Dropbox/Drive/OneDrive share link; do not retry the path.

1. Three required fields + one optional: the source (sourceFile multipart blob, NOT file, for FILE, sourceURL for URL, or html for HTML), businessTransactionType ("INVOICE", "BILL", "CUSTOMER_CREDIT_NOTE", "SUPPLIER_CREDIT_NOTE", "SALE_QUOTE", "SALE_ORDER", "PURCHASE_REQUEST", or "PURCHASE_ORDER"; EXPENSE rejected; a quote/request lands DRAFT, an order lands PENDING until the order update's isPendingToActive* flag), sourceType ("FILE", "URL", or "HTML"). For HTML mode, html is the raw HTML string (max 5 MB). Optional: uploadMode ("SEPARATE" default, or "MERGED" for a single PDF containing multiple documents; the backend splits it via boundary detection before extraction; refused for the four quote/order/request types) and internalNotes (max 3000 characters, set on the created record). Max 10 MB per file. All required fields are validated server-side. CRITICAL: multipart form field names are camelCase: businessTransactionType, sourceType, sourceFile, uploadMode, NOT snake_case. Using business_transaction_type returns 422 "businessTransactionType is a required field". The File blob must include a filename and correct MIME type (e.g. application/pdf, image/jpeg); bare application/octet-stream blobs are rejected with 400 "Invalid file type".

59a. MERGED upload workflow tracking: When uploadMode: "MERGED", the upload response workflowResourceId is a parent tracking ID. The backend splits the PDF, then creates child workflows for each split page; these child IDs appear in POST /magic/workflows/search (by fileName or createdAt), NOT the parent ID. To track MERGED progress, search by fileName rather than the parent workflowResourceId.

1. Response maps transaction types: Request INVOICE → response SALE. Request BILL → response PURCHASE. Request CUSTOMER_CREDIT_NOTE → response SALE_CREDIT_NOTE. Request SUPPLIER_CREDIT_NOTE → response PURCHASE_CREDIT_NOTE. S3 paths follow the response type. The response validFiles[] array contains workflowResourceId for tracking extraction progress via POST /magic/workflows/search.
2. Extraction is asynchronous: the API response is immediate (file upload confirmation only). The actual Magic pipeline (OCR, line item extraction, contact matching, CoA learning, and autofill) runs asynchronously. Use POST /magic/workflows/search with filter.resourceId.eq: "<workflowResourceId>" to check status (SUBMITTED → PROCESSING → COMPLETED/FAILED). When COMPLETED, businessTransactionDetails.businessTransactionResourceId contains the created draft BT ID. The subscriptionFBPath in the response is a Firebase Realtime Database path for real-time status updates (alternative to polling).
3. Accepts PDF and JPG/JPEG: both file types confirmed working. Handwritten documents are accepted at upload stage (extraction quality varies). fileType in response reflects actual format: "PDF", "JPEG".
4. Workflow search tracks all magic uploads: POST /magic/workflows/search searches across BT extractions AND bank statement imports. Filter by resourceId (eq), documentType (SALE, PURCHASE, SALE_CREDIT_NOTE, PURCHASE_CREDIT_NOTE, SALE_QUOTE, SALE_ORDER, PURCHASE_REQUEST, PURCHASE_ORDER, BANK_STATEMENT), status (SUBMITTED, PROCESSING, COMPLETED, FAILED), fileName (contains), fileType, createdAt (date range). Response: paginated MagicWorkflowItem with businessTransactionDetails.businessTransactionResourceId (the draft BT ID when COMPLETED) or bankStatementDetails (for bank imports). Standard search sort: { sortBy: ["createdAt"], order: "DESC" }.

Cashflow & Unified Ledger

1. Four ways to read payments: pick by scope. GET /payments (list) and POST /payments/search do NOT exist and never did. What does exist: (a) per-payment CRUD: GET/PUT/DELETE /payments/:resourceId; (b) payment-scoped search: POST /sales/payments/search and POST /purchases/payments/search (added 2026-08-13), one side of the ledger each, plus POST /batch-payments/search for batches; (c) cross-entity ledger: POST /cashflow-transactions/search, the unified transaction ledger spanning invoices, bills, credit notes, journals, cash entries and payments. Filter it by businessTransactionType (e.g. SALE, PURCHASE) and direction (PAYIN, PAYOUT). Response dates are epoch milliseconds. The cashflow ledger tool is search_cashflow_transactions; its resourceId is a ledger row, not a payment record, so it 404s on get_payment / update_payment, which take a document's paymentRecords id. The per-side payment searches (b) have no tool; reach them with a raw request. (d) Per-document settlements: GET /invoices/:id/payments and GET /bills/:id/payments, and for credit notes GET /customer-credit-notes/:id/refunds / GET /supplier-credit-notes/:id/refunds (the domain distinguishes a refund from a payment; a journal has neither). This is the right call for one known document's own settlements and the one to reach for first: no filter to get wrong. All four answer { data: [...] } (measured raw 2026-09-07). It is listed here because it was missing from this rule while (c) sat one line away, and get_transaction_summary consequently filtered the ledger by businessTransactionResourceId, a field TransactionsFilter does not declare, for its entire life, 400ing on every call behind a silent catch.
2. Contacts search uses `name`, NOT billingName. The filter field for searching contacts by name is name (maps to billingName internally). Sort field is also name. Using billingName in a search filter returns zero results.

Response Shape Gotchas

1. Contact boolean fields are `customer`/`supplier`, NOT isCustomer/isSupplier. These are plain booleans on the contact object: { "customer": true, "supplier": false }. Using isCustomer or isSupplier in code will be undefined.
2. Finalized statuses differ by resource type, NOT "FINALIZED", "FINAL", or "POSTED". Journals → "ACTIVE" (journals have no approval state: their lifecycle is ACTIVE | VOID | DRAFT; live-verified 2026-08-03). Invoices/Bills → "UNPAID" (progresses to "PARTIALLY_PAID", "PAID"). OVERDUE is not a status (a list with it returns 422 and a search matches nothing), so find overdue documents with status in [UNPAID, PARTIALLY_PAID] plus dueDate lt <today in the organization's timezone>. Customer/Supplier Credit Notes → "UNAPPLIED" (progresses to "PARTIALLY_APPLIED", "APPLIED"). All types support "DRAFT" and "VOID" (not "VOIDED"). When creating with saveAsDraft: false, the response status matches the type's finalized status.
3. Create/pay responses are minimal by default: POST create endpoints (invoices, bills, journals, contacts, payments) return only { resourceId: "..." } (plus a few metadata fields). They do NOT return the full entity. To verify field values after creation, do a subsequent GET /:type/:resourceId. MCP tool shortcut: create_invoice / create_bill / create_journal / create_contact / create_item accept returnFullEntity: true: the executor performs the GET server-side and returns the full entity inline, saving a turn. The raw REST POST is still minimal-only; only the MCP tools collapse the round trip. If the post-create GET fails (transient 5xx, network blip), the tool returns the minimal create envelope augmented with _hydration: { status: 'failed', resourceId, message }. The write committed; the agent should retry only the get_* call, NEVER the create (would duplicate the document). `_fx` on transaction creates: invoice/bill/credit-note create results may carry a sibling _fx field, e.g. FX: 1 SGD (your base) = 0.74 USD (applied rate for 2026-04-03), the exchange rate the record was ACTUALLY created with. Relay that line to the user verbatim; it matters most when the caller supplied no rate (the organization rate was applied silently, and a rate stored the wrong way round reads as an obviously absurd number the user can catch on sight).
4. No `amountDue` field: Invoices and bills do NOT have an amountDue field. To check if a transaction is fully paid, inspect the paymentRecords array: if paymentRecords.length > 0, payments exist. Compare totalAmount with the sum of paymentRecords[].transactionAmount to determine remaining balance.
5. Response dates include time component: Even though request dates are YYYY-MM-DD, response dates are epoch milliseconds (see Rule 52). When comparing dates from responses, always convert with new Date(epochMs).toISOString().slice(0, 10), never string-match against the raw epoch value. Remember: business dates are org-timezone (see Rule 52).
6. Items POST requires `saleItemName`/`purchaseItemName`: When creating items with appliesToSale: true or appliesToPurchase: true, you MUST include saleItemName and/or purchaseItemName respectively. These are the display names shown on sale/purchase documents. Omitting them causes 422: "saleItemName is a required field". If not specified, default to the internalName value.
7. Items PUT requires `itemCode` + `internalName`: Even for partial updates, PUT /items/:id requires both itemCode and internalName in the body. Omitting either causes 422. Use read-modify-write pattern: GET current item, merge your updates, PUT the full payload. Clio handles this automatically.
8. Capsules PUT requires `resourceId` + `capsuleTypeResourceId`: Even for partial updates, PUT /capsules/:id requires resourceId and capsuleTypeResourceId in the body. Omitting either causes 422 or "Capsule type not found". Use read-modify-write pattern: GET current capsule, merge updates, PUT full payload. Clio handles this automatically.

Cash Entry Response Shape (CRITICAL)

1. Cash-in/out/transfer CREATE returns `parentEntityResourceId`: the resourceId in the POST response ({ data: { resourceId: "X" } }) is the journal header's parentEntityResourceId. This ID is used for DELETE (DELETE /cash-entries/X) and PUT. GET (GET /cash-in-entries/:id) accepts either the cashflow-transaction resourceId from the LIST response or this parentEntityResourceId. Three different IDs exist per cash entry: parentEntityResourceId (from CREATE + in LIST), resourceId (cashflow-transaction ID, from LIST, also accepted by GET), businessTransactionResourceId (underlying journal ID, do NOT use for anything).
2. Cash-in/out/transfer LIST/GET return cashflow-transaction shape, NOT journal shape. Key field differences from journals: transactionReference (NOT reference), transactionStatus (NOT status; values: ACTIVE/VOID), valueDate is epoch ms (NOT ISO string), no journalEntries array, has direction (PAYIN/PAYOUT), has nested account object with bank name, has businessTransactionType (JOURNAL_DIRECT_CASH_IN/JOURNAL_DIRECT_CASH_OUT/JOURNAL_CASH_TRANSFER).
3. Cash-in/out/transfer search uses `/cashflow-transactions/search`: Filter by businessTransactionType: { eq: "JOURNAL_DIRECT_CASH_IN" } (or JOURNAL_DIRECT_CASH_OUT or JOURNAL_CASH_TRANSFER). Other useful filters: organizationAccountResourceId (bank account), businessTransactionReference (reference), valueDate (date range). The search endpoint is shared across all cashflow transaction types.
4. DELETE for cash entries uses `/cash-entries/:id`, NOT the individual resource paths. The ID used is the parentEntityResourceId (= the resourceId returned by CREATE). This is a shared endpoint for all cash entry types (cash-in, cash-out, cash-transfer).

Entity Resolution (Fuzzy Matching)

1. `--contact`, `--account`, and `--bank-account` accept names: any CLI flag that takes a contact, chart of accounts entry, or bank account accepts EITHER a UUID resourceId OR a fuzzy name. Examples: --contact "ACME Corp", --account "DBS Operating", --bank-account "Business". The CLI auto-resolves to the best match (strict thresholds) and shows the resolved entity on stderr. UUIDs are passed through without API calls. If the match is ambiguous, the CLI errors with a list of candidates, never silently picks the wrong entity.
2. Payment/refund account is gated by `paymentMethod`, not by the field's type: the field itself accepts any chart-of-accounts id (the REST layer applies no type filter), but the platform then rejects anything outside Bank Accounts / Cash when the method is BANK_TRANSFER, CASH or CHEQUE: INVALID_ACCOUNT_FOR_BUSINESS_TRANSACTION_FOUND. Every other method reaches a non-bank account, which is the only way a deposit drawdown works: pay an invoice with paymentMethod: OTHER and accountResourceId set to the deposit account. The CLI mirrors this, filtering --account to bank/cash for those three methods only. Do not read the permissive field as permission: the REST layer is a proxy, and the accounting engine behind it is the authority.

Draft Finalization Pipeline (Convert & Next)

The clio bills draft subcommand group enables the full "review → fill missing → convert" workflow that mirrors the Jaz UI's "Convert and Next" button. Designed for AI agents processing a queue of draft bills.

#### Commands

#### Mandatory Fields for Bill Finalization

Optional: --ref, --notes, --tag, --tax-profile <name/UUID> (bulk, fuzzy resolved), --tax, --tax-inclusive, --dry-run, --input <file>.

#### Agent Workflow Pattern

Step 1:  clio bills draft list --json
         → Batch queue: every DRAFT with per-field validation + attachment count

Step 2:  For each draft where ready = false:
         a) Read validation.missingFields from Step 1 output
         b) Optional: clio bills draft attachments <id> --json
            → Download fileUrl, read PDF/image, extract or verify values
         c) Resolve values (ask user, or infer from attachment + context)
         d) clio bills draft finalize <id> --contact "Acme" --date 2025-01-15 ... --json
            → Updates + converts to UNPAID in one PUT (Rule 67: bills/invoices → UNPAID, journals → ACTIVE)

Step 3:  For each draft where ready = true:
         clio bills draft finalize <id> --json
         → Converts directly (all mandatory fields already present)

1. `--account` bulk patches line items: when used with clio bills draft finalize, --account resolves the name to a UUID then sets accountResourceId on EVERY line item where it's currently null. Existing accounts are NOT overwritten. Same for --tax-profile. --lines takes priority (full replacement).
2. `--dry-run` validates without modifying: returns the same validation structure as draft list (per-field status/hint), so agents can preview what would happen before committing. No API write occurs.
3. Finalization is a single PUT: updateBill() with saveAsDraft: false transitions DRAFT → UNPAID (per Rule 67) and updates all fields in one call. No delete-and-recreate. The CLI handles all field normalization automatically (date format, line item sanitization, account field name mapping).
4. Draft list attachment count: draft list includes attachmentCount per draft (from GET /bills/:id/attachments). Use draft attachments <id> for full details including fileUrl download links.
5. PUT body requires `resourceId`: The UpdateBill PUT endpoint requires resourceId in the body (in addition to the URL path). Dates must be YYYY-MM-DD (not ISO with time). taxInclusion is boolean (true/false), not string. Line items must use accountResourceId (not organizationAccountResourceId from GET).
6. GET→PUT field asymmetry: GET returns organizationAccountResourceId on line items; PUT requires accountResourceId. GET returns dates as 2026-02-27T00:00:00Z; PUT requires 2026-02-27. GET returns taxProfile: { resourceId } object; PUT requires taxProfileResourceId string. The CLI draft finalize command normalizes all of these automatically.
7. Magic workflow status may be null immediately after creation: The POST /magic/workflows/search endpoint may return a workflow with status: null right after POST /magic/create-from-attachment. Allow 2-3 seconds before polling, or default to SUBMITTED. The CLI magic status command defaults null status to SUBMITTED.
8. Finalized invoices/bills need `accountResourceId` on all line items: When saveAsDraft: false (or using --finalize), every lineItems[i].accountResourceId must be set. Omitting it causes 422: "lineItems[0].accountResourceId is required if [saveAsDraft] is false". The CLI validates this pre-flight.

#### DRY Extension Pattern

Bills, invoices, and credit notes share identical mandatory field specs. Adding clio invoices draft or clio customer-credit-notes draft later reuses all validation, formatting, and CLI flag logic from draft-helpers.ts; only the API calls differ.

Bank Rules

1. Bank rules GET by ID has double-nested response: GET /bank-rules/:id returns { data: { data: [...], totalElements, totalPages } } (double data wrapper). Unlike standard GET /:type/:id which returns { data: {...} }. The inner data is an array containing the single rule. Unwrap with response.data.data[0]. Field asymmetry: Request uses appliesToReconciliationAccount (string UUID), response returns it as an object { code, currencyCode, name }.
2. Bank rules search uses `/bank-rules/search`: Standard search pattern with filter/sort/limit/offset. Filter fields: appliesToReconciliationAccount, name, reference, resourceId, actionType, businessTransactionType. Sort fields: resourceId, name, actionType, businessTransactionType, reference, appliesToReconciliationAccount, createdAt.

90a. Bank rules create field is `appliesToReconciliationAccount` (NOT appliesToReconciliationAccountResourceId), the bank account UUID. configuration must nest under reconcileWithDirectCashEntry key. configuration.reconcileWithDirectCashEntry.reference is REQUIRED (omitting causes GENERAL_ERROR). amountAllocationType: use "PERCENTAGE" or "FIXED"; "FIXED_AND_PERCENTAGE" is read-only (include both fixedAllocation + percentageAllocation arrays and the server infers it). Optional config fields: contactResourceId, internalNotes, tags, currencySettings, taxCurrencySettings, classifierConfig on allocation lines. Send `searchFilter` too, see 90d; a rule without one is never suggested. 90b. Bank rules PUT is FULL REPLACEMENT: PUT /bank-rules/:id replaces the entire rule. Must send resourceId, appliesToReconciliationAccount, and full configuration every time. Omitting any required field causes GENERAL_ERROR. Use read-modify-write pattern: GET current rule, merge changes, PUT full payload. Same pattern as items PUT (Rule 72) and capsules PUT (Rule 73). `searchFilter` is the one exception: omit it and the API keeps the stored condition, send null to remove it, send an object to replace it. 90c. Bank rule POST canonical create payload (verified live 2026-04, NOT obvious from any single field error):

{
  "name": "My Rule",
  "appliesToReconciliationAccount": "<bank-account-uuid>",
  "configuration": {
    "reconcileWithDirectCashEntry": {
      "amountAllocationType": "PERCENTAGE",
      "reference": "AUTO-{{bankReference}}",
      "percentageAllocation": [
        { "organizationAccountResourceId": "<acct-uuid>", "amount": 100 }
      ]
    }
  }
}

Required nested keys (each missing one returns a different cryptic error):

• configuration MUST nest under reconcileWithDirectCashEntry key (the action type, even though there's only one type today)
• amountAllocationType: "PERCENTAGE" or "FIXED" only (NOT FULL_AMOUNT despite that sounding right)
• For PERCENTAGE: percentageAllocation: [{organizationAccountResourceId, amount}] (ARRAY of allocations summing to 100)
• For FIXED: fixedAllocation: [{organizationAccountResourceId, amount}] (ARRAY of fixed amounts)
• reference is required in the action config (omitting → cryptic 422)

Dynamic strings: name and reference support {{bankReference}}, {{bankPayee}}, {{bankDescription}} placeholders, replaced with bank record values during reconciliation.

actionShortcutResourceId for apply_bank_rule IS the rule's own resourceId from create response (no separate "action shortcut" entity).

90d. Bank rules support column-value mapping. reconcileWithDirectCashEntry can resolve fields per row from a custom bank-statement column: amountSourceColumnKey (set amount by a column; mutually exclusive with amount), organizationAccountResourceIdMap/taxProfileResourceIdMap/classifierConfigMap on each fixedAllocation line, and contactResourceIdMap/tagsMap on the shortcut. Each *Map is a ColumnValueMapConfig (columnKey + ordered mappings[], first match wins, blank matchValue = catch-all); targetResourceId is a UUID (tag NAME for tagsMap). reference also takes {{column:<key>}} / {{column_abs:<key>}} tokens. Full shape: references/bank-rule-column-mapping.md. The rule's WHEN side is the inline `searchFilter`, and without one the rule is never suggested. Auto-reconciliation only considers rules whose stored condition is non-null, so a rule created without it exists, lists, and applies manually, but is never offered. Shape: {"version": 1, "raw": "description:grab", "parsed": {"description": {"contains": "grab"}}}; raw is the one-line form shown in the app and may be blank; parsed is what the matcher compiles. Condition fields: description, extReference, extContactName, netAmount, valueDate, plus the account's active custom Bank Fields. Operators (15, from the matcher's own map): TEXT eq/contains/notContains/startWith/notStartWith/isBlank/isNotBlank, compared case-insensitively, the blank pair taking no value; NUMERIC eq/gt/gte/lt/lte/inRange/notInRange; DATE eq/gt/gte/lt/lte/between/notBetween. Combine with {"and": {...}} or {"orGroup": [{"and": {...}}]}. An unsupported field path does not error: the rule saves, lists, and then never fires, because the matcher logs a warning server-side and skips it; use only the fields above. relatedSearchShortcutResourceIds (the retired saved-search path) is not exposed by this API at all; the platform rejects a request that sets both.

Fixed Assets

1. Fixed asset search does NOT support `createdAt` sort. Valid sort fields: resourceId, name, purchaseDate, typeName, purchaseAmount, bookValueNetBookValueAmount, depreciationMethod, status. Using createdAt returns 422. Default to purchaseDate DESC.
2. Fixed asset disposal/sale/transfer use different endpoint patterns. Discard: POST /discard-fixed-assets/:id (body includes resourceId + dates). Mark sold: POST /mark-as-sold/fixed-assets (body-only, no path param). Transfer: POST /transfer-fixed-assets (body-only). Undo: POST /undo-disposal/fixed-assets/:id.

92a. Two ways to register fixed assets. (1) Create (POST /fixed-assets): for assets purchased via a bill or journal already in the system. ACTIVE assets require purchaseBusinessTransactionType (PURCHASE or JOURNAL_MANUAL) and purchaseBusinessTransactionResourceId, the resourceId of the purchase LINE ITEM (or the manual-journal entry), NOT the bill or journal document. Passing the document id fails. The line item must also be UNLINKED: reusing one already attached to another asset fails with ITEM_ALREADY_LINKED_WITH_ANOTHER_FIXED_ASSET. (2) Transfer (POST /transfer-fixed-assets): for pre-ex