Prolific bonuses API

openapi: 3.2.0
info:
  title: Reference aiTaskBuilder Bonuses API
  version: 1.0.0
servers:
- url: https://api.prolific.com
  description: Production
tags:
- name: bonuses
paths:
  /api/v1/submissions/bonus-payments/:
    post:
      operationId: create-bonus-payments
      summary: Set up bonuses
      description: 'Set up bonus payments to one or more participants/submissions in a study.


        You need the study id, the participant|submission ids and the request in CSV format.


        The csv_bonuses field needs to be structured in the format of either:


        - `<participant_id>,<amount>\n`.

        - `<submission_id>,<amount>\n`.


        **Note: The amount will be in the study currency. The amount should be a decimal value, e.g. 1.50 for £1.50.**

        Warning: An amount of 30 will pay £/$30.00.


        As an example, `60ffe5c8371090c7041d43f8,4.25` would be a bonus of £4.25 for participant 60ffe5c8371090c7041d43f8 in a study with GBP currency.


        Setting up a bonus payment does not actually pay them, to do so check [/api/v1/bulk-bonus-payments/{id}/pay/](#tag/Bonuses/paths/~1api~1v1~1bulk-bonus-payments~1%7Bid%7D~1pay~1/post)


        The submission and participant IDs need to have taken part in the study in order for this call to be successful.

        If not, you will get a "400" HTTP response back, which explains which IDs are incorrect.


        We recommend a maximum of 200 participant or submission IDs per request.'
      tags:
      - bonuses
      parameters:
      - name: Authorization
        in: header
        description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.


          Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


          If your token is leaked, delete it and create a new one directly in the app.


          In your requests add `Authorization` header with the value `Token <your token>`.'
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Bonus created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkBonus'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                study_id:
                  type: string
                csv_bonuses:
                  type: string
  /api/v1/bulk-bonus-payments/{id}/pay/:
    post:
      operationId: pay-bonus-payments
      summary: Pay bonuses
      description: 'Bonus payments are made asynchronously.

        The payment will be done in the following minutes and your balance will be updated accordingly.


        <Warning>

        This endpoint is **not idempotent**. Sending multiple requests with the same bulk bonus payment ID will result in participants being paid multiple times. Ensure you send this request only once per bulk payment.

        </Warning>'
      tags:
      - bonuses
      parameters:
      - name: id
        in: path
        description: Bulk bonus payment id
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.


          Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


          If your token is leaked, delete it and create a new one directly in the app.


          In your requests add `Authorization` header with the value `Token <your token>`.'
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Successfully received bonus payments request. The bonuses will be paid asynchronously.
          content:
            application/json:
              schema:
                type: string
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ErrorDetailDetail:
      oneOf:
      - type: string
      - type: array
        items:
          type: string
      - $ref: '#/components/schemas/ErrorDetailDetail2'
      description: Error detail
      title: ErrorDetailDetail
    ErrorDetailDetail2:
      type: object
      properties:
        any_field:
          type: array
          items:
            type: string
          description: Name of the field with a validation error and as a value an array with the error descriptions
      description: All fields with validation errors
      title: ErrorDetailDetail2
    ErrorDetail:
      type: object
      properties:
        status:
          type: integer
          description: Status code as in the http standards
        error_code:
          type: integer
          description: Internal error code
        title:
          type: string
          description: Error title
        detail:
          $ref: '#/components/schemas/ErrorDetailDetail'
          description: Error detail
        additional_information:
          type: string
          description: Optional extra information
        traceback:
          type: string
          description: Optional debug information
        interactive:
          type: boolean
      required:
      - status
      - error_code
      - title
      - detail
      title: ErrorDetail
    BulkBonus:
      type: object
      properties:
        id:
          type: string
          description: Bonus ID. It is the ID to be used when paying the bonus
        study:
          type: string
          description: Study ID
        amount:
          type: number
          format: double
          description: The amount the participant will receive in cents
        fees:
          type: number
          format: double
          description: The fees Prolific will charge for this bonus in cents
        vat:
          type: number
          format: double
          description: The VAT cost for this bonus in cents
        total_amount:
          type: number
          format: double
          description: Total amount that will be deducted from your balance in cents
      required:
      - id
      - total_amount
      title: BulkBonus
    Error:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      required:
      - error
      title: Error
  securitySchemes:
    token:
      type: apiKey
      in: header
      name: Authorization
      description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.


        Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


        If your token is leaked, delete it and create a new one directly in the app.


        In your requests add `Authorization` header with the value `Token <your token>`.'