API reference
Groups
/groups
A group is who a group-scoped event is about. A static group keeps a list you add to; a dynamic group holds whoever's attributes contain its filter, so nobody keeps it up. Beside the groups somebody keeps are temporary lists, picked by a person for one send: you can see them, but a key cannot change one and an event cannot name one. In the Standard lens a group is, for example, “Group A”.
POSTCreate a group
Requires groups:write. Makes a standing group. Static (the default) keeps a list: add to it with POST /groups/{group_id}/members. Dynamic takes a filter instead, checked against the pack's schema for what it holds, so a filter naming a key no record carries is refused rather than saved to reach nobody. member_kind is fixed here and never changes. Unknown keys — owner_user_id among them — are refused with 400.
Body parameters
namestring · required · max 200
“Group A”. Unique in the instance.
kindstatic | dynamic · default static
member_kindsubject | contact · default subject
Whether it holds subjects or contacts.
filterobject · optional
Required on a dynamic group, refused on a static one. The attributes a member's must contain: {"class": "Group A"}.
external_refstring · optional · max 200
Your own id for it. Trimmed as it is stored, and it is what ?external_ref= looks up exactly.
attributesobject · optionalVaries by pack
Checked against the instance's pack: its group_schema. Choose a pack to see the keys. PATCH replaces the whole object; it does not merge.
The Standard lens has no pack behind it, so there are no keys to list.
Returns
201 with the group. 400 for a filter on a static group, none on a dynamic one, or an attribute the pack refuses; the sentence names it. 409 if the name is taken, or the reference — “That reference is already used by another group. Find it with ?external_ref= and update that group instead.”
Response body
One group: the same fields in every pack. Press Response on the sample to see one whole.
FieldTypeDescription
iduuidWhat an event's group_id names.
namestringUnique in the instance.
kindstatic | dynamicstatic keeps a list; dynamic holds whoever matches its filter.
member_kindsubject | contactWhether it holds subjects or contacts. Fixed when it is made.
filterobject | nullA dynamic group's filter: the subject or contact attributes a member's must contain.Varies by pack
derived_fromstring | nullThe subject attribute a group the records keep up was built from. null on a group somebody keeps.
attributesobjectShaped by the instance's pack's group_schema.Varies by pack
temporarybooleantrue on a list somebody picked for a send. It cannot be named on an event, and a key cannot change it.
external_refstring | nullYour own id, as you sent it.
statusactive | inactive
created_atdatetime
updated_atdatetime
On failure the body is { error, code } instead.
