Social API reference

Social API · Lists

post/v1/communities/{community_id}/lists/{list_id}/membersAuth

Add a member to a list. Owner-only.

Path parameters

community_id*string

Social community UUID.

list_id*string

List UUID.

Headers

Idempotency-Keystring

Opaque client-generated string (1-256 chars, `[A-Za-z0-9._:-]`) that makes a retry safe: within 24 h a repeat with the same key and body returns the original response with `Idempotent-Replay: true` instead of running again. Same key with a different body is `409 IDEMPOTENCY_KEY_REUSE`.

Request body

actor_id*string · uuid

The acting actor (the list owner). In the deprecated shape that sends `caller_actor_id`, this is the actor being added.

Example: "aaaaaaaa-0000-0000-0000-000000000001"

member_actor_idstring · uuid

The actor being added. Required unless you send the deprecated `caller_actor_id` shape.

Example: "aaaaaaaa-0000-0000-0000-000000000002"

caller_actor_idstring · uuid

Deprecated: the caller in the old shape (`caller_actor_id` + `actor_id` as the member). Send `actor_id` + `member_actor_id`.

Example: "aaaaaaaa-0000-0000-0000-000000000001"

Response · 201 Member added (or returned via idempotent retry).

list_id*string · uuid

Owning list UUID.

Example: "11111111-0000-0000-0000-000000000001"

actor_id*string · uuid

Member actor UUID.

Example: "aaaaaaaa-0000-0000-0000-000000000002"

community_id*string · uuid

Owning community UUID.

Example: "cccccccc-cccc-cccc-cccc-cccccccccccc"

added_at*string · date-time

ISO timestamp.

Example: "2026-05-01T12:00:00.000Z"

Example

Request

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

{
  "actor_id": "aaaaaaaa-0000-0000-0000-000000000001",
  "member_actor_id": "aaaaaaaa-0000-0000-0000-000000000002",
  "caller_actor_id": "aaaaaaaa-0000-0000-0000-000000000001"
}

Response

{
  "list_id": "11111111-0000-0000-0000-000000000001",
  "actor_id": "aaaaaaaa-0000-0000-0000-000000000002",
  "community_id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
  "added_at": "2026-05-01T12:00:00.000Z"
}