# Group API - Fields Reference

This article describes all fields available through the Group API. Use this as a reference when reading, creating, or updating groups.

---

## Overview

The Group API lets you manage groups programmatically. Groups are used to organise tags, subscriptions, messages, and templates into named categories within your Envoke account. Each item type has its own group namespace, accessible via a different URL path.

Groups support **one level of nesting**: a top-level group can have subgroups, but a subgroup cannot itself have children.

All endpoints require [HTTP Basic Auth](https://envoke-developers.pages.dev/guides/authentication/) using your API ID and API Key.

---

## URL Paths by Item Type

The Group API exposes four separate paths — one for each type of item that can be grouped:

| URL path | Groups for... |
|---|---|
| `https://e1.envoke.com/v2/groups/tags` | Tags (interests) |
| `https://e1.envoke.com/v2/groups/subscriptions` | Subscriptions |
| `https://e1.envoke.com/v2/groups/messages` | Messages |
| `https://e1.envoke.com/v2/groups/templates` | Templates |

All four paths accept the same request and response format described in this article.

---

## Fields

| Field | Type | Read-only | Required on Create | Description |
|---|---|---|---|---|
| `id` | string | Yes | — | Unique identifier assigned on creation. |
| `name` | string | No | Yes | The group name. |
| `parent_group` | string | No | No | Name of the parent group. Empty string (`""`) when the group is top-level. |

---

## Field Details

### `id`

- **Type:** String
- **Read-only:** Yes — assigned automatically on creation.
- **Example:** `"7"`

Used to identify the group in update, delete, and filter requests.

---

### `name`

- **Type:** String
- **Read-only:** No — updatable via PATCH.
- **Required on create:** Yes
- **Example:** `"Academic Programs"`

The group name as it appears within your Envoke account.

---

### `parent_group`

- **Type:** String (read); String, integer, or null (write)
- **Read-only:** No — updatable via PATCH.
- **Required on create:** No
- **Returned value (read):** The parent group's name as a string. Returns `""` (empty string) when the group is top-level.
- **Accepted values (write):** Parent group name (string) or parent group ID (integer).
- **Example:** `"Academic Programs"`, `""`

**Nesting rules:**
- A top-level group has `parent_group: ""`.
- A subgroup has `parent_group: "<parent name>"`.
- The parent must itself be a top-level group — you cannot nest a subgroup under another subgroup. The maximum depth is 1.

**Removing a parent:** On PATCH, pass `null` or `""` (empty string) to promote a subgroup to top-level. This removes the parent association.

---

## Error Responses

**Validation errors** (missing required fields, invalid values):

```json
{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": [
      "The field 'name' is required"
    ]
  }
}
```

**Not-found behaviour varies by method:**

- **GET** `/groups/{type}/{id}` — when the ID is not found, returns an empty array (`[]`).
- **PATCH** and **DELETE** `/groups/{type}/{id}` — when the ID is not found, returns a validation error:

```json
{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": ["Item with id '999999' not found"]
  }
}
```

**Delete constraint** — a group with subgroups or assigned items cannot be deleted:

```json
{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": ["Only empty groups can be deleted"]
  }
}
```

---

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