---
title: "Managing Groups with the REST API"
slug: "managing-groups-with-the-engage-rest-api"
description: "Manage your groups programmatically with our API: list, check lock status, and delete groups efficiently. Unlock powerful group management today!"
tags: ["Group Management", "API Endpoints", "Group Deletion"]
updated: 2026-09-23T07:51:55Z
published: 2026-09-23T07:51:55Z
canonical: "docs.mapp.com/managing-groups-with-the-engage-rest-api"
stale: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Groups with the REST API

## Overview

Three endpoints let you work with groups programmatically: you can list the groups of your customer account, check whether a group is currently locked by a running operation, and delete groups.

| Endpoint | Purpose |
| --- | --- |
| **GET /group/find** | Returns a paginated list of groups with filtering and sorting. |
| **GET /group/getLockStatus** | Returns the lock status of a single group. |
| **POST /group/delete** | Deletes one or more groups by ID. |

All three endpoints require API version **v19 or later**. The version is part of the base URL, for example `https://email.yourdomain.com/api/rest/v19`. For authentication and base URL, see [Getting Started with Engage API](https://docs.mapp.com/apidocs/en/getting-started-with-engage-api).

All date and time values returned by these endpoints are Unix timestamps in milliseconds.

---

## Finding Groups

`GET /group/find` returns a page of groups. Unbounded listing is not supported, so paging always applies. With no parameters, the endpoint returns the first 25 groups sorted by name in ascending order.

### Query Parameters

All parameters are optional.

| Parameter | Type | Description |
| --- | --- | --- |
| **nameFilter** | String | Returns groups whose name or email address contains this text. The match is case-insensitive. |
| **groupCategoryId** | Long | Returns only groups assigned to this group category. |
| **status** | String | `active` or `archived`. Omit the parameter to return both. |
| **groupType** | String | `regular` or `super`. Omit the parameter to return both. |
| **sortBy** | String | Field to sort by: `name`, `email`, `creationDate`, `memberCount`, `messageCount`, `groupCategory` or `id`. Default is `name`. Sorting by `groupCategory` sorts by the category label, not by its ID. |
| **sortOrder** | String | `asc` or `desc`. Default is `asc`. |
| **page** | Integer | Page to return, counted from 1. Default is 1. |
| **limit** | Integer | Number of groups per page. Default is 25, the maximum is 500. |

Filters are combined with AND. An invalid value for `status`, `groupType`, `sortBy` or `sortOrder`, a page below 1, or a limit outside the permitted range returns HTTP 400.

### Response

The response contains the list of groups in `groups`, together with `page` and `limit` as they were applied, and `totalCount`, the number of groups matching the filters across all pages.

Each entry in `groups` contains the following fields:

| Field | Type | Description |
| --- | --- | --- |
| **id** | Long | Unique ID of the group. |
| **name** | String | Display name of the group. |
| **email** | String | Sender email address of the group. |
| **description** | String | Description stored with the group. |
| **groupCategoryId** | Long | ID of the group category assigned to the group. |
| **groupCategoryLabel** | String | Display name of that group category. |
| **archived** | Boolean | True when the group is archived. |
| **isSuperGroup** | Boolean | True when the group is a SuperGroup. |
| **creationDate** | Long | When the group was created, as a Unix timestamp in milliseconds. |
| **memberCount** | Long | Number of members in the group. Can be `null`, see the note below. |
| **messageCount** | Long | Number of messages sent to the group. Can be `null`, see the note below. |
| **ownerId** | Long | ID of the system user who owns the group. |
| **isoCountryCode** | String | Country code configured for the group. |
| **isoLanguageCode** | String | Language code configured for the group. |
| **messageCategoryId** | Long | ID of the message category assigned to the group. |

> **Member statistics can be switched off.** When member statistics are skipped for your customer account, `memberCount` and `messageCount` are returned as `null`. Treat both fields as nullable in your integration.

### What the Endpoint Returns

- Deleted groups are never returned.
- Results depend on the permissions of the API user. A user without the permission to view all groups sees only the groups they own or moderate. Groups of other customer accounts are never returned.
- The endpoint returns a summary per group, not the full configuration. To read all settings of a single group, use `GET /group/get`. To read group attributes, use `GET /group/getAttributes`.

---

## Checking Whether a Group Is Locked

`GET /group/getLockStatus` takes a single required parameter, `groupId`, and returns the current lock status of that group.

Mapp Engage locks a group while an operation writes to it or reads from it, so that conflicting processes cannot run at the same time. For the two lock types and what they block, see [Group Locks](https://docs.mapp.com/docs/en/create-a-new-group#group-locks).

### Response

| Field | Type | Description |
| --- | --- | --- |
| **groupId** | Long | ID of the group you asked about. |
| **locked** | Boolean | True while an operation holds a lock on the group. |
| **lockType** | String | `EXCLUSIVE` or `SHARED`. |
| **lockedBy** | String | Identifier of the operation that holds the lock. |
| **lockReason** | String | Why the group is locked. See the table below. |
| **since** | Long | When the lock was created, as a Unix timestamp in milliseconds. |
| **lastAccessed** | Long | When the lock was last accessed, as a Unix timestamp in milliseconds. |

When the group is not locked, `locked` is `false` and all other fields except `groupId` are `null`.

### Lock Reasons

| Value | Meaning |
| --- | --- |
| `TRANSFER_SELECTION` | A segment transfer is writing contacts to the group. |
| `IMPORT` | A contact import is running on the group. |
| `SENDOUT` | A sendout is using the group. |
| `DELETE_GROUP` | The group is being deleted. |
| `BLACKLIST` | A blacklist operation is running on the group. |
| `OTHER` | Another operation holds the lock. |

### Using the Lock Status

A group stays locked until the operation that locked it has finished. A response with `locked: true` is therefore a reliable signal that an operation is still running. During a segment transfer, for example, the endpoint returns `locked: true`, `lockType: EXCLUSIVE` and `lockReason: TRANSFER_SELECTION`.

The endpoint tells you whether an operation is running, not how far it has progressed. For progress, poll `GET /process/getDetails` with the process ID that the transfer endpoint returned.

An invalid group ID returns HTTP 400. A group that does not exist or does not belong to your customer account returns HTTP 404.

---

## Deleting Groups

`POST /group/delete` takes a non-empty list of group IDs in the request body and deletes them immediately. Scheduled deletion is not supported.

The endpoint follows the same batch pattern as `POST /group/archive` and `POST /group/activate`: you receive one result per ID, and a failure for one group does not stop the others from being processed. An empty or missing list returns HTTP 400.

### Results

Each result contains `entityKey` with the group ID, a `code`, and a `message` with further details.

| Code | Meaning |
| --- | --- |
| `OK` | The group was deleted. |
| `NO_SUCH_OBJECT` | No group with this ID exists, or it does not belong to your customer account. |
| `PERMISSION_DENIED` | The API user is not permitted to delete this group. |
| `GROUP_LOCKED` | An operation currently holds a lock on the group. The group was not deleted. |
| `HAS_ACTIVE_REFERENCES` | An active scheduled message task still references the group. The group was not deleted. |
| `INVALID_PARAMETER` | The value is not a valid group ID. |
| `UNEXPECTED_ERROR` | The deletion failed for another reason. See `message` for details. |

Evaluate the result for every ID you sent. A group that returns `HAS_ACTIVE_REFERENCES` or `GROUP_LOCKED` still exists.

### What Deletion Affects

Deleting a group does more than remove the group itself. References that do not block the deletion are adjusted: scheduled tasks, event rules and whiteboards that use the group are deactivated, and prepared messages that use it are deleted. For the complete behaviour, see [References to the Group](https://docs.mapp.com/docs/en/create-a-new-group#references-to-the-group).

> [!CAUTION]
> **A campaign can be deleted with the group.** A campaign that belongs to the group is deleted together with it, including its statistics, unless the campaign has been marked beforehand. The Group endpoints do not return the associated campaign or its state, so an API client cannot check this in advance. Do not delete a group whose campaigns, prepared messages or statistics you still need.

---

## Typical Sequence

A common use case is cleaning up groups that a programmatic segment transfer created on the fly.

1. Call `GET /group/find` to locate the groups, for example with `nameFilter` and `groupCategoryId`.
2. Call `GET /group/getLockStatus` for each group you intend to delete. A group that a transfer is still writing to cannot be deleted.
3. Send the IDs of the unlocked groups to `POST /group/delete`.
4. Evaluate every result. Retry the groups that returned `GROUP_LOCKED` once their operation has finished.