Setting up an api_access

An api_access object can be created by

prolific_api_access <- api_access(api_token = "<api_token>")

While all other settings when creating an api_access rarely require adjustment, the api_token is the information that needs to be specified for the API access to work. The prolific.api package’s functionality heavily depends on a a valid api_token. Therefore, the above command prints a console message to indicate that the token is valid:

The token’s validity can also be checked by means of the check_authorization method, which returns TRUE if the token is valid, and FALSE if it is not:

prolific_api_access$check_authorization()
#> [1] TRUE

The section on obtaining an API token describes how to obtain a valid token.

Using an api_access

The actual API access is carried out by means of the access method of the api_access class. The access method wraps different methods for exchanging information with the API that serve different purposes:

This table lists the available methods, which are specified in the method argument of the access method. By default, file transfer is based on curl.

For retrieving information from prolific.co using the get method, a simple example is

prolific_api_access$access(
  method = "get",
  endpoint = "users/me"
)

to obtain information about the account you are accessing the API with.

A simple example for submitting information to the API using the post method is

prolific_api_access$access(
  endpoint = "study-cost-calculator",
  method = "post",
  data = list(
    reward = 100,
    total_available_places = 5
  )
)

to calculate the cost (including fees and taxes) of a study where 5 participants are paid 1 £ each.

More realistic examples are provided in the sections below, while a list of further endpoints is provided in
Prolific’s API documentation.

Creating a prolific_study

A minimal specification for creating a prolific_study contains the following information:

new_study <- prolific_study(
  # Information shown to participants
  name = "<Publicly visible study name>",
  description = "<Publicly visible study description>",
  estimated_completion_time = 1,
  reward = 10,
  # URL participants are redirected to
  external_study_url = "https://www.link_to_my_study.com",
  # Completion code to verify participation
  completion_code = "123",
  # Number of participants to recruit
  total_available_places = 10,
  eligibility_requirements =
    list(
      participant_id_prescreener
    )
)

The information that is presented to the potential participants contains the study’s

• name,
• description,
• estimated completion time,
• reward and
• total available places.

To them, the study will then will be presented as

in the dashboard. Once they select the study in the dashboard, more details are shown:

People deciding to take part in a study can click on “Take part in this study”, which redirects them to the

• external study url

where the study is conducted. Once they completed your study, you should provide them with a

• completion code

and redirect them back to prolific.co. Participant compensation is then based on the completion code by checking whether a participant obtained the correct completion code after completing the study. The compensation does not happen automatically, so you still can check which participants are compensated, e.g. in case of erroneous completion codes.

The above fields are the ones that need to be set in a minimal study specification. For an exhaustive overview of the fields in a prolific_study, see the section on methods and fields access and the documentation help(prolific_study).

prolific_api_access$access(
  endpoint = "studies",
  method = "post",
  data = new_study
)
#> ======================================================================
#> Prolific study summary:
#> ======================================================================
#> name:                      <Publicly visible study name>
#> internal_name:             
#> id:                        64648077334b5b48eebef880
#> project:                   61f12ae112c02bba9e3523b1
#> external_study_url:        https://www.link_to_my_study.com
#> total_available_places:    10
#> reward:                    10
#> ======================================================================

Getting a prolific_study from the platform

The study’s id is also required if you want to obtain a previously created study from prolific.co. For a study that is not yet represented in an R object, we first need to find out its id.

A list of all studies in the Prolific account can be obtained via

# If the study ID is unknown, you can obtain a list of all studies:
list_of_studies <-
  prolific_api_access$access(
    endpoint = "studies",
    method = "get"
  )

which in this case includes only the new study created above:

print(list_of_studies)
#>    creation_day creation_time internal_name
#> 1:   2023-05-17      07:21:27              
#>                             name                       id study_type
#> 1: <Publicly visible study name> 64648077334b5b48eebef880     SINGLE
#>    total_available_places places_taken reward
#> 1:                     10            0     10
#>    max_submissions_per_participant max_concurrent_submissions
#> 1:                               1                         -1
#>         status number_of_submissions total_cost stratum publish_at
#> 1: UNPUBLISHED                     0      139.9      NA         NA
#>    is_underpaying below_prolific_min below_original_estimate
#> 1:             NA                 NA                      NA
#>    quota_requirements is_reallocated privacy_notice
#> 1:                 NA          FALSE             NA

To retrieve the study from the API, we use the study’s endpoint, which is "studies/64648077334b5b48eebef880":

