Prolific Messages API

openapi: 3.0.3
info:
  title: Prolific 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: Studies
    description: Create, publish, and manage research studies.
  - name: Submissions
    description: Review, approve, reject, and return participant submissions.
  - name: Participant Groups
    description: Saved, dynamic groups of participant IDs used as allowlist/blocklist filters.
  - name: Projects
    description: Organize studies within a workspace.
  - name: Workspaces
    description: Top-level containers that hold projects, fund studies, and scope teams.
  - name: Messages
    description: Communicate with participants.
  - name: Hooks
    description: Event webhook subscriptions and signing secrets.
  - name: Filters
    description: Demographic and screening requirements and eligibility counts.
  - name: Bonuses
    description: Bulk bonus payments to participants.
  - name: Users
    description: Authenticated account and user identity.
paths:
  /studies/:
    get:
      operationId: listStudies
      tags: [Studies]
      summary: List all studies
      description: Lists all studies, with the option to filter by study status.
      parameters:
        - name: state
          in: query
          required: false
          schema:
            type: string
          description: Filter studies by status (e.g. UNPUBLISHED, ACTIVE, COMPLETED).
      responses:
        '200':
          description: A paginated list of studies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudyList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createStudy
      tags: [Studies]
      summary: Create a draft study
      description: Creates a new draft study. Publishing is a separate transition step.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StudyInput'
      responses:
        '201':
          description: The created draft study.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Study'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /studies/{id}/:
    parameters:
      - $ref: '#/components/parameters/StudyId'
    get:
      operationId: getStudy
      tags: [Studies]
      summary: Retrieve a study
      responses:
        '200':
          description: A study.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Study'
        '401':
          $ref: '#/components/responses/Unauthorized'
    patch:
      operationId: updateStudy
      tags: [Studies]
      summary: Update a study
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StudyInput'
      responses:
        '200':
          description: The updated study.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Study'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteStudy
      tags: [Studies]
      summary: Delete a study
      responses:
        '204':
          description: The study was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /studies/{id}/transition/:
    parameters:
      - $ref: '#/components/parameters/StudyId'
    post:
      operationId: transitionStudy
      tags: [Studies]
      summary: Transition study status
      description: >-
        Change the status of a study, e.g. PUBLISH a draft, START, PAUSE, or STOP
        an active study.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  enum: [PUBLISH, START, PAUSE, STOP]
      responses:
        '200':
          description: The study in its new status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Study'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /studies/{id}/cost/:
    parameters:
      - $ref: '#/components/parameters/StudyId'
    get:
      operationId: getStudyCost
      tags: [Studies]
      summary: Show study cost
      description: Returns the calculated cost of a study including participant rewards and platform fee.
      responses:
        '200':
          description: Study cost breakdown.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /submissions/:
    get:
      operationId: listSubmissions
      tags: [Submissions]
      summary: List submissions
      description: >-
        Returns basic information of submissions, including study id, participant
        id, status and start timestamp. A study id is required.
      parameters:
        - name: study
          in: query
          required: true
          schema:
            type: string
          description: The study ID to list submissions for.
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: A paginated list of submissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /submissions/{id}/:
    parameters:
      - $ref: '#/components/parameters/SubmissionId'
    get:
      operationId: getSubmission
      tags: [Submissions]
      summary: Retrieve a submission
      responses:
        '200':
          description: A submission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Submission'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /submissions/{id}/transition/:
    parameters:
      - $ref: '#/components/parameters/SubmissionId'
    post:
      operationId: transitionSubmission
      tags: [Submissions]
      summary: Approve or reject a submission
      description: Transition a completed submission to APPROVE or REJECT.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  enum: [APPROVE, REJECT]
                rejection_category:
                  type: string
                message:
                  type: string
      responses:
        '200':
          description: The submission in its new status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Submission'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /submissions/{id}/request-return/:
    parameters:
      - $ref: '#/components/parameters/SubmissionId'
    post:
      operationId: requestReturnSubmission
      tags: [Submissions]
      summary: Request participant return submission
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request_return_reasons:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Return requested.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Submission'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /submissions/bulk-approve/:
    post:
      operationId: bulkApproveSubmissions
      tags: [Submissions]
      summary: Bulk approve submissions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                study_id:
                  type: string
                submission_ids:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Submissions queued for approval.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /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'
  /workspaces/:
    get:
      operationId: listWorkspaces
      tags: [Workspaces]
      summary: Get user's workspaces
      responses:
        '200':
          description: A list of workspaces.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWorkspace
      tags: [Workspaces]
      summary: Create a workspace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                description:
                  type: string
      responses:
        '201':
          description: The created workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /workspaces/{workspace_id}/:
    parameters:
      - $ref: '#/components/parameters/WorkspaceId'
    get:
      operationId: getWorkspace
      tags: [Workspaces]
      summary: Get workspace
      responses:
        '200':
          description: A workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
    patch:
      operationId: updateWorkspace
      tags: [Workspaces]
      summary: Update a workspace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The updated workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /workspaces/{workspace_id}/balance/:
    parameters:
      - $ref: '#/components/parameters/WorkspaceId'
    get:
      operationId: getWorkspaceBalance
      tags: [Workspaces]
      summary: Get workspace balance
      responses:
        '200':
          description: The workspace wallet balance.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /workspaces/{workspace_id}/projects/:
    parameters:
      - $ref: '#/components/parameters/WorkspaceId'
    get:
      operationId: listProjects
      tags: [Projects]
      summary: Get all projects in a workspace
      responses:
        '200':
          description: A list of projects.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createProject
      tags: [Projects]
      summary: Create a project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
      responses:
        '201':
          description: The created project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{id}/:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getProject
      tags: [Projects]
      summary: Get project
      responses:
        '200':
          description: A project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
    patch:
      operationId: updateProject
      tags: [Projects]
      summary: Update a project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The updated project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /messages/:
    get:
      operationId: getMessages
      tags: [Messages]
      summary: Retrieve messages
      description: Get messages between you and another user, or your messages with all users.
      parameters:
        - name: user_id
          in: query
          required: false
          schema:
            type: string
        - name: created_after
          in: query
          required: false
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: A list of messages.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: sendMessage
      tags: [Messages]
      summary: Send a message
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                recipient_id:
                  type: string
                body:
                  type: string
                study_id:
                  type: string
      responses:
        '201':
          description: The message was sent.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /messages/unread/:
    get:
      operationId: getUnreadMessages
      tags: [Messages]
      summary: Retrieve unread messages
      responses:
        '200':
          description: A list of unread messages.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /hooks/event-types/:
    get:
      operationId: listEventTypes
      tags: [Hooks]
      summary: List subscribable event types
      responses:
        '200':
          description: A list of event types.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /hooks/secrets/:
    get:
      operationId: listSecrets
      tags: [Hooks]
      summary: List all secrets
      responses:
        '200':
          description: A list of signing secrets.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createSecret
      tags: [Hooks]
      summary: Create or replace a secret
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                workspace_id:
                  type: string
      responses:
        '201':
          description: The created secret.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /hooks/subscriptions/:
    get:
      operationId: listSubscriptions
      tags: [Hooks]
      summary: List all subscriptions
      responses:
        '200':
          description: A list of subscriptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createSubscription
      tags: [Hooks]
      summary: Create a subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionInput'
      responses:
        '201':
          description: The created subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /hooks/subscriptions/{id}/:
    parameters:
      - $ref: '#/components/parameters/SubscriptionId'
    get:
      operationId: getSubscription
      tags: [Hooks]
      summary: Retrieve a subscription
      responses:
        '200':
          description: A subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
    patch:
      operationId: updateSubscription
      tags: [Hooks]
      summary: Update a subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionInput'
      responses:
        '200':
          description: The updated subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteSubscription
      tags: [Hooks]
      summary: Delete a subscription
      responses:
        '204':
          description: The subscription was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /hooks/subscriptions/{id}/confirm/:
    parameters:
      - $ref: '#/components/parameters/SubscriptionId'
    post:
      operationId: confirmSubscription
      tags: [Hooks]
      summary: Confirm a subscription
      responses:
        '200':
          description: The subscription was confirmed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /hooks/subscriptions/{id}/events/:
    parameters:
      - $ref: '#/components/parameters/SubscriptionId'
    get:
      operationId: getSubscriptionEvents
      tags: [Hooks]
      summary: Get subscription events
      responses:
        '200':
          description: Delivered events for the subscription.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /filters/:
    get:
      operationId: listFilters
      tags: [Filters]
      summary: List all filters
      description: List all filters (requirements) that can be applied to your filter sets or studies.
      responses:
        '200':
          description: A list of filters.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /filters/{filter_id}/distribution/:
    parameters:
      - name: filter_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getFilterDistribution
      tags: [Filters]
      summary: Get filter distribution
      responses:
        '200':
          description: The distribution of participants across the filter's values.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /participant-counts/:
    post:
      operationId: countParticipants
      tags: [Filters]
      summary: Count participants
      description: Count how many eligible participants match a set of filters.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filters:
                  type: array
                  items:
                    type: object
      responses:
        '200':
          description: The count of eligible participants.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /submissions/bonus-payments/:
    post:
      operationId: setupBonusPayments
      tags: [Bonuses]
      summary: Set up bonuses
      description: >-
        Create a bulk bonus payment for a study from a CSV of participant/submission
        IDs and amounts. This does not pay the bonuses; call the pay endpoint after.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                study_id:
                  type: string
                csv_bonuses:
                  type: string
                  description: 'CSV rows of <participant_id>,<amount> or <submission_id>,<amount>.'
      responses:
        '201':
          description: The created bulk bonus payment.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  total_amount:
                    type: number
        '401':
          $ref: '#/components/responses/Unauthorized'
  /bulk-bonus-payments/{id}/pay/:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: payBonusPayments
      tags: [Bonuses]
      summary: Pay bonuses
      description: >-
        Pay a previously created bulk bonus payment. Payment is made asynchronously
        against your workspace balance. Up to 200 participants per request.
      responses:
        '200':
          description: The bonus payment was queued for payment.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/me/:
    get:
      operationId: getMe
      tags: [Users]
      summary: Retrieve the authenticated user
      description: Returns the basic account information for the authenticated user, including ID and email.
      responses:
        '200':
          description: The authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/{id}/:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getUser
      tags: [Users]
      summary: Retrieve a user
      responses:
        '200':
          description: A user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API token supplied as "Token <your token>".'
  parameters:
    StudyId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The study ID.
    SubmissionId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The submission ID.
    GroupId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The participant group ID.
    WorkspaceId:
      name: workspace_id
      in: path
      required: true
      schema:
        type: string
      description: The workspace ID.
    ProjectId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The project ID.
    SubscriptionId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The hook subscription ID.
  responses:
    Unauthorized:
      description: Authentication credentials were missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            detail:
              type: string
            error_code:
              type: integer
    Study:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        internal_name:
          type: string
        description:
          type: string
        status:
          type: string
        external_study_url:
          type: string
        total_available_places:
          type: integer
        reward:
          type: integer
          description: Reward per participant in the study currency's minor units.
        estimated_completion_time:
          type: integer
        project:
          type: string
        filters:
          type: array
          items:
            type: object
    StudyInput:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        external_study_url:
          type: string
        total_available_places:
          type: integer
        reward:
          type: integer
        estimated_completion_time:
          type: integer
        project:
          type: string
        filters:
          type: array
          items:
            type: object
    StudyList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Study'
        _links:
          type: object
    Submission:
      type: object
      properties:
        id:
          type: string
        participant_id:
          type: string
        study_id:
          type: string
        status:
          type: string
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
    Submi

# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/prolific-research/refs/heads/main/openapi/prolific-research-openapi.yml