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.

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.

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

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"
    },
    {
      "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"
}

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",
}

PATCH/api/groups/:id

Update a group

You can use this endpoint to update a group. Examples of updates include changing the name, description and avatar or adding and removing contacts from 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"
}

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.

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"