Prolific API

Hello,
I imagine this might be a big feature to ask, but I think it would be awesome if there were a Prolific API.

A way we could communicate with Prolific from our R/Prolific/other scripts to program things like:

  • exporting the demographics
  • processing bulk approvals
  • process bulk bonus payments
  • sending bulk messages

And maybe other things that I can’t think of right now.

Hey @Samuel_Dupret, this is a great idea that’s come up before. We’re currently looking at working on this. We know how much easier it will make using Prolific.

I’ll let you know as soon as I have concrete updates on this :slight_smile:

1 Like

How to bulk approve a study using the public API

Before you can do the bulk approval shown in step 3, you need to check that you can Authenticate
and that your Study ID works. Or watch this youtube video on how to do bulk approvals.

1. Checking Authentication

For now, you can authenticate by using Basic Authentication, rfc7617.
You need to replace the email:password with your credentials.

curl -u email:password 'https://www.prolific.co/api/v1/users/me/'

This should return the following if your have supplied the correct credentials.

{"id":"60an2fuc693c29420793ut7b","email":"username@gmail.com","first_name" ...

2. Check Study ID

To get the study id, you need to navigate to your study in the active tab. The url at the top of the browser
will look something like this.

https://app.prolific.co/studies/<study_id>/submissions
e.g. https://app.prolific.co/studies/60f6acb180a7b59ac0621f9e/submissions

Now put the <study_id> string into the following url and send the curl request.

curl -u email:password 'https://www.prolific.co/api/v1/studies/<study_id>/submissions/?offset=0&limit=10'

If you get the following response then your study id is working.

> {"results":[{"id":"60f6d313d530edde21564465","participant_id":"5ce69ff9b1e73b000146186d" ...

3. Bulk approval

Once you can authenticate and you know your study id works, you can then use the following API to
bulk approve.

curl -u email:password \
--request POST 'https://www.prolific.co/api/v1/submissions/bulk-approve/' \
--header 'Referer: https://app.prolific.co/' \
--header 'Content-Type: application/json' \
--data-raw '{"study_id": "<study_id>","participant_ids":["<from_survey_tool>", "<from_survey_tool>"]}'

You need to use the following schema for your data in the --data-raw, the following shows an example of this POST data.

{
  "study_id":"60f6acb180a7b59ac0621f9e", 
  "participant_ids":["60f25f799fbd8a136cc6a9b0", "5ce69ff9b1e73b000146186d"]
}

study_id from step 1. Check study ID

participant_ids from survey tool i.e. qualtrics, google forms …

3 Likes

@Samuel_Dupret You asked and we listened!

Check out @Andrew_Arderne’s guide :arrow_up:

This is a very early first development, so do let us know your thoughts :slight_smile:

Wow, that’s awesome! Thank you @Josh and @Andrew_Arderne !

I had a go at it with R and I managed to bulk approve my study. Wonderful :slight_smile: I am looking forward to be able to do bonuses that way.

3 Likes

Bulk bonus payment API

Once you can authenticate and you know your study id works, you can then use the following API to
bulk pay bonuses. This process takes 2 steps, creating the bulk processing data and then paying it out.

1. Creating bulk payment data

curl -u email:password \
--request POST 'https://www.prolific.co/api/v1/submissions/bonus-payments/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "study_id": "61000180997ce18e0cd801b3",
    "csv_bonuses": "60ffe5c8371090c7041d43f8,0.20\n60ff44a1d00991f1dfe405d9,0.20"
}'

You need to use the following schema for your data in the --data-raw, the following shows an example of this POST data. The csv_bonuses contain the participant_ids that you should have from your survey tool.

{
    "study_id": "61000180997ce18e0cd801b3",  \\ taken from study url
    "csv_bonuses": "60ffe5c8371090c7041d43f8,0.20\n60ff44a1d00991f1dfe405d9,0.20"
}

csv_bonuses structure: String(participant_id comma amount new_line)

The line below shows an example of this CSV format.

60ffe5c8371090c7041d43f8,0.20\n60ff44a1d00991f1dfe405d9,0.20\n610001c69ef2254561beee980.30

Running that curl command should return similar data to this, the id is important here and will be used in the next step.

> {
    "id": "61015b057bd72ddc7244edb9",  // <-- used in next step as bulk_payments_id
    "study": "61000180997ce18e0cd801b3",
    "amount": 40.0,
    "fees": 0.0,
    "total_amount": 40.0,
    "vat": 0.0
}

2. Process payments

Now that everything is setup, copy the bulk_payments_id and replace it with the url below

curl -u email:password \
--request POST 'https://www.prolific.co/api/v1/bulk-bonus-payments/<bulk_payment_id>/pay/'

An example of this request with the data from step 1

curl -u email:password \ 
--request POST 'https://www.prolific.co/api/v1/bulk-bonus-payments/61015971a62d280b3b4ebfc6/pay/'

If this works it should return the following message, you can also see the amount shown on the study page.

> "Successfully processed bonus payments."
3 Likes

@Samuel_Dupret , @Andrew_Arderne strikes again!

Awesome! I don’t have bonus payments to do right now and I am off for a week but I will give that a try when I get back.

Hey! I’m affiliated with PsychoPy/PsychoJS/Pavlovia. We’ve seen other devs create “study portals” to manage Pavlovia, like VESPR. I wondered if we could extend that idea to Prolific and then discovered this thread. The web API already covers the most important use cases; cool :slight_smile:

I’ve got a feature request/suggestion: could I request an API key? I.e., some auto-generated string that the researcher can copy-paste from Prolific into another application. Then the other application doesn’t need to know the researchers’ password for authenticating itself to the web API.

1 Like

Hi @Thomas_Pronk ,

I am a backend engineer at Prolific.

We are actively thinking of offering an API key to increase security when using the API.
And we have also been looking at PsychoPy and wondered how could we make it easy to integrate with Prolific.
Would you like to talk with us?

Hi @Jonas_Anso, nice to meet you!

Yes, I’d love to. Actually, I found out that Jon (our CEO) is already planning a web API meetup. I guess we’ll talk soon :slight_smile:

Cheers, Thomas

1 Like

Great! I will ask @Elaine to add you to the meeting.

2 Likes