openapi: 3.0.3
info:
  title: Prolific Bonuses Participant Groups API
  description: 'The Prolific API is a versioned REST interface for the Prolific online research participant recruitment platform. Researchers use it to programmatically create and publish studies, review and approve submissions, manage participant groups, projects and workspaces, apply demographic filters and requirements, pay bonuses, message participants, and subscribe to event webhooks (hooks). The API is served from https://api.prolific.com/api/v1 and follows a standard REST pattern: a collection endpoint (.../resource/) for GET (list) and POST (create), and an element endpoint (.../resource/{id}/) for GET, PATCH/PUT, and DELETE. All requests are authenticated with an API token supplied in the Authorization header as "Token <your token>".'
  version: v1
  contact:
    name: Prolific
    url: https://docs.prolific.com/api-reference
  license:
    name: Proprietary
    url: https://www.prolific.com/terms
servers:
- url: https://api.prolific.com/api/v1
  description: Prolific API v1
security:
- tokenAuth: []
tags:
- name: Participant Groups
  description: Saved, dynamic groups of participant IDs used as allowlist/blocklist filters.
paths:
  /participant-groups/:
    get:
      operationId: listParticipantGroups
      tags:
      - Participant Groups
      summary: Get all participant groups
      description: List participant groups scoped to a workspace_id or project_id.
      parameters:
      - name: workspace_id
        in: query
        required: false
        schema:
          type: string
      - name: project_id
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A list of participant groups.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantGroupList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createParticipantGroup
      tags:
      - Participant Groups
      summary: Create participant group
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParticipantGroupInput'
      responses:
        '201':
          description: The created participant group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantGroup'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /participant-groups/{id}/:
    parameters:
    - $ref: '#/components/parameters/GroupId'
    get:
      operationId: getParticipantGroup
      tags:
      - Participant Groups
      summary: Get a participant group
      responses:
        '200':
          description: A participant group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantGroup'
        '401':
          $ref: '#/components/responses/Unauthorized'
    patch:
      operationId: updateParticipantGroup
      tags:
      - Participant Groups
      summary: Update a participant group
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParticipantGroupInput'
      responses:
        '200':
          description: The updated participant group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantGroup'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteParticipantGroup
      tags:
      - Participant Groups
      summary: Delete a participant group
      responses:
        '204':
          description: The participant group was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /participant-groups/{id}/participants/:
    parameters:
    - $ref: '#/components/parameters/GroupId'
    get:
      operationId: getGroupParticipants
      tags:
      - Participant Groups
      summary: Get group participants
      responses:
        '200':
          description: The participant IDs in the group.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: addGroupParticipants
      tags:
      - Participant Groups
      summary: Add participants to group
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                participant_ids:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Participants added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantGroup'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: removeGroupParticipants
      tags:
      - Participant Groups
      summary: Remove participants from group
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                participant_ids:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Participants removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantGroup'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    ParticipantGroupInput:
      type: object
      properties:
        name:
          type: string
        project_id:
          type: string
        participant_ids:
          type: array
          items:
            type: string
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            detail:
              type: string
            error_code:
              type: integer
    ParticipantGroup:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        project_id:
          type: string
        workspace_id:
          type: string
        participant_count:
          type: integer
    ParticipantGroupList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/ParticipantGroup'
  responses:
    Unauthorized:
      description: Authentication credentials were missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    GroupId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The participant group ID.
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API token supplied as "Token <your token>".