# Bulk Operations

Asynchronous batch jobs that act on many contacts at once (tag, untag, delete,
etc.). Differs from `POST /api/contacts/bulk` (synchronous delete-only) in two
ways: this runs in the background on the `bulk` queue, and supports more
actions with per-row failure tracking.

## Start a bulk operation

`POST /api/bulk-operations`

Enqueues the job and returns 202 with the operation record. Poll
`GET /api/bulk-operations/{id}` until `status=completed` or `failed`.

### Body parameters

- `action` (string, required) — Action to run (`tag`, `untag`, `delete`, etc. — see `BulkOperation::ACTIONS`).
- `payload` (object, required) — Action-specific payload. Must include `ids`.
  - `ids` (integer[], required) — Target contact IDs (min 1).
  - `tag_id` (integer) — Required for `tag`/`untag`.

### Example request

```bash
curl --request POST \
    "https://klozzo.com/api/bulk-operations" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"action\": \"tag\",
    \"payload\": {
        \"ids\": [
            42,
            43,
            44
        ],
        \"tag_id\": 3
    }
}"
```

### Response `202`

```json
{
    "id": 31,
    "action": "tag",
    "status": "pending",
    "total": 3,
    "processed": 0,
    "failed": 0,
    "progress": 0,
    "errors": null,
    "started_at": null,
    "finished_at": null,
    "created_at": "2026-06-05T13:42:00+00:00"
}
```

### Response `422` — An action that does not exist

```json
{
    "message": "Action no es una opción válida.",
    "errors": {
        "action": [
            "Action no es una opción válida."
        ]
    }
}
```

### Response `422` — No targets

```json
{
    "message": "Falta payload.ids.",
    "errors": {
        "payload.ids": [
            "Falta payload.ids."
        ]
    }
}
```

## Bulk operation status

`GET /api/bulk-operations/{bulkOperation_id}`

Returns the current state of a bulk operation. `progress` is `(processed /
total) * 100` rounded. `errors` is populated per-row when individual rows
fail (the job continues; only `status=failed` indicates a global failure).

### Path parameters

- `bulkOperation_id` (integer, required) — Bulk operation ID.

### Example request

```bash
curl --request GET \
    --get "https://klozzo.com/api/bulk-operations/31" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
```

### Response `200`

```json
{
    "id": 31,
    "action": "tag",
    "status": "processing",
    "total": 3,
    "processed": 2,
    "failed": 0,
    "progress": 66,
    "errors": null,
    "started_at": "2026-06-05T13:42:01+00:00",
    "finished_at": null,
    "created_at": "2026-06-05T13:42:00+00:00"
}
```

### Response `404` — Does not exist, or belongs to another location

```json
{
    "message": "No query results for model."
}
```