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 Political party pack a group is, for example, “Montserrado County”.

GET/groupsList · ?q ?external_ref ?temporaryshown →POST/groupsCreate 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

GETList groups

Requires groups:read. Returns a bare JSON array, by name. Temporary lists are left out unless you ask for them with temporary=true: an event cannot name one, so a system choosing a group_id is better off never seeing them.

Query parameters

limitinteger · default 50 · max 200

offsetinteger · default 0

qstring · optional · max 100

Matches the name. It is a search, not a lookup, so it cannot be combined with external_ref.

kindstatic | dynamic · optional

derivedboolean · optional

true for the groups Raven keeps up from membership attributes; false for the ones somebody keeps.

statusactive | inactive · optional

temporaryboolean · default false

true gives the lists people picked for sends instead.

external_refstring · optional · max 200

Your own id for the group, looked up exactly: an array of one, or an empty one. It is how a system finds the group it made after somebody here has renamed it. Refused with 400 alongside q: search, or look up.

Returns

200 with an array of groups. An empty array when nothing matches.

Response body

A bare JSON array. Each item is 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 memberships or people. Fixed when it is made.

filterobject | nullA dynamic group's filter: the membership or person 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 Political party 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 →