PRprolific
rewardRecommendations

Calculate reward recommendations

Changed on

Calculate the recommended participant reward rates for a data collection, optionally based upon a given set of filters.

min_reward_per_hour is the higher of Prolific's platform minimum and the minimum set for the workspace. GET does not include verified-filter minimums, which may raise the minimum required to publish a study. min_reward_per_hour_source identifies which floor supplies the returned minimum. If no recommendations are available, a single GLOBAL entry carrying that minimum and source is returned. The same entry is returned if the recommendation service is unavailable (it errors, returns a 5xx, or returns an unreadable body). Client errors (4xx) from the recommendation service are returned unchanged.

get/api/v1/reward-recommendations/

Request

  • Base URL
    https://api.prolific.com
  • URL
    https://api.prolific.com/api/v1/reward-recommendations/
  • Auth
    API key in header Authorization

Query parameters

workspace_idstring required

The ID of the workspace in which you'll be creating the study

currency'USD' | 'GBP' required

An ISO 4217 currency code. Note that we only support a selection of currency codes as per the enum values.

screener_idsstring

A URL-encoded, comma-delimited list of filter IDs (e.g. custom group filter IDs) that you plan to apply to your study.

There are various methods of converting an array of filter IDs to a URL-encoded, comma delimited array e.g:

JavaScript:

const screenerIDs = ["mandarin", "spanish"];
const encodedScreenerIDs = encodeURIComponent(screenerIDs.join(","));
const url = `https://api.prolific.com/api/v1/reward-recommendations?screener_ids=${encodedScreenerIDs}&workspace_id=<workspace ID>&currency=GBP`

Python:

import urllib.parse

screener_ids = ["mandarin", "spanish"]
encoded_screener_ids = urllib.parse.quote(",".join(screener_ids))
url = f"https://api.prolific.com/api/v1/reward-recommendations?screener_ids={encoded_screener_ids}&workspace_id=<workspace ID>&currency=GBP"

Response

A list of reward recommendations. We suggest using the first recommendation in the list as this is guaranteed to be the most recent set of reward rates.

currency'USD' | 'GBP'

An ISO 4217 currency code. Note that we only support a selection of currency codes as per the enum values.

min_reward_per_hourinteger

The minimum hourly reward rate returned for the request. GET applies the higher of Prolific's platform minimum and the workspace minimum. POST also includes the minimum for the verified filters selected. Studies below the applicable minimum cannot be published.

Note that this is returned as the hundredth subunit of the given currency i.e:

  • for USD, this will be the value in cents
  • for GBP, this will be the value in pence

To display this as USD or GBP respectively, you'll need to divide this value by 100 and use an appropriate number formatting API e.g:

JavaScript:

new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(2000/ 100); // "$20.00"
min_reward_per_hour_source'PLATFORM' | 'VERIFIED' | 'WORKSPACE' required

Which floor sets the enforced minimum.

  • WORKSPACE: the minimum set for the workspace.
  • VERIFIED: the minimum for the verified filters selected (POST only).
  • PLATFORM: Prolific's minimum.

When floors are tied, WORKSPACE takes precedence over VERIFIED, which takes precedence over PLATFORM. More sources may be added, so treat any other value as Prolific's minimum.

recommended_reward_per_hourinteger

The good hourly reward rate that we recommend you pay to your study's participants.

Note that this is returned as the hundredth subunit of the given currency i.e:

  • for USD, this will be the value in cents
  • for GBP, this will be the value in pence

To display this as USD or GBP respectively, you'll need to divide this value by 100 and use an appropriate number formatting API e.g:

JavaScript:

new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(2000/ 100); // "$20.00"

Changes

  • 0ef16a364976Revision changes
    • info

      added the required property / to the response with the status

  • 6c9aa73fa51fRevision changes
    • warning

      deleted the header request parameter Authorization

    • info

      the endpoint scheme security token was added to the API