Social API reference

Social API · Actors

post/v1/communities/{community_id}/actors/by-external/batchAuth

Batch-resolve external_ids to actors (max 200 per call). POST-only — external_ids are up to 256 chars and can't ride a querystring. Unknown ids come back in `missing[]` instead of failing the call.

Path parameters

community_id*string

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

Request body

external_ids*array

external_ids to resolve, 1–200 items (POST body — 256-char ids can't ride a querystring). Duplicates are de-duplicated.

Example: ["user_abc123","user_def456"]

Response · 200 Actors found (request order, de-duplicated) plus the `missing[]` external_ids.

data*array

Actors found, in request order (after de-duplication).

missing*array

external_ids with no actor in this community.

Example: ["user_ghost"]

Example

Request

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

{
  "external_ids": [
    "user_abc123",
    "user_def456"
  ]
}

Response

{
  "data": [
    {
      "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "community_id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
      "external_id": "user_abc123",
      "display_name": "Ada Lovelace",
      "avatar_url": "https://cdn.example.com/avatars/ada.png",
      "metadata": {
        "tier": "pro"
      },
      "status": "active",
      "is_private": false,
      "created_at": "2026-05-01T12:00:00.000Z",
      "updated_at": "2026-05-01T12:00:00.000Z"
    }
  ],
  "missing": [
    "user_ghost"
  ]
}