Social API reference

Social API · Actors

post/v1/communities/{community_id}/actors/batchAuth

Bulk actor upsert (max 200 per call) — the import lane. Each item runs the exact single-upsert path; results come back per item with partial success (`201` even when some items fail — inspect `success` / `error` per entry). No wrapping transaction.

Path parameters

community_id*string

Social community UUID. Must belong to the PAK's workspace.

Request body

actors*array

Actors to upsert, in order. 1–200 items; each item follows the single-upsert body exactly.

Response · 201 Per-item results, request order. `succeeded` + `failed` summarise the batch.

data*array

One result per input item, same order.

succeeded*number

Count of successful items.

Example: 199

failed*number

Count of failed items.

Example: 1

Example

Request

POST https://social.productcraft.co/v1/communities/{community_id}/actors/batch
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "actors": [
    {
      "external_id": "user_abc123",
      "display_name": "Ada Lovelace",
      "avatar_url": "https://cdn.example.com/avatars/ada.png",
      "metadata": {
        "tier": "pro"
      }
    }
  ]
}

Response

{
  "data": [
    {
      "index": 0,
      "success": true,
      "actor": {},
      "created": true,
      "error": {}
    }
  ],
  "succeeded": 199,
  "failed": 1
}