How to do your first API calls with Prolific

Introduction

With Prolific API, you can recruit high-quality participants and manage your research workflows programmatically through your own app.

The most important thing is understanding that the API helps you interface with the main objects and interact with them, which is key in a research workflow. Here, we will interface with the Study and the Participant Group objects. There are other objects you can interact with, but they are not covered here.

• The study which will be linked to your survey
• The participant group associated with this study
• The screener you can apply pre-study

Objects and states

This tutorial will focus on interfacing with the Study and Participant Group objects.

Each Study object will have different states. Here are the states:

• Unpublished - When a study is created, it is in a draft format.
• Scheduled - Study is scheduled to be published at a specific date. Study is 'Active' when published.
• Active - Study is published to participants.
• Paused - Study is paused, participants are not shown the study and cannot make submissions.
• Awaiting review - All participant submissions are completed, and not all have been reviewed yet.
• Completed - All submissions have been reviewed.

In this tutorial, we will help you to make your first Prolific API calls. We will cover:

Create your test environment

Modify a study via API

Creating a prescreening study with a survey

First Prolific API Calls

Create your environment

What you'll need:

A survey link from your survey platform of choice. If you don’t have one, here’s one you can copy from Typeform - or you can create a simple one via the Prolific Survey builder.

Time: 30 min

Create your test environment

1. Create a test account on prolific as a researcher account
2. Share the email associated with this account with API Support or the Customer Success Manager you are currently engaged with within the prolific team. If you don’t have someone assigned to you, please reach out to sales@prolific.com.
3. Read our developer documentation: https://docs.prolific.com/docs/api-docs/public/
4. Log into your prolific researcher account and create the study and its survey and screener to filter participants

• Create a workspace MyWorkspace
• Create a project MyProject
• Create a study MyStudy
• Create a screener set for example, "developer not developer"
• Setup your survey link

Now you’ve created your test environment!

This environment is a soft live testing environment linked to real participants. If you'd like to have a sandbox environment, get in touch with our sales or API Support team, and they will be able to set you up.

Get Access/authenticate with your API Token

• Go into your workspace
• Click on settings
• Click Go to the API token page
• Click Create API token
• Input Token name

Your token will then be ready to copy. Next:

• Capture workspace id from URL given
• Given https://app.prolific.com/researcher/workspaces/{workspace_id}/settings/tokens
• In this example, the workspace ID is: 6552422d9da4ef6fbe8a6044
• https://app.prolific.com/researcher/workspaces/6552422d9da4ef6fbe8a6044/settings/tokens

Important note: In the current API version, the token, while sitting under a workspace, is an account level token. As such, the token is the same across all workspaces created under the account. Please contact API Support if you want more information on this.

Modify a study via API

What you'll need:

You need to have access to your test account you created above. You'll also need to have your Postman or similar REST Client ready for action!

Time: 30 min

Concept

Interacting with the Prolific platform using the API is done by using objects. In this example, we'll use the study object.

As a first API call you will modify your existing test study, by changing the number of participants.

As we mentioned in the introduction part of this guide, the study acts as a state machine. We’ll just be looking at states from ‘Unpublished’ to ‘Active’. To find out more about accessing your study via the API, check out our Study APIs documentation.

Modify the Study object

1. Go to the study area

• Log into the account
• select your workspace
• Select your project
• Select the study

Within the study you will be able to get the Study id {id} from the URL.

https://app.prolific.com/researcher/workspaces/studies/{id}}

1. Given the Study id {id} You will patch a study as follows by changing the number to 200

Your test environment is created. Let’s now go to the API by creating your access as presented in Create your environment.

Now, it's time for you to publish this study.

Publish the study (optional)

What you'll need

If you have completed the previous part of the tutorial, you should have a study ready to be published.

Time: 30 min

Concept

Once created, a study is initially unpublished. You can choose to publish it straight away or schedule it via the user interface or via the API.

How to publish a study via API

In this section, we’ve included some python code for this API that you can modify to publish your study programmatically:

You can also access this via the UI.

How to publish a study manually

• Log into your account
• Select the workspace
• Select the project
• Select the study
• Click edit
• Click Publish Now
  

Creating prescreening study within a survey

What you'll need

• Make sure you've kept the token you created in create your environment.
• Get in touch with the API Support team, as you will need access to your researcher_id.
• Review the cost per submission on your account.
• Remember, your test account is a soft live account linked to a real participant group.

Time: 60-90 min

Concept

Pre-screening involves inviting a group of participants to complete a short survey (or ‘screener’) to define a subset of the initial group. In the example below, we’ll create a screener for a study on people’s experiences of watching the World Cup.

Our goal is to pre-screen for participants who have actually watched the World Cup. Then we’ll create a second study with the participants we pre-screened to understand their experience of watching the World Cup.

The example given is in Python, but feel free to use what you feel comfortable with!

How to create a pre-screening study

1. Contact the Prolific API Support team to get your researcher_id.
2. Create a survey object for pre-screening called “Do you watch the World Cup?”
   • This is going to allow us to define two groups:
     • People who watch the world cup.
     • People who don't watch the world cup.

1. Create the Study by passing the Survey survey_id created above as an input by using the CreateStudy API.

Publishing the Study

It’s time to publish your study! You’ll need to pass the draft study identifier study_id with the PublishStudy API.

Getting the study Results

Study Completion state

Before you can get the study results, the study needs to be completed.

There are two ways to get results from study and its state of completion at this stage. You can opt for for a real-time or a delayed approach:

1. Real-time:
   1. Throttle API pull approach
   2. Webhook approach
2. Delayed:
   1. Timeout/duration preset: Using Max time Survey
   2. Threshold completion: Using Max participant

Here, we'll examine the delayed approach and wait for completion. If you are interested in learning more, please contact API Support.

Survey Result and participants submissions

Now we wait until we reach either the limit duration for this study or the threshold of maximum participants for it's completion.

The participants should have now submitted their answers, creating the prescreened group of people who have watched the world cup.

The prescreen is the result of the first study which checks who watched the world cup.

Using a prescreened participant group

We’ll now be able to use these results for our second study, “What did you think of the world cup?”

Now, let’s publish this second study:

That’s it - you’ve published your first pre-screener study using the Prolific API!