Group API - Insert

Use this endpoint to create a new group in your account.

---

Endpoint

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

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

Authentication is via HTTP Basic Auth using your API ID and API Key. The request body must be JSON.

---

Request Body

Field	Type	Required	Description
name	string	Yes	The group name.
parent_group	string, integer, or null	No	Parent group name (string) or parent group ID (integer) to nest this group under. Omit, pass null, or pass "" to create a top-level group. The parent must itself be top-level — only one level of nesting is supported.

---

Response

On success, the API returns the newly created group object:

{
  "success": true,
  "result_text": "Created",
  "result_data": {
    "id": "8",
    "name": "Graduate Studies",
    "parent_group": "Academic Programs"
  }
}

result_data.id is the Envoke group ID. Store this if you need to update or delete the group later.

---

Validation Errors

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

Common validation errors:

Error	Cause
Request body may not be empty	No JSON body was provided.
The field 'name' is required	name was missing or blank.
The 'parent_group' '{value}' not found	The parent group name or ID was not found in this account for this item type.
The field 'parent_group' cannot be a nested group (maximum depth is 1)	The specified parent is itself a subgroup — only top-level groups can be used as parents.

---

Examples

Create a top-level tag group

curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Academic Programs"}' \
  "https://e1.envoke.com/v2/groups/tags"

Create a subgroup (by parent name)

curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Graduate Studies", "parent_group": "Academic Programs"}' \
  "https://e1.envoke.com/v2/groups/tags"

Create a subgroup (by parent ID)

curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Graduate Studies", "parent_group": 7}' \
  "https://e1.envoke.com/v2/groups/tags"

Create a subscription group

curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Stakeholder Communications"}' \
  "https://e1.envoke.com/v2/groups/subscriptions"

---

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.