List Groups

A group is an arbitrary, organizational set of social accounts. Unlike a profile (at most one per account, meant to model a single brand across networks), a group is a free-form bag: an account can belong to many groups, and a group can hold any accounts — including several from the same network.

Groups are purely organizational. They are not wired into queues, posts, or contacts; use them to slice and filter accounts (for example in the UI, or via the ?group_id= filter on social accounts).

The group object

{
  "id": "grp_9aB8cD7eF6gH5iJ4kL3mN2oP1q",
  "name": "US Region",
  "description": "All US-facing accounts",
  "color": "#0ea5e9",
  "account_ids": ["sa_...", "sa_..."],
  "created_at": "2026-07-12T10:00:00.000Z",
  "updated_at": "2026-07-12T10:00:00.000Z"
}

GET/v1/groups

{ "groups": [ { "id": "grp_...", "name": "US Region", "account_ids": ["sa_..."], "...": "..." } ] }

Create Group

POST/v1/groups

Body parameters

Field	Type	Notes
`name`	string	Required
`description`	string	Optional
`color`	string	Optional hex color
`account_ids`	string[]	Optional initial members (`sa_` ids)

POST /v1/groups

curl -X POST https://api.socialit.com/v1/groups \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "US Region", "account_ids": ["sa_..."] }'

{ "group": { "id": "grp_...", "name": "US Region", "account_ids": ["sa_..."], "...": "..." } }

If any account_ids entry does not belong to your workspace the request fails with 400 InvalidAccount (the offending id is echoed back as account_id).

Get Group

GET/v1/groups/:id

{ "group": { "id": "grp_...", "name": "US Region", "account_ids": ["sa_..."], "...": "..." } }

Update Group

PATCH/v1/groups/:id

Update any of name, description, color. Passing account_ids replaces the group’s entire membership.

PATCH /v1/groups/:id

curl -X PATCH https://api.socialit.com/v1/groups/grp_... \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "account_ids": ["sa_a", "sa_b"] }'

{
  "group": {
    "id": "grp_...",
    "name": "US Region",
    "account_ids": [
      "sa_..."
    ],
    "...": "..."
  }
}

Delete Group

DELETE/v1/groups/:id

Accounts are not affected; only the group and its memberships are removed.

{ "ok": true }

List Members

Manage membership without replacing the whole set.

GET/v1/groups/:id/members

{ "account_ids": ["sa_...", "sa_..."] }

Add Member

POST/v1/groups/:id/members

Body parameters

Field	Type	Notes
`account_id`	string	Required (`sa_` id)

Idempotent — adding an existing member is a no-op. Returns the updated member list. Fails with 400 InvalidAccount if the account is not in your workspace.

POST /v1/groups/:id/members

curl -X POST https://api.socialit.com/v1/groups/grp_.../members \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "sa_..." }'

{ "account_ids": ["sa_...", "sa_..."] }

Remove Member

DELETE/v1/groups/:id/members/:account_id

{ "ok": true }