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.

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

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

---

Examples

List all tag groups (default pagination)

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

List all subscription groups

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

Filter by parent group name

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:

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

Filter by name

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

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

Return only specific fields

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)

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

Response:

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

Get a single group by ID

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.