Create Bank Rule

POST /banking/bank-rules

Group: Banking › Bank Rules · Operation ID: createBankRule

Create a bank rule, with its criteria, watched bank accounts and action object, and return its id. Returns only the id; read the record back with GET banking/bank-rules/:id for its stored state. Every request must carry the Api-Version header.

Creates one bank rule and returns its id — and only its id. Read the record back with GET banking/bank-rules/{id} if you need its stored state; bankRuleNumber comes from a gapless number range and is visible only on that follow-up GET.

A rule is created whole: the header, at least one criterion, at least one watched bank account, and the action object describing the entry to create. All four are required — there is no partial rule.

The watched accounts constrain the action. Every account must belong to one legal entity (ACCOUNTS_SPAN_ENTITIES), and they must be either all credit card accounts or all not (MIXED_ACCOUNT_TYPES). createCreditCardEntry then works only with credit card accounts and createBankEntry only with the rest; a mismatch is ACTION_ACCOUNT_TYPE_MISMATCH.

Only two of the four rule actions are implemented. createFundTransfer and autoMatch are rejected with RULE_ACTION_NOT_SUPPORTED, which is why the input is a two-member union rather than the whole enum.

Operators are constrained by the criterion. Numeric operators apply only to amount, text operators only to description and payeePayor, and an amount value must parse as a number. Anything else is INVALID_CRITERIA with the offending criterion named.

All guards run before the first write, so a rejected request creates nothing.

Open in the interactive reference

Parameters

Name In Type Required Description
Api-Version header "v1" yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.
Idempotency-Key header string no An opaque caller-chosen string (1-255 characters) that makes this request safe to retry. Repeating the same key with an identical request body replays the original response instead of re-executing - but only once that original request succeeded; a failed attempt re-executes on retry. Repeating the key with a different body is answered with 422. A key still in flight is answered with 409 - as is a key whose original request was interrupted before it finished, for a few minutes afterwards, until that attempt is presumed dead. A completed response stays replayable for 24 hours. The key is scoped to the caller, not to the action: reusing it for a different action is answered with 409 or 422 rather than treated independently. On read actions this header is ignored. On write actions that cannot offer the guarantee it is answered with 400 IDEMPOTENCY_NOT_SUPPORTED rather than silently ignored.

Request body

Required, application/json: createBankRuleInput.

Field Type Required Description
rule string yes Name of the rule. Must be unique across the tenant; a clash is DUPLICATE_RULE_NAME.
action string, one of "createBankEntry", "createCreditCardEntry" yes What the rule does when a transaction matches. Only these two are implemented; createFundTransfer and autoMatch are rejected with RULE_ACTION_NOT_SUPPORTED.
status string, one of "active", "inactive" yes Whether the rule is in force. Only an active rule can be run; deactivate a rule rather than deleting it to keep its history.
priority number yes Evaluation order relative to other rules; lower runs first.
description string no Free-text note on what the rule is for.
bankAccountIds array of string yes [fk: BankAccountApi.bankAccounts.id] The bank accounts this rule watches, given as their ids (UUIDs). At least one is required. All must belong to one legal entity, and must be either all credit card accounts or all not.
criteria array of object yes The conditions a bank transaction must meet. At least one is required; they are combined by each criterion's logicalOperator.
criteria[].criteria string, one of "amount", "description", "payeePayor" yes Which field of the transaction is tested.
criteria[].operator string yes How the field is compared. Numeric operators (equal, notEqual, greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual) apply only to 'amount'; text operators (is, isNot, contains, doesNotContain and their caseInsensitive variants) apply only to 'description' and 'payeePayor'. A mismatch is INVALID_CRITERIA.
criteria[].logicalOperator string, one of "and", "or" no How this criterion joins the next. Defaults to 'and' when omitted.
criteria[].value string yes The value compared against. Must parse as a number when criteria is 'amount'; free text otherwise. Required and non-empty.
actionObject object yes The entry the rule creates when a transaction matches. Required and must carry at least one field.
actionObject.accountId string no [fk: AccountApi.accounts.id] Account the created entry line books to, given as its id (a UUID).
actionObject.name string no Name stamped on the created entry.
actionObject.description string no Description stamped on the created entry and its line.
actionObject.billableExpense string, one of "yes", "no" no Whether the created credit card entry line is a billable expense. Customer applies only when this is 'yes'.
actionObject.businessUnitId string no [fk: BusinessUnitApi.businessUnits.id] Business unit stamped on the created line, given as its id (a UUID).
actionObject.departmentId string no [fk: DepartmentApi.departments.id] Department stamped on the created line, given as its id (a UUID).
actionObject.customerId string no [fk: CustomerApi.customers.id] Customer stamped on the created line, given as its id (a UUID).
actionObject.vendorId string no [fk: VendorApi.vendors.id] Vendor stamped on the created line, given as its id (a UUID).
actionObject.intercompanyPartnerId string no [fk: BusinessPartnerApi.businessPartners.id] Intercompany partner, given as its id (a UUID). Applied only when the booking account is paired for elimination; ignored otherwise, which is what the rule engine itself does.
actionObject.valueAllocationTags array of string no Value-allocation tag codes stamped on the created line. Applied only for dimensions still enabled on the document the rule creates.

Example:

{
  "rule": "Stripe payouts",
  "action": "createBankEntry",
  "status": "active",
  "priority": 10,
  "description": "Book Stripe payouts to the clearing account",
  "bankAccountIds": [
    "8f2c1d40-5a6b-4c7d-9e80-1f2a3b4c5d6e"
  ],
  "criteria": [
    {
      "criteria": "description",
      "operator": "containsCaseInsensitive",
      "logicalOperator": "and",
      "value": "STRIPE"
    }
  ],
  "actionObject": {
    "accountId": "6d1e4b27-8a90-4c31-b5f2-7e8a9c0d1b23",
    "name": "Stripe payout",
    "description": "Auto-created by rule"
  }
}

Response

200 Success

Under data (createBankRuleOutput):

Field Type Required Description
id string yes Platform id (a UUID) assigned to the newly created bank rule.

Response headers

Errors

Code Status
REFERENCE_NOT_FOUND 400
ACCOUNTS_REQUIRED 400
CRITERIA_REQUIRED 400
ACTION_OBJECT_REQUIRED 400
ACCOUNTS_SPAN_ENTITIES 400
MIXED_ACCOUNT_TYPES 400
ACTION_ACCOUNT_TYPE_MISMATCH 400
RULE_ACTION_NOT_SUPPORTED 400
DUPLICATE_RULE_NAME 400
INVALID_CRITERIA 400
ACCOUNT_NOT_POSTABLE 400
IDEMPOTENCY_KEY_CONFLICT 409
IDEMPOTENCY_PAYLOAD_MISMATCH 422

Statuses