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

```json
{
  "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

```json
{
  "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

```bash
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)

```bash
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)

```bash
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

```bash
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](https://developers.envoke.com).*