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"