openapi: 3.0.3
info:
  title: Prolific Bonuses Submissions 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: Submissions
  description: Review, approve, reject, and return participant submissions.
paths:
  /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'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            detail:
              type: string
            error_code:
              type: integer
    SubmissionList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Submission'
        _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
  responses:
    Unauthorized:
      description: Authentication credentials were missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    SubmissionId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The submission ID.
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API token supplied as "Token <your token>".