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

# Create a Celebration Group

> Create a Celebration Group that contacts can be assigned to.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.peoplewisher.com/v1/celebration-groups' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "name": "Customers",
      "category": "birthday"
    }' 
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "data": {
      "group_id": 24,
      "name": "Customers",
      "category": "birthday"
    }
  }
  ```
</ResponseExample>

## How it works

Creating a group does not create or configure the messages sent to its members. Configure the group's celebration settings, templates, channels, and workflow inside PeopleWisher.

## 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 POST /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:
    post:
      tags:
        - Celebration Groups
      summary: Create a Celebration Group
      description: |
        Creates a Celebration Group.

        Creating the group does not configure its workflow. The group becomes
        useful when its celebration settings, templates, channels, and timing
        are configured by the account owner in the Peoplewisher application.
      operationId: createCelebrationGroup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupCreate'
            example:
              name: Customers
              category: birthday
      responses:
        '201':
          description: Celebration Group created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMutationResponse'
              example:
                success: true
                data:
                  group_id: 24
                  name: Customers
                  category: birthday
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '403':
          $ref: '#/components/responses/PlanLimit'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-codeSamples:
        - lang: curl
          source: |-
            curl --request POST \
              --url 'https://api.peoplewisher.com/v1/celebration-groups' \
              --header 'Authorization: Bearer YOUR_API_KEY' \
              --header 'Content-Type: application/json' \
              --data '{
                "name": "Customers",
                "category": "birthday"
              }' 
components:
  schemas:
    GroupCreate:
      type: object
      required:
        - name
        - category
      properties:
        name:
          type: string
        category:
          type: string
          enum:
            - birthday
            - anniversary
            - work_anniversary
            - wedding_anniversary
          description: |
            Celebration category. Peoplewisher currently recognizes birthday,
            anniversary, work_anniversary, and wedding_anniversary.
    GroupMutationResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          $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:
    InvalidRequest:
      description: The request is malformed or required data is missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: invalid_request
            message: A valid group_id is required.
    PlanLimit:
      description: The account has reached a Peoplewisher plan limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: plan_limit_reached
            message: >-
              You have reached the maximum number of contacts allowed on your
              current plan.
    ValidationError:
      description: Request validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: validation_error
            message: Please provide a valid email address.
    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.

````