# Search Bank Rule

`POST /banking/bank-rules/search`

Group: Banking › Bank Rules · Operation ID: `searchBankRule`

Search bank rules by id, name, action or status, and page through the matches. Read-only. Returns the full record for each match — the header plus its criteria, watched bank accounts and action object; matching nothing is an empty items array with HTTP 200, not a 404. Every request must carry the Api-Version header.

Search bank rules by id, name, action or status, and page through the matches. Returns the full record for each match — the header plus its criteria, watched bank accounts and action object — the same item schema as `GET banking/bank-rules/{id}`. Matching nothing is an empty `items` array with HTTP 200, not a 404.

All filters are ANDed; omitting every one of them matches every rule. Pagination is cursor-based: pass the previous response's `pagination.nextCursor` as `page.cursor`.

[Open in the interactive reference](https://docs.api.lensing.ai/?op=searchBankRule)

## 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`. |

## Request body

Required, `application/json`: searchBankRuleInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | no | Search filters, nested as one object so they map onto the POST body. All are optional and are ANDed; omitting every one of them matches all bank rules. Omit the whole object to do exactly that. |
| `filters.id` | string | no | Exact match on a rule's id (a UUID). This is how a single known rule is fetched. |
| `filters.rule` | string | no | Exact match on the rule's name. Names are unique, so this returns at most one match. |
| `filters.action` | string | no | Restrict to rules with this action. One of 'createBankEntry', 'createCreditCardEntry'; any other value yields an empty page. |
| `filters.status` | string | no | Restrict to rules of this status. One of 'active', 'inactive'; any other value yields an empty page. |
| `page` | object | no | Pagination controls. Omit for the first page. |
| `page.cursor` | string | no | Opaque forward cursor from a previous response's pagination.nextCursor; omit for the first page. Do not construct manually. |
| `page.size` | number | no | Maximum number of bank rules to return. Defaults to 50, capped at 200; the server may return fewer, but never more. |

Example:

```json
{
  "filters": {
    "status": "active"
  },
  "page": {
    "size": 25
  }
}
```

## Response

`200` Success

Under `data` (searchBankRuleOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes | Matching bank rules for this page, newest first. Empty when nothing matches. |
| `items[].id` | string | yes | Id of the bank rule (a UUID) — the public identifier of this record. |
| `items[].bankRuleNumber` | string | no | Human-readable document number assigned from the BankRule number range, e.g. BR-000014. |
| `items[].rule` | string | yes | Name of the rule. Unique across the tenant. |
| `items[].action` | string | yes | What the rule does when a transaction matches. One of 'createBankEntry', 'createCreditCardEntry'. |
| `items[].status` | string | yes | Whether the rule is in force. One of 'active', 'inactive'. Only an active rule can be run. |
| `items[].priority` | number | yes | Evaluation order relative to other rules; lower runs first. |
| `items[].description` | string | no | Free-text note on what the rule is for. |
| `items[].externalId` | string | no | External system identifier, when this rule was migrated from another system. |
| `items[].lastModifiedDate` | string (date-time) | yes | Instant the rule last changed, as ISO 8601 UTC (YYYY-MM-DDTHH:mm:ss.sssZ). |
| `items[].criteria` | array of object | yes | The conditions a bank transaction must meet, combined by each criterion's logicalOperator. Every rule has at least one. |
| `items[].criteria[].id` | string | yes | Id of the criterion row (a UUID). |
| `items[].criteria[].criteria` | string | yes | Which field of the transaction is tested. One of 'amount', 'description', 'payeePayor'. |
| `items[].criteria[].operator` | string | yes | How the field is compared. Numeric operators apply only to 'amount'; text operators only to 'description' and 'payeePayor'. |
| `items[].criteria[].logicalOperator` | string | no | How this criterion joins the next. One of 'and', 'or'. |
| `items[].criteria[].value` | string | yes | The value compared against. A decimal string for 'amount', free text otherwise. |
| `items[].accounts` | array of object | yes | The bank accounts this rule watches. Every rule has at least one, all belonging to one legal entity. |
| `items[].accounts[].id` | string | yes | Id of the mapping row (a UUID). |
| `items[].accounts[].bankAccountId` | string | yes | [fk: BankAccountApi.bankAccounts.id] The watched bank account, given as its id (a UUID). |
| `items[].accounts[].accountName` | string | no | Name of the bank account, denormalised for convenience. |
| `items[].actionObject` | object | no | The entry the rule creates when a transaction matches. |
| `items[].actionObject.id` | string | yes | Id of the action object (a UUID). |
| `items[].actionObject.accountId` | string | no | [fk: AccountApi.accounts.id] Account the created entry line books to, given as its id (a UUID). |
| `items[].actionObject.name` | string | no | Name stamped on the created entry. |
| `items[].actionObject.description` | string | no | Description stamped on the created entry and its line. |
| `items[].actionObject.billableExpense` | string | no | Whether the created credit card entry line is a billable expense. One of 'yes', 'no'. |
| `items[].actionObject.businessUnitId` | string | no | [fk: BusinessUnitApi.businessUnits.id] Business unit stamped on the created line, given as its id (a UUID). |
| `items[].actionObject.departmentId` | string | no | [fk: DepartmentApi.departments.id] Department stamped on the created line, given as its id (a UUID). |
| `items[].actionObject.customerId` | string | no | [fk: CustomerApi.customers.id] Customer stamped on the created line, given as its id (a UUID). |
| `items[].actionObject.vendorId` | string | no | [fk: VendorApi.vendors.id] Vendor stamped on the created line, given as its id (a UUID). |
| `items[].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. |
| `items[].actionObject.valueAllocationTags` | array of string | no | Value-allocation tag codes stamped on the created line. |
| `pagination` | object | yes | Cursor pagination for this result set. |
| `pagination.nextCursor` | string | no | Opaque cursor to pass as page.cursor for the next page; absent on the last page (mirrors the list/v1 data-set pagination.nextCursor). |
| `pagination.hasMore` | boolean | yes | True when more matches remain beyond this page (mirrors the list/v1 data-set pagination.hasMore). |

## Statuses

- `400` — Invalid request or business failure
- `401` — Missing or invalid access token
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests
- `500` — Internal server error