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

# List Celebration Groups

> List the Celebration Groups available to your Peoplewisher account. Each group includes its celebration category so your application can determine where a contact belongs.

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.peoplewisher.com/v1/celebration-groups' \
    --header 'Authorization: Bearer YOUR_API_KEY' 
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "data": [
      {
        "group_id": 24,
        "name": "Customers",
        "category": "birthday",
        "status": "active",
        "date_created": "2026-09-28 16:00:00",
        "data_source_id": null,
        "data_source_name": null,
        "data_source_type": null,
        "contact_count": 174
      },
      {
        "group_id": 25,
        "name": "Work Anniversaries",
        "category": "work_anniversary",
        "status": "active",
        "date_created": "2026-09-28 16:02:00",
        "data_source_id": null,
        "data_source_name": null,
        "data_source_type": null,
        "contact_count": 42
      }
    ]
  }
  ```
</ResponseExample>

## How it works

### Celebration categories

Peoplewisher currently supports these celebration categories:

* `birthday`
* `anniversary`
* `work_anniversary`
* `wedding_anniversary`

The category is part of the group definition. Your application should normally select the appropriate existing group rather than trying to reproduce PeopleWisher's workflow logic.

## Authentication

Include your Peoplewisher API key as a Bearer token on every request:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Your API key is available in **Peoplewisher → Settings → API**. Keep it private and never expose it in browser-side code or public repositories.


## OpenAPI

````yaml openapi.yaml GET /celebration-groups
openapi: 3.0.3
info:
  title: Peoplewisher API
  version: 1.0.0
  description: |
    The Peoplewisher API lets an application synchronize contacts and place
    those contacts into Peoplewisher Celebration Groups. Peoplewisher then
    runs the celebration workflows configured for those groups in the
    Peoplewisher application.

    The public API is intentionally focused: applications provide people data
    and group membership. Templates, channels, schedules, celebration
    settings, and workflow behavior are managed in the Peoplewisher UI.
servers:
  - url: https://api.peoplewisher.com/v1
    description: Peoplewisher API
security:
  - bearerAuth: []
tags:
  - name: Contacts
    description: Manage the people whose celebrations Peoplewisher handles.
  - name: Celebration Groups
    description: >-
      Manage the Peoplewisher groups that determine which celebration workflow
      applies to a contact.
paths:
  /celebration-groups:
    get:
      tags:
        - Celebration Groups
      summary: List Celebration Groups
      description: >
        Returns the Celebration Groups in the authenticated PeopleWisher
        account.


        Each group includes its `category`. The category identifies the type

        of celebration the group is used for and is part of the response so

        an integrating application can map its own customer or event model

        to the correct Peoplewisher workflow.
      operationId: listCelebrationGroups
      responses:
        '200':
          description: Celebration Group list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupListResponse'
              example:
                success: true
                data:
                  - group_id: 24
                    name: Customers
                    category: birthday
                    status: active
                    date_created: '2026-09-28 16:00:00'
                    data_source_id: null
                    data_source_name: null
                    data_source_type: null
                    contact_count: 174
                  - group_id: 25
                    name: Work Anniversaries
                    category: work_anniversary
                    status: active
                    date_created: '2026-09-28 16:02:00'
                    data_source_id: null
                    data_source_name: null
                    data_source_type: null
                    contact_count: 42
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-codeSamples:
        - lang: curl
          source: |-
            curl --request GET \
              --url 'https://api.peoplewisher.com/v1/celebration-groups' \
              --header 'Authorization: Bearer YOUR_API_KEY' 
components:
  schemas:
    GroupListResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/CelebrationGroup'
    CelebrationGroup:
      type: object
      properties:
        group_id:
          type: integer
        name:
          type: string
        category:
          type: string
        status:
          type: string
        date_created:
          type: string
        data_source_id:
          type: integer
          nullable: true
        data_source_name:
          type: string
          nullable: true
        data_source_type:
          type: string
          nullable: true
        contact_count:
          type: integer
    ErrorResponse:
      type: object
      required:
        - success
        - error
        - message
      properties:
        success:
          type: boolean
        error:
          type: string
        message:
          type: string
        request_id:
          type: string
          nullable: true
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: unauthorized
            message: Invalid or missing API key.
    RateLimited:
      description: The API request was rate limited.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: rate_limited
            message: Too many requests. Please retry later.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: |
        Use the API key generated in Peoplewisher Settings as a Bearer token.

````