---
title: "Create a new group"
method: POST
path: "/groups"
tags: ["groups"]
---

# Create a new group

`POST /groups`

## Request

- Base URL: `http://localhost:3001`
- URL: `http://localhost:3001/groups`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Creates a new expense group with the current user as admin

## Request body

- CreateGroupRequestDto
  - `name` string, required: Name of the group
  - `description` string: Description of the group
  - `icon` string: Icon name for the group
  - `color` string: Hex color for the group
  - `defaultCurrency` string: Default currency code (ISO 4217)
  - `supportedCurrencies` string[]: List of supported currencies
  - `currencyOrder` string[]: Display order for currencies

## Response `200`

Group created successfully

- object
  - `data` GroupResponseDto
    - `id` string, required
    - `name` string, required
    - `description` string
    - `createdBy` string, required
    - `createdAt` string, required: ISO creation timestamp
    - `updatedAt` string, required: ISO last update timestamp
    - `members` GroupMemberResponseDto[], required
      - `id` string, required
      - `userId` string, required
      - `displayName` string, required
      - `email` string, required
      - `role` 'admin' | 'member', required
      - `joinedAt` string, required: ISO timestamp when the user joined
      - `leftAt` string, nullable, required
      - `avatarUrl` string, nullable
      - `displayOrder` number, nullable: Custom display order for this membership
      - `overrideIcon` string, nullable
      - `overrideColor` string, nullable
    - `memberCount` number, required
    - `defaultCurrency` string, required
    - `supportedCurrencies` string[], required
    - `currencyOrder` string[], required
    - `icon` string, required
    - `color` string, required
    - `transactions` object[], required: Transactions for the group (typically omitted or empty in this response; loaded via separate transactions endpoint)
    - `groupIcon` string, required
    - `groupColor` string, required
  - `success` boolean
  - `message` string

## Other responses

- `400`: Bad Request - Invalid input or validation failed
- `401`: Unauthorized - Authentication required or invalid token
- `403`: Forbidden - Insufficient permissions to access this resource
- `404`: Not Found - The requested resource does not exist
- `500`: Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.dev/spliteo/apis/spliteo-api.md) · [All operations](https://skmtc.dev/spliteo/apis/spliteo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/spliteo/apis/spliteo-api/revisions/bd9b84f4e407?raw)