# Rules

> Rules that act on bank transactions when their conditions match.

Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer <API key or access token>`.

## List rules

`GET /api/public/v1/rules`

SDK: `prosaic.rules.list(params)`

Returns rules in the workspace associated with the API key. By default returns only active rules.

### Query parameters

- `isActive` (string): Filter rules by active status. `true` (default) returns only active rules, `false` returns only inactive rules, `all` returns both. . One of: `all`, `false`, `true`.
- `entityId` (string): Only rules whose scope reaches this entity: workspace-wide rules, rules on the entity's chart template, rules on the entity itself, and rules on any of its bank accounts. .
- `page` (integer): Default: `1`.
- `pageSize` (integer): Default: `50`.

### Responses

- `200`: Successful response
  - `data` (array of objects, required)
    - `id` (string, required)
    - `name` (string, required)
    - `description` (string, nullable, required)
    - `isActive` (boolean, required)
    - `targetType` (string, required)
    - `createdAt` (string, date-time, required)
    - `updatedAt` (string, date-time, required)
    - `conditions` (array of objects, required)
      - `id` (string, required)
      - `field` (string, required)
      - `operator` (string, required)
      - `value` (string, required)
      - `secondValue` (string, nullable, required)
    - `actions` (array of objects, required)
      - `id` (string, required)
      - `actionType` (string, required)
      - `payload` (any, required)
    - `scopes` (array of objects, required)
      - `id` (string, required)
      - `scopeType` (string, required)
      - `entity` (object, nullable, required)
        - `id` (string, required)
        - `name` (string, required)
      - `bankAccount` (object, nullable, required)
        - `id` (string, required)
        - `name` (string, required)
      - `accountTemplate` (object, nullable, required)
        - `id` (string, required)
        - `name` (string, required)
  - `pagination` (object, required)
    - `currentPage` (number, required)
    - `pageSize` (number, required)
    - `totalCount` (number, required)
    - `totalPages` (number, required)
    - `hasNextPage` (boolean, required)
    - `hasPreviousPage` (boolean, required)
- `400`: Validation failed
- `401`: Unauthorized
- `403`: Insufficient role
- `404`: Workspace not found, or entityId is not in the workspace
- `500`: Internal server error

### Example (Node SDK)

```ts
const page = await prosaic.rules.list();
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/rules \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## Get a rule by ID

`GET /api/public/v1/rules/{ruleId}`

SDK: `prosaic.rules.retrieve(ruleId)`

### Path parameters

- `ruleId` (string, required)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `id` (string, required)
    - `name` (string, required)
    - `description` (string, nullable, required)
    - `isActive` (boolean, required)
    - `targetType` (string, required)
    - `createdAt` (string, date-time, required)
    - `updatedAt` (string, date-time, required)
    - `conditions` (array of objects, required)
      - `id` (string, required)
      - `field` (string, required)
      - `operator` (string, required)
      - `value` (string, required)
      - `secondValue` (string, nullable, required)
    - `actions` (array of objects, required)
      - `id` (string, required)
      - `actionType` (string, required)
      - `payload` (any, required)
    - `scopes` (array of objects, required)
      - `id` (string, required)
      - `scopeType` (string, required)
      - `entity` (object, nullable, required)
        - `id` (string, required)
        - `name` (string, required)
      - `bankAccount` (object, nullable, required)
        - `id` (string, required)
        - `name` (string, required)
      - `accountTemplate` (object, nullable, required)
        - `id` (string, required)
        - `name` (string, required)
- `400`: Invalid rule ID
- `401`: Unauthorized
- `403`: Insufficient role
- `404`: Rule or workspace not found
- `500`: Internal server error

### Example (Node SDK)

```ts
const { data } = await prosaic.rules.retrieve(ruleId);
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/rules/$RULE_ID \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## Create a rule

`POST /api/public/v1/rules`

SDK: `prosaic.rules.create(params)`

Creates a new rule in the workspace associated with the API key.

### Request body

Content type: `application/json`

- `name` (string, required)
- `conditions` (array of objects, required)
  - `field` (string, required): One of: `description`, `type`, `date`, `amount`, `category`, `merchant`.
  - `operator` (string, required): One of: `endsWith`, `startsWith`, `is`, `equals`, `gte`, `contains`, `gt`, `lt`, `lte`, `between`.
  - `value` (string, required)
  - `secondValue` (string, nullable)
- `actions` (array of objects, required)
  - `actionType` (string, required): One of: `post_journal`, `tag_dimensions`.
  - `payload` (any, required)
- `scopes` (array of objects, required)
- `description` (string, nullable)
- `isActive` (boolean)
- `targetType` (string): One of: `bank_transaction`.
- `source` (string): One of: `ai`, `manual`, `duplicate`, `transactions_filters`, `transactions_reconcile`, `dimension_proposal`, `demo_seed`.

### Responses

- `201`: Successful response
  - `data` (object, required)
    - `id` (string, required)
    - `name` (string, required)
    - `description` (string, nullable, required)
    - `isActive` (boolean, required)
    - `targetType` (string, required)
    - `createdAt` (string, date-time, required)
    - `updatedAt` (string, date-time, required)
    - `conditions` (array of objects, required)
      - `id` (string, required)
      - `field` (string, required)
      - `operator` (string, required)
      - `value` (string, required)
      - `secondValue` (string, nullable, required)
    - `actions` (array of objects, required)
      - `id` (string, required)
      - `actionType` (string, required)
      - `payload` (any, required)
    - `scopes` (array of objects, required)
      - `id` (string, required)
      - `scopeType` (string, required)
      - `entity` (object, nullable, required)
        - `id` (string, required)
        - `name` (string, required)
      - `bankAccount` (object, nullable, required)
        - `id` (string, required)
        - `name` (string, required)
      - `accountTemplate` (object, nullable, required)
        - `id` (string, required)
        - `name` (string, required)
- `400`: Validation failed. Covers both shape errors (missing/invalid fields)
and action-payload semantic errors caught by the request schema
(e.g. proportion lines must sum to 1).

- `401`: Unauthorized
- `403`: Insufficient role
- `404`: Workspace not found
- `422`: Rule failed service-level validation against workspace data
(e.g. unknown tax rate codes, account codes not allowed by the
action type). Distinct from 400, which is raised by the request
schema before the service is called.

- `500`: Internal server error

### Example (Node SDK)

```ts
const { data } = await prosaic.rules.create({
  name: 'Example Ltd',
  conditions: [
    {
      field: 'description',
      operator: 'endsWith',
      value: 'string',
    },
  ],
  actions: [
    {
      actionType: 'post_journal',
      payload: 'string',
    },
  ],
  scopes: [
    {
      scopeType: 'workspace',
    },
  ],
});
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/rules \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Ltd",
    "conditions": [
      {
        "field": "description",
        "operator": "endsWith",
        "value": "string"
      }
    ],
    "actions": [
      {
        "actionType": "post_journal",
        "payload": "string"
      }
    ],
    "scopes": [
      {
        "scopeType": "workspace"
      }
    ]
  }'
