---
title: "createGroup"
method: POST
path: "/households/{householdId}/groups/createGroup"
tags: ["groups"]
---

# createGroup

`POST /households/{householdId}/groups/createGroup`

Use the createGroup command in the groups namespace to create a new group from a list
 of players. The player returns a group object with the group ID. This may be an existing
 group ID if an existing group is a subset of the new group. In this case, Sonos may
 build the new group by adding new players to the existing group.

## Request body

- object
  - `playerIds` string[], required — An array of player ID strings to group.
  - `musicContextGroupId` string, nullable — (Optional) The group containing the audio that you want to use. If empty or not provided, the new group will not contain any audio.
  - `areaIds` string[], nullable — (Optional) List of source areaIds in the group. Emitted in groupInfo events. As of version 1.19.1, this can include the "Everywhere" area ID. If it does, this indicates that the group includes all visible players.

## Response `200`

Returns a groupInfo object, which currently only includes a group object. The groupInfo object 
 may include additional information in the future.

 Muse v2 sends playerSetError which includes playerIds array since version 1.17.0

- GroupInfo — No description available
  - `group` Group — No description available
    - `id` string, required — The ID of the group.
    - `name` string, required — The display name for the group, such as “Living Room” or “Kitchen + 2”.
    - `coordinatorId` string, required — The ID of the player acting as the group coordinator for the group. This is a playerId value.
    - `playbackState` 'PLAYBACK_STATE_IDLE' | 'PLAYBACK_STATE_BUFFERING' | 'PLAYBACK_STATE_PAUSED' | 'PLAYBACK_STATE_PLAYING' — No description available
    - `playerIds` string[], required — The IDs of the primary players in the group. For example, only one player from each set of players bonded as a stereo pair or as satellites to a home theater setup. Each element is the ID of a player. This list includes the coordinatorId.
    - `areaIds` string[], nullable — List of source areaIds associated with the group.

## Other responses

- `400` — Returns a groupInfo object, which currently only includes a group object. The groupInfo object may include additional information in the future. Muse v2 sends playerSetError which includes playerIds array since version 1.17.0
- `401` — Returns a groupInfo object, which currently only includes a group object. The groupInfo object may include additional information in the future. Muse v2 sends playerSetError which includes playerIds array since version 1.17.0
- `403` — Returns a groupInfo object, which currently only includes a group object. The groupInfo object may include additional information in the future. Muse v2 sends playerSetError which includes playerIds array since version 1.17.0
- `404` — Returns a groupInfo object, which currently only includes a group object. The groupInfo object may include additional information in the future. Muse v2 sends playerSetError which includes playerIds array since version 1.17.0
- `499` — Returns a groupInfo object, which currently only includes a group object. The groupInfo object may include additional information in the future. Muse v2 sends playerSetError which includes playerIds array since version 1.17.0
- `500` — Returns a groupInfo object, which currently only includes a group object. The groupInfo object may include additional information in the future. Muse v2 sends playerSetError which includes playerIds array since version 1.17.0
- `503` — Returns a groupInfo object, which currently only includes a group object. The groupInfo object may include additional information in the future. Muse v2 sends playerSetError which includes playerIds array since version 1.17.0

---

[API](https://skmtc.net/sonos/apis/authorization-api.md) · [All operations](https://skmtc.net/sonos/apis/authorization-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sonos/authorization-api/revisions/243132628620/schema)