Teach a persistent counterparty → account rule
create_counterparty_ruleCreates (or updates) a persistent per-org rule mapping a counterparty to an account, then BACK-APPLIES it to every pending review event from that counterparty — each is properly approved (journal lines written, audit entry, ledger sync queued), not bulk edited. After this, future events from the counterparty auto-classify and never reach review. This is how you act on get_pending_by_counterparty: "categorise all my AWS as infrastructure" becomes one call. This WRITES financial data — only call it with an account you are confident in. The counterparty is matched on a normalised key, so "AWS, Inc." and "AWS EMEA" resolve to the same rule. Idempotent: re-running updates the single rule and re-approves nothing already approved. actor_id is optional — it defaults to the organisation entity, and if provided must belong to this org. GUARDRAIL (OOB approval): if the rule would back-apply to an unusually large set (many events, a large aggregate, or a large rolling-hour total across recent applies), it returns status "approval_required" and writes ONLY an approval request — YOU CANNOT BOOK IT YOURSELF; confirm:true does not bypass it. Your human gets an email and approves on the dashboard, at which point the action books automatically — do NOT retry the call; verify later by re-reading the books (e.g. get_pending_by_counterparty). If the response says the request was denied recently, do not re-ask for 24h. Small approvals apply immediately (status "applied").
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| org_id | No | Optional. Defaults to the organisation the authenticated API key is bound to, so you normally omit it and never need to ask the user for their organisation UUID. If provided, it must match the key’s org or the request is rejected. | 0e91146d-511c-469f-bdee-5c867b26ae0d |
| reason | Yes | Why this mapping is correct. Stored verbatim in the audit trail. | |
| confirm | No | DEPRECATED — no longer bypasses the guardrail. Above-guard applies always return status "approval_required" (your human approves out-of-band); re-calling with confirm:true changes nothing. Kept for wire compatibility. | |
| actor_id | No | Optional. Defaults to the organisation entity (correct for an org-scoped key). If provided, it must be an entity belonging to this organisation — arbitrary UUIDs are rejected, so the audit trail cannot be attributed to someone else. | |
| direction | No | Restrict the rule to one direction (inbound = money in, outbound = money out). Null applies it to both. Use outbound for a vendor you pay (an expense). | |
| counterparty | Yes | The counterparty name to make a rule for (e.g. "AWS"). Normalised to a key, so any variant of the same vendor matches. | |
| approved_category | Yes | The account future and pending events from this counterparty are classified as: a numeric chart code (4000 SaaS Revenue, 4100 Usage Revenue, 4900 Other Income, 5000 API & Compute Costs, 5100 Payment Processing Fees, 5200 Platform Commission, 6100 Software Subscriptions, 6200 Contractor & Freelancer, 6300 Marketing & Ads, 6400 Banking & Finance Fees, 6500 Payroll, 6600 Taxes, 6700 Foreign Exchange Gain/Loss, 6750 Unrealized FX Gain/Loss, 6800 Office & Equipment, 6810 Travel, 6820 Meals & Entertainment, 6830 Professional Services, 6840 Insurance, 6900 Other Expenses, 2100 Accounts Payable, 3900 Owner Contributions & Transfers, 1100 Cash & Bank, 1150 Stripe Receivable, 1160 App Store / Play Receivable, 1200 Stripe Settlement) or a rollup category (revenue → 4000, cost_of_goods → 5000, operating_expense → 6100). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | ||
| message | No | ||
| rule_id | No | ||
| category | Yes | ||
| currency | No | ||
| direction | Yes | ||
| account_code | Yes | ||
| applied_count | No | ||
| pending_count | No | ||
| approval_state | No | ||
| counterparty_key | Yes | ||
| approval_request_id | No | ||
| pending_total_cents | No |