# Group API - Read

Use the read endpoints to retrieve groups for your account. You can list all groups for a given item type with filtering and sorting, or retrieve a single group by ID.

---

## Endpoints

| Method | URL | Description |
|---|---|---|
| GET | `https://e1.envoke.com/v2/groups/{type}` | Return a list of groups. |
| GET | `https://e1.envoke.com/v2/groups/{type}/{ID}` | Return a single group. |

Replace `{type}` with one of: `tags`, `subscriptions`, `messages`, or `templates`.

Authentication is via HTTP Basic Auth using your API ID and API Key.

---

## List Groups

```
GET https://e1.envoke.com/v2/groups/{type}
```

Returns a JSON array of groups for your account and the specified item type, sorted alphabetically by name. Supports filtering, sorting, pagination, and field selection.

### Query Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `limit` | integer | `10` | Maximum number of results to return. Hard cap is `100` unless `?fields=` or `?result_type=kvp` is also set (see note below). |
| `skip` | integer | `0` | Number of records to skip. Use with `limit` to paginate. |
| `fields` | string | *(all)* | Comma-separated list of fields to include in each result. See limit note below. |
| `result_type` | string | *(array)* | Set to `kvp` to receive results as a key-value object (`{ "id": "name" }`). See limit note below. |
| `filter[id]` | string | — | Filter by group ID. |
| `filter[name]` | string | — | Filter by group name. |
| `filter[parent_group]` | string | — | Filter by parent group name or numeric ID. |
| `sort[name]` | string | — | Sort by name. Value: `asc` or `desc`. |

**Note — limit behaviour with `?fields=` and `?result_type=kvp`:** When either of these parameters is present, the default limit increases to 10,000 (returning all records if no explicit limit is specified) and a `?limit=` value above 100 is honoured as-is. This allows full exports and dropdown population without pagination.

### Filter Operators

All `filter[field]` parameters support exact match and the not-equal operator:

| Operator | Example | Description |
|---|---|---|
| *(none)* | `?filter[name]=Academic Programs` | Exact match |
| `(ne)` | `?filter[parent_group][(ne)]=Academic Programs` | Not equal |

The `filter[parent_group]` parameter accepts either a group name or a numeric group ID. Name lookups are case-sensitive.

*Note: URL-encode brackets in production requests (e.g. `%5B` for `[`).*

### Response

A JSON array of group objects. Returns an empty array (`[]`) if no groups exist or no results match the filter.

```json
[
  {
    "id": "7",
    "name": "Graduate Studies",
    "parent_group": "Academic Programs"
  },
  {
    "id": "3",
    "name": "Student Life",
    "parent_group": ""
  }
]
```

`parent_group` is always present. It is an empty string (`""`) for top-level groups.

---

## Get a Single Group

```
GET https://e1.envoke.com/v2/groups/{type}/{ID}
```

Returns a single group object. Replace `{type}` and `{ID}` with the item type and Envoke group ID.

If the ID is not found, the API returns an empty array (`[]`).

### Response

```json
{
  "id": "7",
  "name": "Graduate Studies",
  "parent_group": "Academic Programs"
}
```

---

## Examples

### List all tag groups (default pagination)

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/groups/tags"
```

### List all subscription groups

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/groups/subscriptions"
```

### Filter by parent group name

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/groups/tags?filter%5Bparent_group%5D=Academic+Programs"
```

### Filter top-level groups only

Filtering for groups with no parent — pass an empty string or `0`:

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/groups/tags?filter%5Bparent_group%5D="
```

### Filter by name

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/groups/tags?filter%5Bname%5D=Student+Life"
```

### Sort by name descending

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/groups/tags?sort%5Bname%5D=desc"
```

### Return only specific fields

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/groups/tags?fields=id,name"
```

### Return as a key-value map (for dropdowns)

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/groups/tags?result_type=kvp"
```

Response:

```json
{ "3": "Student Life", "7": "Graduate Studies" }
```

### Get a single group by ID

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/groups/tags/7"
```

---

*Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.*

*Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).*