---
title: "Create a new participant group within a workspace"
method: POST
path: "/api/v1/participant-groups/"
tags: ["participantGroups"]
---

# Create a new participant group within a workspace

`POST /api/v1/participant-groups/`

## Headers

- `Authorization` string, required

## Request body

- object
  - `workspace_id` string — The id of the workspace to create the participant group in. Either a workspace or organisation ID must be specified.
  - `organisation_id` string — The id of the organisation to create the participant group in. Either a workspace or organisation ID must be specified.
  - `name` string, required — The name of the participant group
  - `description` string — A description of the participant group
  - `participant_ids` string[] — The ids of participants to be initially added to the group

## Response `201`

Participant group created

- ParticipantGroupResponse
  - `id` string — The id of the participant group
  - `name` string — The name of the participant group
  - `project_id` string, nullable — The id of the project the participant group belongs to
  - `workspace_id` string, nullable — The id of the workspace the participant group belongs to. A participant group can only belong to either a workspace or an organisation.
  - `organisation_id` string, nullable — The id of the organisation the participant group belongs to. A participant group can only belong to either a workspace or an organisation.
  - `description` string, nullable — The user-provided description of the participant group
  - `participant_count` integer — The number of participants in the participant group
  - `is_deleted` boolean — Whether the participant group has been deleted
  - `feeder_studies` ParticipantGroupFeederStudiesItems[] — Details of all studies which are configured to modify the participants in this group through completion codes.
    - `id` string — The id of the study.
    - `name` string — The name of the study.
    - `internal_name` string — The internal name of the study.
    - `status` string — The current status of the study.
    - `feeder_completion_codes` ParticipantGroupFeederStudiesItemsFeederCompletionCodesItems[] — The completion codes which will modify the participants in this group.
      - `code` string — The code that will modify the participants in this group.
      - `code_type` string — The label or code type given to this code within the context of the study.
      - `action` 'ADD_TO_PARTICIPANT_GROUP' | 'REMOVE_FROM_PARTICIPANT_GROUP' — The action that will be taken when this code is used.

## Other responses

- `400` — Error

---

[API](https://skmtc.net/prolific/apis/api-reference.md) · [All operations](https://skmtc.net/prolific/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/prolific/api-reference/versions/dc6f073a9827/schema)