Docs/Workspace API/Batch

Batch operations

Send up to 100 operations in a single request. Business-logic failures (not-found, duplicate) land in each item's own result — a bad item doesn't block the 99 good ones. Modeled on the HubSpot batch pattern.

Endpoints

Resource	Path	Methods supported	Required scope
Contacts	POST /contacts/batch	create, update, upsert	crm.contacts.write
Companies	POST /companies/batch	create, update, upsert	crm.companies.write
Deals	POST /deals/batch	create, update	crm.deals.write
Invoices	POST /invoices/batch	create, update	sales.invoices.write
Workorders	POST /workorders/batch	create, update	operations.workorders.write

How it works

Max 100 operations per request. 101+ returns 400 VALIDATION_ERROR.
Mixed operations are allowed — mix create, update and (where supported) upsert in the same call.
Schema validation is strict upfront. If any item's data payload violates the resource schema (e.g. invalid email), the whole batch returns 400. This protects you from partially-processed batches where some items passed a payload typo.
Business-logic failures are per-item. If item 3 tries to update a deleted record, item 3 lands with status: 404 in the results array; items 1-2 and 4-100 still succeed.
Scopes — the API-key must carry the write scope for the resource. Delete is NOT batched (use bulk-delete).
Idempotency — set an Idempotency-Key header. Replay with the same key + body returns the cached batch result.

Example

curl -X POST https://app.staffifyai.com/api/workspace/v1/contacts/batch \
  -H "Authorization: Bearer $STAFFIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      { "method": "create", "data": { "first_name": "Alice", "email": "[email protected]" } },
      { "method": "update", "id": 42, "data": { "job_title": "CEO" } },
      {
        "method": "upsert",
        "match_on": "email",
        "match_value": "[email protected]",
        "data": { "first_name": "Bob", "last_name": "Builder" }
      }
    ]
  }'

Response

{
  "object": "batch_result",
  "summary": { "total": 3, "succeeded": 2, "failed": 1 },
  "results": [
    { "index": 0, "method": "create", "status": 201, "data": { "object": "contact", "id": 101, ... } },
    { "index": 1, "method": "update", "status": 404, "error": {
        "type": "invalid_state",
        "code": "NOT_FOUND",
        "message": "Contact 42 not found"
    }},
    { "index": 2, "method": "upsert", "status": 200, "data": { ..., "_upserted": { "matched": true } } }
  ],
  "meta": { "request_id": "req_abc123" }
}

Errors

400 VALIDATION_ERROR — any item failed schema validation (whole-batch reject).
400 VALIDATION_ERROR — operations empty or >100 items.
403 — API-key lacks the required write scope.
409 IDEMPOTENCY_KEY_CONFLICT — same key used with a different body.