# Act on many records at once — by filter or by ids

THE bulk door: export, move, copy, update, set a status, assign, archive, convert, analyse or delete EVERY record on a page (leads, deals, merchants… or a board by its board-… key) that matches a filter — or the records named in `ids` — in one call. The filter is the grid's own, so what the grid lists for it is exactly what is acted on. Reach for it on any 'export everyone with status X', 'move all leads tagged Y to the hot leads board' or 'mark these five deals …' ask instead of reading rows and acting one at a time. Body: {filter: {q, filters, groupId, sort, dir} OR ids: [row ids], action, target?, cells?, status?, note?, role?, assignee?, dryRun?} — ids and a filter together are refused; an id that names nothing you can see is in `skipped`. `filters` maps a column — its id (get_definitions_key answers the columns) or its label — to the values to keep: the Status column `c1` → `{"filters": {"c1": ["new"]}}`; a status or select takes its value or its label, a person column a name or email, '' is a blank cell, several values are OR and several columns AND; a computed column (formula, lookup, a record's `documents`: missing, requested or complete) filters like a stored one — `{"filters": {"Documents": ["missing"]}}` is every record still owed a paper; `q` searches every cell; `groupId` keeps one record group; no filter is the whole page. `export` writes a CSV of the matches in the words the grid draws (names, labels — never ids) and answers `file: {id, name, url}`: give the person that link. `move` and `copy` take `target: {boardId}` or `{key}` and carry each cell into the target's column of the same name and kind; a move takes a record whole or leaves it where it is (a record with files, calls or documents attached stays — copy it instead), and every record left behind is in `skipped` with the reason. `update` takes `cells: {column name or id: value}` and sets it on every match. `copy` with the page's own key as the target duplicates the records. `status` takes `status` (a value or a label; a word the page does not have is refused whole, naming the real ones) and an optional `note` filed with each move — a deal moves through its stage engine, so a deal its gate refuses is skipped with why. `assign` takes `role` (one of the page's assignable roles) and `assignee` (a member's account id; empty clears the role). `convert` makes a deal of each lead (leads only; a lead converted before is skipped, naming its deal). `analyze` sends every document on each record for analysis and counts documents in `affected`. `archive` retires them (reactivate brings one back); `delete` is permanent. Send `dryRun: true` FIRST for move, update, status, assign, archive and delete: it writes nothing and answers how many match, the first names in `preview` and a move's column `plan` — tell the person, then make the real call. Answers {action, matched, affected, skipped: [{rowId or column, reason}], preview?, plan?, file?}: `affected` is how many changed. Above 5000 matches it is refused — narrow the filter. Money boards (ledger views) are refused. Any member exports; every other action needs write on the page and on the target. The custom-board twin is `post_boards_id_rows_act`.

Access class: `def:read`.

## Endpoint

`POST /v1/definitions/{key}/rows/act`

## Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| key | path | string | Yes |

## Request body

Content type: `application/json`.

```json
{
  "action": "string",
  "assignee": "string",
  "cells": {},
  "dryRun": true,
  "filter": {
    "dir": "string",
    "filters": {},
    "groupId": "",
    "q": "string",
    "sort": "string"
  },
  "ids": [
    "string"
  ],
  "note": "string",
  "role": "string",
  "status": "string",
  "target": {
    "boardId": "",
    "key": "string"
  }
}
```

## Responses

### 201

the action's answer

Content type: `application/json`.

```json
{
  "data": {
    "action": "string",
    "affected": 1.5,
    "dryRun": true,
    "file": {
      "id": "",
      "name": "string",
      "url": "string"
    },
    "matched": 1.5,
    "plan": {
      "mappings": [
        "string"
      ],
      "unmapped": [
        "string"
      ],
      "warnings": [
        "string"
      ]
    },
    "preview": [
      "string"
    ],
    "skipped": [
      "string"
    ]
  }
}
```

### default

a refusal: `{"error": "<what a person needs to read>"}`. 401 no credential, 402 the plan does not include this, 403 the seat does not, 404 the thing does not exist or is not yours to see.

Content type: `application/json`.

```json
{
  "error": "string"
}
```
