API reference

Segments

/groups

A segment is who a group-scoped event is about. A static segment keeps a list you add to; a dynamic segment holds whoever's attributes contain its filter, so nobody keeps it up. Beside the segments 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 Subscription business pack a segment is, for example, “Annual plans”.

GET/groupsList · ?q ?external_ref ?temporary POST/groupsCreateshown →GET/groups/{group_id}Read PATCH/groups/{group_id}Update · attributes replaced whole POST/groups/{group_id}/membersAdd members · up to 500 GET/groups/{group_id}/membersMembers · static DELETE/groups/{group_id}/members/{member_id}Remove a member POST/groups/syncBuild from an attribute GET/groups/{group_id}/matchesMatches · dynamic POST/groups/{group_id}/deactivateDeactivate · no delete

POSTCreate a segment

Requires groups:write. Makes a standing segment. 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

“Annual plans”. Unique in the instance.

kindstatic | dynamic · default static

member_kindsubject | contact · default subject

Whether it holds subscriptions or customers.

filterobject · optional

Required on a dynamic segment, refused on a static one. The attributes a member's must contain: {"plan": "Annual plans"}.

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

Generated from the Subscription business pack's group_schema. PATCH replaces the whole object; it does not merge.

KeyLabelKindAllowed valuesRequired

noteNotetext—No

ownerOwnertext—No

Returns

201 with the segment. 400 for a filter on a static segment, 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 segment: 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 subscriptions or customers. Fixed when it is made.

filterobject | nullA dynamic group's filter: the subscription or customer 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 Subscription business 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.

Previous← Authentication, keys and scopes NextEvent types →