Create a bank rule

Operation ID: createBankRule

Group: Banking › Bank Rules

Open in the interactive reference

POST /banking/bank-rules

Retry-safe: A write that accepts Idempotency-Key: repeating a request with the same key replays the stored answer instead of executing twice.

Creates a bank rule, with its criteria, accounts, and action object. The response contains 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, the watched bank accounts, and the action object describing the entry to create. createBankEntry and createCreditCardEntry need at least one watched account; createFundTransfer derives its two sides from the action object and takes none.

The watched accounts constrain the action. For createBankEntry and createCreditCardEntry 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 being ACTION_ACCOUNT_TYPE_MISMATCH. createFundTransfer is exempt from all three: a transfer spans two accounts, so it may mix entities (intercompany) and account types.

Only three of the four rule actions are implemented. autoMatch is rejected with RULE_ACTION_NOT_SUPPORTED, which is why the input is a three-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.

Parameters

Request body

Required, application/json: createBankRuleInput.

{
  "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"
    }
  ],
  "criteriaGroups": [
    {
      "key": "<key>",
      "parentKey": "<parentKey>",
      "logicalOperator": "and"
    }
  ],
  "actionObject": {
    "accountId": "6d1e4b27-8a90-4c31-b5f2-7e8a9c0d1b23",
    "name": "Stripe payout",
    "description": "Auto-created by rule"
  }
}

Response

200 Success

Under data (createBankRuleOutput):

{
  "data": {
    "id": "9f2c6a10-7d34-4c8e-9b21-5a0f3e6d81b7"
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Response headers

• Idempotency-Replayed — Present and true only when this response replays a previously stored one for the same Idempotency-Key, rather than reflecting a live execution. Absent on a live response - never sent as false.

Errors

Statuses

• 400 — Invalid request or business failure. Codes: REFERENCE_NOT_FOUND, ACCOUNTS_REQUIRED, CRITERIA_REQUIRED, ACTION_OBJECT_REQUIRED, ACCOUNTS_SPAN_ENTITIES, MIXED_ACCOUNT_TYPES, ACTION_ACCOUNT_TYPE_MISMATCH, RULE_ACTION_NOT_SUPPORTED, DUPLICATE_RULE_NAME, INVALID_FUND_TRANSFER, INVALID_CRITERIA, ACCOUNT_NOT_POSTABLE
• 401 — The request carries no valid access token.
• 403 — Not authorized
• 404 — Not found
• 409 — The Idempotency-Key is still being processed by another request.
• 422 — The Idempotency-Key was already used with a different request payload.
• 429 — Too many requests from this client address. The response has no body and no Retry-After header.
• 500 — Internal server error