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 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):

{
  "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:

{
  "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:

{
  "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.