Collaborator Groups (REST)

A collaborator group is a named cluster of collaborators with an associated structure: flat, linear chain, or parent-child tree. Programs and distributors bind to a group so that calculation strategies can walk it and produce cascade payouts. For the operator-facing overview, see What are collaborator groups. This page is the REST reference: the wire shape of each resource, the endpoints that read and mutate them, and how a program or distributor gets bound to a group.

Data shape

CollaboratorGroup

Field	Type	Description
`id`	integer	Primary key.
`name`	string	Display name.
`description`	string	Free-form description. Empty string when not set.
`structure`	string	Registered structure resolver id. Today’s values: `flat`, `linearChain`, `parentChild`. See the structure picker guide.

The read endpoints (GET /collaborator-groups and GET /collaborator-groups/{id}) select fields through the resolver and expose only the four fields above. The record also carries dateCreated and dateModified timestamps. Those are not retrievable through the read endpoints, but the create response (POST /collaborator-groups) does return them.

linearChain and parentChild require the Pro tier. Plus ships flat only, so a Plus-only install exposes flat as the only available structure value.

CollaboratorGroupMember

Field	Type	Description
`id`	integer	Primary key.
`groupId`	integer	The parent group’s id.
`collaboratorId`	integer	The collaborator’s id.
`metadata`	object	Structure-specific data. Always serialized as a JSON object, even when empty (`{}`).
`dateCreated`	datetime	When the membership row was created.
`dateModified`	datetime	When the membership row was last updated.
`collaboratorName`	string	The collaborator’s name, joined from the collaborator record. Read-only convenience field, so you can render a member without a second lookup.
`collaboratorEmail`	string	The collaborator’s email, joined from the collaborator record. Read-only convenience field.
`collaboratorStatus`	string	The collaborator’s status (for example `active`), joined from the collaborator record. Read-only convenience field.

The metadata object’s keys depend on the parent group’s structure:

flat: empty object. The flat resolver ignores all metadata. Every member is a peer.
linearChain: { "position": <int> }. Smaller positions sit higher in the chain. Members with missing or non-numeric positions are treated as position 0.
parentChild: { "parentCollaboratorId": <int|null> }. The collaborator id of this member’s direct upline. Null (or a pointer that doesn’t match a member of the group) means this member is a root of the tree.

Switching a group’s structure does not migrate per-member metadata. Resolvers tolerate unknown keys. Switching from linearChain back to flat leaves position values in place, and they’re simply ignored.

REST endpoints

Method and path	What it does
`GET /collaborator-groups`	Lists groups. The `fields` query parameter is required.
`GET /collaborator-groups/{id}`	Reads one group.
`POST /collaborator-groups`	Creates a group, optionally with an initial `members` array.
`PUT /collaborator-groups/{id}`	Updates `name`, `description`, or `structure`. Member changes do not go through this endpoint.
`DELETE /collaborator-groups/{id}`	Deletes the group and cascades its member rows. Does not detach program or distributor bindings, which then point at a missing group.
`GET /collaborator-groups/{id}/members`	Lists the members of one group.
`POST /collaborator-groups/{id}/members`	Bulk-adds members. Collaborators already in the group are skipped.
`PUT /collaborator-groups/{id}/members`	Full-replaces the roster, reconciling the submitted list against the current one.
`DELETE /collaborator-groups/{id}/members/{collaboratorId}`	Removes one member. Returns 204, or 404 when the membership row does not exist.
`GET /collaborator-groups/structures`	Lists the installed structure resolvers and the walker capabilities each advertises.

All of these require the Update capability on CollaboratorGroup, held by the administrator and siren_platform_manager roles. See the individual endpoint pages in the sidebar for full request and response details, or browse the all REST endpoints reference.

Binding a program or distributor

A program or distributor does not store its collaborator-group association on its own row. The binding lives in the shared wp_siren_configs table, keyed by:

Programs: (type='program', subtype=<programId>, configKey='collaboratorGroupId')
Distributors: (type='distributor', subtype=<distributorId>, configKey='collaboratorGroupId')

You set the binding by including collaboratorGroupId in the body of a POST or PUT against the program or distributor itself. There is no separate binding endpoint:

PUT /programs/{id}

{
  "collaboratorGroupId": 12
}

A listener on the program/distributor action event writes the config row and broadcasts a ProgramBoundToCollaboratorGroup (or DistributorBoundToCollaboratorGroup) event. Passing null, "", or 0 clears the binding. Each program or distributor can be bound to at most one collaborator group.

Once bound, the upline cascade and downline cascade calcs walk the group on every qualifying engagement.

Data shape