> ## Documentation Index
> Fetch the complete documentation index at: https://developer.peoplewisher.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Celebration Groups

> Create, list, and remove the groups that connect contacts to Peoplewisher workflows.

A Celebration Group is the point where your application connects a person to a Peoplewisher celebration workflow.

The API supports:

| Operation    | Method   | Endpoint                            |
| ------------ | -------- | ----------------------------------- |
| List groups  | `GET`    | `/v1/celebration-groups`            |
| Create group | `POST`   | `/v1/celebration-groups`            |
| Delete group | `DELETE` | `/v1/celebration-groups/{group_id}` |

## Categories

Every Celebration Group has a `category`.

Peoplewisher currently recognizes:

| Category              | Purpose                          |
| --------------------- | -------------------------------- |
| `birthday`            | Birthday celebrations            |
| `anniversary`         | Anniversary celebrations         |
| `work_anniversary`    | Work anniversary celebrations    |
| `wedding_anniversary` | Wedding anniversary celebrations |

The category is returned when you list groups and is also accepted when creating a group.

## List groups

```bash theme={null}
curl https://api.peoplewisher.com/v1/celebration-groups \
  -H "Authorization: Bearer $PEOPLEWISHER_API_KEY"
```

Example:

```json theme={null}
{
  "success": true,
  "data": [
    {
      "group_id": 24,
      "name": "Customers",
      "category": "birthday",
      "status": "active",
      "contact_count": 174
    }
  ]
}
```

## Create a group

```bash theme={null}
curl -X POST https://api.peoplewisher.com/v1/celebration-groups \
  -H "Authorization: Bearer $PEOPLEWISHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customers",
    "category": "birthday"
  }'
```

Creating a group does **not** configure the messages or channels.

After creating the group, the account owner should open Peoplewisher and configure the group's celebration settings.

## Delete a group

```bash theme={null}
curl -X DELETE https://api.peoplewisher.com/v1/celebration-groups/24 \
  -H "Authorization: Bearer $PEOPLEWISHER_API_KEY"
```

PeopleWisher's existing group deletion flow marks a group for deletion rather than immediately removing all related records.

## The important rule

Once the group is configured, your application generally does not need to know how the workflow works.

It only needs to keep the group membership and contact data correct.