# Batch Operations

`POST /api/batch`

Execute up to 50 operations in one request, in order, with continue-on-error. Operations use the same names, arguments and per-operation permission rules as the MCP tools (e.g. customers_create, invoices_get, leads_search). Each item returns status plus result or error, with completed/failed counters in the envelope.

- **Group:** Batch
- **Since:** v3.0.0
- **Authentication:** `authtoken` header, created under Setup > API > API Management
- **HTML version:** /apiguide/batch/batch-operations/

## Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `authtoken` | String | **required** | Authentication token, generated from admin area |

## Example request

```bash
curl -X POST "https://yoursite.com/api/batch" \
  -H "authtoken: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "field": "value" }'
```

## Success response

### Success-Response:

```json
HTTP/1.1 200 OK
{
  "status": true,
  "completed": 3,
  "failed": 0,
  "results": [
    {
      "index": 0,
      "tool": "customers_create",
      "status": true,
      "result": { "status": true, "record_id": 142 }
    },
    {
      "index": 1,
      "tool": "invoices_get",
      "status": true,
      "result": {
        "id": "5",
        "clientid": "142",
        "number": "1000",
        "prefix": "INV-",
        "date": "2026-07-21",
        "duedate": "2026-08-20",
        "currency": "1",
        "subtotal": "1200.00",
        "total_tax": "0.00",
        "total": "1200.00",
        "status": "1"
      }
    },
    {
      "index": 2,
      "tool": "leads_update",
      "status": true,
      "result": { "status": true, "record_id": 88 }
    }
  ]
}
```

### Partial-Failure-Response:

```json
HTTP/1.1 200 OK
{
  "status": false,
  "completed": 2,
  "failed": 1,
  "results": [
    {
      "index": 0,
      "tool": "customers_create",
      "status": true,
      "result": { "status": true, "record_id": 142 }
    },
    {
      "index": 1,
      "tool": "invoices_get",
      "status": false,
      "error": "Invoice not found"
    },
    {
      "index": 2,
      "tool": "leads_update",
      "status": true,
      "result": { "status": true, "record_id": 88 }
    }
  ]
}
```

## Error responses

### Validation-Error:

```json
HTTP/1.1 422 Unprocessable Entity
{
  "status": false,
  "error": "validation_failed",
  "message": "Batch validation failed",
  "errors": {
    "operations": "Provide an operations array: [{\"tool\": \"...\", \"arguments\": {...}}]"
  }
}
```

---

Perfex CRM REST API by Themesic Interactive. Full reference: /apiguide/