Participant groups

Participant groups let your organisation group participants together (for example by house, program, or cohort). On this page we'll look at the participant group model and how to page through every group in your organisation. Listing participant groups requires the read:participant_groups scope.

The participant group model

The participant group model contains the core details of a group in your organisation.

Properties

Name
object
Type
string
Description
The object type. Always participant_group.
Name
id
Type
integer
Description
Unique identifier for the group within your organisation.
Name
name
Type
string
Description
The group's name.
Name
livemode
Type
boolean
Description
true when the object was returned by a live-mode key (ds_live_…), false in test mode.

GET/v1/participant-groups

List participant groups

Returns a paginated list of the participant groups in your organisation, ordered by name. Requires the read:participant_groups scope.

The response is the standard list envelope: an object of list, the url of the resource, a has_more flag, and a data array of participant group objects.

Optional attributes

Name
limit
Type
integer
Description
The number of objects to return, 1–100. Defaults to 25.
Name
starting_after
Type
integer
Description
A cursor for pagination. Pass the id of the last participant group from the previous page to fetch the next page.

Every response includes a Request-Id header — quote it to support when reporting a problem — along with Diversity-Sync-Version: v1 and the RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers.

Request

GET

/v1/participant-groups

curl -G https://api.diversitysync.com/v1/participant-groups \
  -H "Authorization: Bearer {access_token}" \
  -d limit=2

Response

{
  "object": "list",
  "url": "/v1/participant-groups",
  "has_more": true,
  "data": [
    {
      "object": "participant_group",
      "id": 4,
      "name": "Day Program",
      "livemode": true
    },
    {
      "object": "participant_group",
      "id": 9,
      "name": "Lakeside Cohort",
      "livemode": true
    }
  ]
}

GET/v1/participant-groups

Paginate through every group

The list is cursor-paginated. While has_more is true, request the next page by passing the id of the last group you saw as starting_after. Stop when has_more is false.

Request

GET

/v1/participant-groups

curl -G https://api.diversitysync.com/v1/participant-groups \
  -H "Authorization: Bearer {access_token}" \
  -d limit=2 \
  -d starting_after=9

Response

{
  "object": "list",
  "url": "/v1/participant-groups",
  "has_more": false,
  "data": [
    {
      "object": "participant_group",
      "id": 12,
      "name": "Weekend Respite",
      "livemode": true
    }
  ]
}