# Obtain the study with ID 64648077334b5b48eebef880 from Prolific
obtained_study <- 
    prolific_api_access$access(
        endpoint = c("studies","64648077334b5b48eebef880"),
        method = "get"
)

Note that the endpoint argument may be a vector, which is then collapsed using /.

Updating Fields in a prolific_study

The fields in a prolific_study can be changed using either S4 and RefClass syntax (see the section on methods and fields access ). For example, you can change the name of new_study using either one:

# S4 class style
name(new_study) <- "How to create and update studies on Prolific"
# Refclass style
new_study$name <- "How to create and update studies on Prolific"

Both lines of code have the same effect: The name of new_study is now “How to create and update studies on Prolific”. Equivalent access works for all other fields in prolific_study objects, which are listed in the section on methods and fields access and the documentation help(prolific_study).

Changing a prolific_study on the platform

To actually apply the changes made in the previous paragraph to the study on prolific.co, prolific_api_access$access with method = "patch" or method = "put" is used:

# Patch new_study on Prolific
prolific_api_access$access(
    endpoint = c("studies",new_study$id),
    method = "patch",
    data = 
)
#> ======================================================================
#> Prolific study summary:
#> ======================================================================
#> name:                      <Publicly visible study name>
#> internal_name:             
#> id:                        64648077334b5b48eebef880
#> project:                   61f12ae112c02bba9e3523b1
#> external_study_url:        https://www.link_to_my_study.com
#> total_available_places:    10
#> reward:                    10
#> ======================================================================

method = "patch" applies all changes made to the study while retaining the settings that are unchanged. In contrast, method = "put" can be used to overwrite an existing study with an entirely new study specification. In many cases, the effect will be the same - but empty fields in a prolific_study will not be changed when using "patch", but will be deleted when using "put".

Deleting a prolific_study on the platform

Ultimately, a study can be deleted using access with method = "delete" on the study’s endpoint

# Delete new_study on Prolific
prolific_api_access$access(
    endpoint = c("studies",new_study$id),
    method = "delete"
)

Setting up prolific_prescreeners

To make a simple example, participants who currently live in the United States can be selected using the prolific_prescreener

us_prescreener <-
  prolific_prescreener(
    title = "Current Country of Residence",
    "United States"
  )

You can combine multiple constraints for a single prescreener. To extend the above prescreener to also allow for participants from the UK, use

uk_us_prescreener <-
  prolific_prescreener(
    title = "Current Country of Residence",
    "United Kingdom",
    "United States"
  )

Some of the prescreeners allow to specify lower and upper boundaries for a numerical variable. For example, participants with an age between 20 and 24 can be selected using the prolific_prescreener

age_prescreener <-
  prolific_prescreener(
    title = "Age",
    "Minimum Age" = 20,
    "Maximum Age" = 24
  )

Using prolific_prescreeners

The prescreeners can be combined in a list and included as the eligibility_requirements field of a prolific_study:

new_study_with_prescreeners <- prolific_study(
  # Information shown to participants
  name = "<Publicly visible study name>",
  description = "<Publicly visible study description>",
  estimated_completion_time = 1,
  reward = 10,
  # URL participants are redirected to
  external_study_url = "https://www.link_to_my_study.com",
  # Completion code to verify participation
  completion_code = "123",
  # Number of participants to recruit
  total_available_places = 10,
  # Constraints that participants have to meet
  eligibility_requirements = list(
    uk_us_prescreener,
    age_prescreener
  )
)

This example creates a study that has the same information as new_study above, but is available only for persons living in the UK or US who are between 20 and 24 years of age.

As above, the study can be submitted to prolific.co using

prolific_api_access$access(
  endpoint = "studies",
  method = "post",
  data = new_study_with_prescreeners
)

To add, remove or change prescreeners in an existing prolific_study, simply
modify the study’s eligibility_requirements field, as described (see the section on updating fields in a prolific_study ). For example, the age requirement specified for new_study_with_prescreeners can be relaxed to allow for participants between the ages of 18 and 28:

new_study_with_prescreeners$eligibility_requirements$
  `Age`$constraints <- list(
  "Minimum Age" = 18,
  "Maximum Age" = 28
)

To limit the study to persons living in the US (i.e. exclude the previously included UK inhabitants), use

new_study_with_prescreeners$eligibility_requirements$
  `Current Country of Residence` <- us_prescreener

The changes can be applied as described in the section on changing a prolific_study on the platform

A full searchable list of all currently available prescreeners (as of 2023-05-17) is available in the following list of available prescreeners. It also includes example code snippets for each prescreener and available constraints.