```

## Update a rule

`PATCH /api/public/v1/rules/{ruleId}`

SDK: `prosaic.rules.update(ruleId, params)`

### Path parameters

- `ruleId` (string, required)

### Request body

Content type: `application/json`

- `name` (string)
- `description` (string, nullable)
- `isActive` (boolean)
- `conditions` (array of objects)
  - `field` (string, required): One of: `description`, `type`, `date`, `amount`, `category`, `merchant`.
  - `operator` (string, required): One of: `endsWith`, `startsWith`, `is`, `equals`, `gte`, `contains`, `gt`, `lt`, `lte`, `between`.
  - `value` (string, required)
  - `secondValue` (string, nullable)
- `targetType` (string): One of: `bank_transaction`.
- `actions` (array of objects)
  - `actionType` (string, required): One of: `post_journal`, `tag_dimensions`.
  - `payload` (any, required)
- `scopes` (array of objects)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `id` (string, required)
    - `name` (string, required)
    - `description` (string, nullable, required)
    - `isActive` (boolean, required)
    - `targetType` (string, required)
    - `createdAt` (string, date-time, required)
    - `updatedAt` (string, date-time, required)
    - `conditions` (array of objects, required)
      - `id` (string, required)
      - `field` (string, required)
      - `operator` (string, required)
      - `value` (string, required)
      - `secondValue` (string, nullable, required)
    - `actions` (array of objects, required)
      - `id` (string, required)
      - `actionType` (string, required)
      - `payload` (any, required)
    - `scopes` (array of objects, required)
      - `id` (string, required)
      - `scopeType` (string, required)
      - `entity` (object, nullable, required)
        - `id` (string, required)
        - `name` (string, required)
      - `bankAccount` (object, nullable, required)
        - `id` (string, required)
        - `name` (string, required)
      - `accountTemplate` (object, nullable, required)
        - `id` (string, required)
        - `name` (string, required)
- `400`: Validation failed. Covers both shape errors (missing/invalid fields)
and action-payload semantic errors caught by the request schema
(e.g. proportion lines must sum to 1).

- `401`: Unauthorized
- `403`: Insufficient role
- `404`: Rule or workspace not found
- `422`: Rule failed service-level validation against workspace data
(e.g. unknown tax rate codes, account codes not allowed by the
action type). Distinct from 400, which is raised by the request
schema before the service is called.

- `500`: Internal server error

### Example (Node SDK)

```ts
const { data } = await prosaic.rules.update(ruleId, {
  name: 'Example Ltd',
  description: 'Office supplies',
  isActive: true,
  conditions: [
    {
      field: 'description',
      operator: 'endsWith',
      value: 'string',
    },
  ],
  targetType: 'bank_transaction',
  actions: [
    {
      actionType: 'post_journal',
      payload: 'string',
    },
  ],
  scopes: [
    {
      scopeType: 'workspace',
    },
  ],
});
```

### Example (curl)

```bash
curl -X PATCH https://app.prosaic.works/api/public/v1/rules/$RULE_ID \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Ltd",
    "description": "Office supplies",
    "isActive": true,
    "conditions": [
      {
        "field": "description",
        "operator": "endsWith",
        "value": "string"
      }
    ],
    "targetType": "bank_transaction",
    "actions": [
      {
        "actionType": "post_journal",
        "payload": "string"
      }
    ],
    "scopes": [
      {
        "scopeType": "workspace"
      }
    ]
  }'
```

## Soft-delete a rule

`DELETE /api/public/v1/rules/{ruleId}`

SDK: `prosaic.rules.del(ruleId)`

### Path parameters

- `ruleId` (string, required)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `success` (boolean, required): One of: `true`.
- `400`: Invalid rule ID
- `401`: Unauthorized
- `403`: Insufficient role
- `404`: Rule or workspace not found
- `500`: Internal server error

### Example (Node SDK)

```ts
const { data } = await prosaic.rules.del(ruleId);
```

### Example (curl)

```bash
curl -X DELETE https://app.prosaic.works/api/public/v1/rules/$RULE_ID \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```