openapi: 3.0.3
info:
  title: Prolific Bonuses 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: Bonuses
  description: Bulk bonus payments to participants.
paths:
  /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'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            detail:
              type: string
            error_code:
              type: integer
  responses:
    Unauthorized:
      description: Authentication credentials were missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API token supplied as "Token <your token>".