Groups

On this page we will look at the different group endpoints that you can use to manage groups programmatically. We will look at how to query, create, update and delete groups.

The group model

The group model contains all the information about your groups.

Groups are either static or dynamic. Dynamic groups are created in the dashboard with a filter, for example all contacts from a certain city or all contacts who replied within the last 30 days. Their members are determined automatically and recomputed right before every dispatch. You can use dynamic groups like any other group, for example as recipient, but you cannot add or remove members via the API.

Properties

Name
id
Type
integer
Description
Unique identifier of the group.
Name
name
Type
string
Description
The name of the group.
Name
members_count
Type
integer
Description
The number of contacts who are in this group.
Name
created
Type
timestamp
Description
The time the group was created.
Name
dynamic
Type
boolean
Description
true for dynamic groups whose members are derived from a filter. Their members cannot be changed via the API.

{
    "id": 17923,
    "name": "group1",
    "members_count": 543,
    "created": "2023-12-21 21:59:53",
    "dynamic": false
}

GET/api/groups

List all groups

This endpoint allows you to retrieve a paginated list of all your groups. By default, a maximum of ten groups are displayed per page.

Optional parameters

Name
limit
Type
integer
Description
Limit the number of groups returned.
Name
offset
Type
integer
Description
The starting point from which the list should be displayed.

Request

GET

/api/groups

curl -G https://gateway.seven.io/api/groups \
    -H "X-Api key: YOUR_API_KEY" \
    -d limit=10

Answer

{
    "pagingMetadata": {
        "offset": 0,
        "count": 4,
        "total": 40,
        "limit": 30,
        "has_more": false
    },
    "data": [
        {
            "id": 17923,
            "name": "Group 1",
            "members_count": 543,
            "created": "2023-12-21 21:59:53",
            "dynamic": false
        },
        {
            "id": 17924,
            // ...
        }
    ]
}

POST/api/groups

Create group

You can use this endpoint to create a new group.

Required parameters

Name
name
Type
string
Description
The name of the group

Request

POST

/api/groups

curl https://gateway.seven.io/api/groups \
    -H "X-Api key: YOUR_API_KEY" \
    -d "name=A new group"

Answer

{
    "id": 17923,
    "name": "A new group",
    "members_count": 0,
    "created": "2023-12-21 21:59:53",
    "dynamic": false
}

GET/api/groups/:id

Retrieve a group

You can use this endpoint to retrieve a group by specifying the group ID. You can see which properties belong to group objects in the list at the top of this page.

Request

GET

/api/groups/17923

curl https://gateway.seven.io/api/groups/17923 \
    -H "X-Api key: YOUR_API_KEY"

Response

{
    "id": 17923,
    "name": "A new group",
    "members_count": 0,
    "created": "2023-12-21 21:59:53",
    "dynamic": false
}

PATCH/api/groups/:id

Update a group

You can use this endpoint to update a group. You can change the name of the group.

Optional parameters

Name
name
Type
string
Description
The name of the group.

Request

PATCH

/api/groups/17923

curl -X PATCH https://gateway.seven.io/api/groups/17923 \
    -H "X-Api key: YOUR_API_KEY" \
    -d "name=New group name"

Answer

{
    "id": 17923,
    "name": "New group name",
    "members_count": 543,
    "created": "2023-12-21 21:59:53",
    "dynamic": false
}

DELETE/api/groups/:id

Delete group

This endpoint allows you to delete groups.

Optional parameters

Name
delete_contacts
Type
boolean
Description
Specifies whether the contacts who are members of this group should also be deleted. Not supported for dynamic groups.

Request

DELETE

/api/groups/17923

curl -X DELETE https://gateway.seven.io/api/groups/17923 \
    -H "X-Api key: YOUR_API_KEY" \
    -d "delete_contacts=false"