---
title: "Creates a schedule group (a division, crew or team)."
method: POST
path: "/api/v1/schedule-groups"
tags: ["ScheduleGroups"]
---

# Creates a schedule group (a division, crew or team).

`POST /api/v1/schedule-groups`

## Request

- Base URL: `https://app.flexonthejob.com`
- URL: `https://app.flexonthejob.com/api/v1/schedule-groups`
- Auth: HTTP bearer

Requires `ManageJobs` and an `Idempotency-Key` header. Same as "New group" on the
Schedule Groups page: the group is placed last among its siblings. Add people with
`PUT /api/v1/schedule-groups/{id}/members/{userId}`.
Example: `{ "name": "Install Crew A", "colorHex": "#2e7d32", "parentGroupId": 3 }`.

## Request body

- ScheduleGroupWriteApiRequest: Body of `POST /api/v1/schedule-groups` (`name` required) and `PATCH /api/v1/schedule-groups/{id}` (only the fields sent change; `""` clears `description` / `colorHex`). Example: `{ "name": "Install Crew A", "colorHex": "#2e7d32", "parentGroupId": 3 }`.
  - `name` string, nullable: Group name, 1–100 characters. Required on create; cannot be cleared. Example: `"Install Crew A"`.
  - `description` string, nullable: Optional description shown on the dispatch board, up to 500 characters; `""` clears it.
  - `colorHex` string, nullable: Colour for calendar / board rendering as 6-digit hex, e.g. `"#2e7d32"` (the `#` is optional; stored lower-case); `""` clears it.
  - `parentGroupId` integer, nullable: Id of the parent group (e.g. the division a crew belongs to); `0` makes the group top-level. Omit on PATCH to keep the current parent (on create, omitted = top-level). A moved group is placed last among its new siblings; a group cannot be moved under itself or its own descendants.

## Response `201`

The new group; `Location` points at `/api/v1/schedule-groups/{id}`.

- ScheduleGroupDto: A scheduling group (division, crew or team) of the calling organization, as returned by `GET /api/v1/schedule-groups`. Groups form a tree via `parentGroupId`; a user may belong to several groups. Requires the `scheduling` module.
  - `id` integer: Numeric id of the group. Stable within this organization.
  - `syncId` string, uuid: Globally unique sync id (GUID). Use it as the `after` pagination cursor.
  - `name` string: Group name, e.g. `"Install Crew A"`.
  - `description` string, nullable: Optional description shown on the dispatch board.
  - `colorHex` string, nullable: Hex colour used for calendar / board rendering, e.g. `"#2e7d32"`; null when unset.
  - `parentGroupId` integer, nullable: Id of the parent group (e.g. the division a crew belongs to); null for top-level groups.
  - `parentGroupName` string, nullable: Name of the parent group; null for top-level groups.
  - `displayOrder` integer: Sort position among siblings (ascending). Pages are returned in id order, so sort by this client-side when rendering a board.
  - `members` ScheduleGroupMemberDto[]: Members of this group, leads first. Only active users are listed.
    - `userId` string: User id (string GUID) — matches `id` from `GET /api/v1/users` and job assignee ids.
    - `displayName` string: User's display name, e.g. `"Sam Carter"`.
    - `isLead` boolean: True for the crew lead / foreman of this group.
  - `createdAt` string, date-time: UTC creation timestamp.
  - `updatedAt` string, date-time, nullable: UTC timestamp of the last edit; null when never edited.

## Other responses

- `400`: Malformed body, a field over its length limit, or missing `Idempotency-Key`.
- `401`: Unauthorized
- `403`: The `scheduling` module is not active for this organization.
- `409`: The key's creator is unknown on this server, so the write cannot be attributed.
- `422`: Blank name, a colour that is not 6-digit hex, or an unknown `parentGroupId`; the field is listed in `errors`.
- `429`: Too Many Requests

---

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