# Group API - Update

Use this endpoint to update an existing group. You can rename the group or change its parent.

---

## Endpoint

```
PATCH https://e1.envoke.com/v2/groups/{type}/{ID}
```

Replace `{type}` with one of: `tags`, `subscriptions`, `messages`, or `templates`. Replace `{ID}` with the Envoke group ID you want to update.

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

---

## Request Body

At least one field must be provided.

| Field | Type | Description |
|---|---|---|
| `name` | string | New group name. Cannot be blank. |
| `parent_group` | string, integer, or null | Parent group name or ID to assign. Pass `null` or `""` (empty string) to promote the group to top-level (remove its parent). The parent must itself be top-level. |

If `id` is included in the request body, it must match the `{ID}` in the URL — if they differ, a validation error is returned: `"Provided 'id': {url_id} does not match 'id' in request body ({body_id})"`.

---

## Response

On success, the API returns the updated group object:

```json
{
  "success": true,
  "result_text": "Updated",
  "result_data": {
    "id": "7",
    "name": "Graduate Studies (Updated)",
    "parent_group": "Academic Programs"
  }
}
```

---

## Validation Errors

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

Common errors:

| Error                                                                     | Cause |
|---------------------------------------------------------------------------|---|
| `Request body may not be empty`                                           | No JSON body was provided. |
| `Item with id '{id}' not found`                                           | The `{ID}` in the URL does not match any group of this type in your account. |
| `The field 'name' cannot be empty`                                        | `name` was provided but was blank or whitespace only. |
| `The 'parent_group' '{value}' not found`                                  | The parent group name or ID was not found for this item type. |
| `The field 'parent_group' cannot be a nested group (maximum depth is 1)`            | The specified parent is itself a subgroup. |
| `Provided 'id': {url_id} does not match 'id' in request body ({body_id})` | `id` in the request body differs from `{ID}` in the URL. |

---

## Examples

### Rename a group

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

### Assign a parent group (make it a subgroup)

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

### Promote to top-level (remove parent) using null

```bash
curl -X PATCH -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parent_group": null}' \
  "https://e1.envoke.com/v2/groups/tags/8"
```

### Promote to top-level (remove parent) using empty string

```bash
curl -X PATCH -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parent_group": ""}' \
  "https://e1.envoke.com/v2/groups/tags/8"
```

### Rename and reassign parent at the same time

```bash
curl -X PATCH -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/8"
```

---

*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).*