Batch Operations

Overview

The Batch API endpoint allows you to submit up to 100 Public Data API operations in a single HTTP request. This reduces network overhead and latency when you need to fetch or modify multiple resources at once.

Each operation is processed independently — the response contains per-item success/failure results so you can handle partial failures gracefully.

Batch requests are rate-limited as a single request against your per-key limit. This makes batches ideal for clients that need to make many calls in a short window.

Endpoint

POST /api/v1/public/data/batch

Authentication

Same as the single-operation endpoint — include your API key in the X-API-Key header.

Request Format

{
  "operations": [
    {
      "id": "users",
      "action": "get-active-users",
      "params": { "status": "active" }
    },
    {
      "id": "jobs",
      "action": "list-work-items",
      "params": { "item_type": "job", "limit": 10 }
    },
    {
      "id": "contacts",
      "action": "list-contacts",
      "params": { "contact_type": "customer", "limit": 5 }
    }
  ]
}

Fields

Field	Type	Required	Description
`operations`	array	Yes	Array of operation objects (1–100 items)
`operations[].id`	string	No	Client-generated ID for correlating results. Auto-generated as `op-N` if omitted.
`operations[].action`	string	Yes	Any valid Public Data API action
`operations[].params`	object	No	Parameters object passed to the action

Response Format

{
  "success": true,
  "data": {
    "results": [
      {
        "id": "users",
        "success": true,
        "status": 200,
        "data": {
          "users": [...],
          "count": 15
        }
      },
      {
        "id": "jobs",
        "success": true,
        "status": 200,
        "data": {
          "work_items": [...],
          "count": 10
        }
      },
      {
        "id": "contacts",
        "success": false,
        "status": 403,
        "error": "API key lacks contacts:read scope"
      }
    ],
    "succeeded": 2,
    "failed": 1,
    "total": 3
  },
  "meta": {
    "api_version": "2026-07-01"
  }
}

The top-level success field is always true when the batch itself is processed successfully. Check each operation's success field to determine individual outcomes.

Idempotency

Batch requests support batch-level idempotency via the Idempotency-Key header. If the same key is sent again with the same request body, the cached batch response is returned. This is useful for retrying failed network requests without risk of duplicate side effects.

curl -X POST https://dev-next.totalaccess.co.za/api/v1/public/data/batch \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      { "id": "emp-1", "action": "get-employees", "params": { "limit": 50 } },
      { "id": "att-1", "action": "get-attendance-logs", "params": { "limit": 100 } },
      { "id": "ts-1",  "action": "get-timesheets", "params": { "status": "approved" } }
    ]
  }'

Node.js

const response = await fetch('https://dev-next.totalaccess.co.za/api/v1/public/data/batch', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.TOTALACCESS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    operations: [
      { id: 'users', action: 'get-active-users', params: { status: 'active' } },
      { id: 'jobs', action: 'list-work-items', params: { item_type: 'job', limit: 10 } },
    ],
  }),
});

const result = await response.json();

for (const op of result.data.results) {
  if (op.success) {
    console.log(`[${op.id}] OK:`, op.data);
  } else {
    console.error(`[${op.id}] Failed (${op.status}):`, op.error);
  }
}

Python

import requests

response = requests.post(
    "https://dev-next.totalaccess.co.za/api/v1/public/data/batch",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json",
    },
    json={
        "operations": [
            {"id": "users", "action": "get-active-users", "params": {"status": "active"}},
            {"id": "jobs", "action": "list-work-items", "params": {"item_type": "job", "limit": 10}},
        ],
    },
)

result = response.json()
for op in result["data"]["results"]:
    if op["success"]:
        print(f"[{op['id']}] OK: {op['data']}")
    else:
        print(f"[{op['id']}] Failed ({op['status']}): {op['error']}")

Limitations

Maximum 100 operations per batch request
Each operation is processed independently — there is no cross-operation transaction support
All operations share the same API key and its associated scopes
Operations are executed in parallel — order of results may not match input order (use the id field to correlate)