Prolific bonuses API
The bonuses API from Prolific — 2 operation(s) for bonuses.
OpenAPI Specification
openapi: 3.1.0
info:
title: API 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:
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
ErrorDetailDetail:
oneOf:
- type: string
- type: array
items:
type: string
- $ref: '#/components/schemas/ErrorDetailDetail2'
description: Error detail
title: ErrorDetailDetail
Error:
type: object
properties:
error:
$ref: '#/components/schemas/ErrorDetail'
required:
- error
title: Error
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
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
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>`.'