# Create activity group

`POST /api/configuration/activity-groups`

- **Products:** Operator (`FOH`)
- **Features:** Front of House Generic Access (`FOHGENERIC`)

HTML version: [Create activity group](https://support.gladstonesoftware.cloud/reference/configuration/create-activity-group)

## Overview

Creates an activity group — a label used to categorise activities so they can be listed, filtered and administered together. An activity group is a flat record: an identifier, a description and a free-text comment. It carries no parent/child hierarchy and no site scoping, and creating one does not attach any activities to it; you assign activities to a group when you create or update each activity.

You may supply your own `id`, or omit it and let the system allocate the next sequential identifier using the `ACTGRP` prefix. The identifier must be unique within your tenant.

**This call is not idempotent.** Retrying with an explicit `id` that already exists returns `409`. Retrying without an `id` allocates a fresh identifier and creates a second, duplicate group. Because the response body is empty, supply your own `id` whenever you need to know the identifier of the group you just created.

## Endpoint

`POST {base_url}/api/configuration/activity-groups`

`{base_url}` is the environment URL issued to your integration. See [Authenticating with Gladstone APIs](../../guides/authenticating-with-gladstone-apis.md).

## Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | No | The identifier you want the group to have, unique within your tenant. Maximum 15 characters. It must not contain any of the characters ``!£$%^&*()_+=[]{};:@~#?.,<>\|`` — a request containing one is rejected with `400` "ActivityGroupId contains invalid characters". Omit it and the system allocates the next free identifier in the `ACTGRP` series (`ACTGRP1`, `ACTGRP2`, …). Because the response body is empty, an omitted `id` leaves you without the identifier of the group you just created; you would have to find it by listing activity groups afterwards. Supplying an `id` that already exists returns `409`. |
| `description` | string | Yes | The human-readable name shown wherever the group is presented for selection or filtering. Must not be blank and must not exceed 255 characters; either fault is rejected with `400`. This is the only label the group has — there is no separate short name or code. |
| `comments` | string | No | A free-text note about the group, maximum 255 characters. The single value you send is written to both the kiosk comment and the web comment fields, so you cannot give kiosk and web different text through this endpoint. Omit it and both are left null. |

## Sample request

```bash title="cURL"
curl -X POST '{base_url}/api/configuration/activity-groups' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "string",
  "description": "string",
  "comments": "string"
}'
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | `id` contains one of the disallowed characters ``!£$%^&*()_+=[]{};:@~#?.,<>\|``; or `description` is missing or blank; or `id`, `description` or `comments` exceeds its maximum length. Length and blank failures are returned as a validation error object keyed by field name, not as a plain string. |
| `400` | Bad request | "Foreign keys being referenced do not exist" — a value in the request refers to something that does not exist. |
| `409` | Conflict | "Activity group ID already exists" — the `id` you supplied is already in use. The group is not modified; use the update endpoint instead. |
| `500` | Internal server error | Any other failure. Nothing is saved, so no partial group is left behind. |