The Prolific API is Live! Give us your thoughts :)

Prolific API

You can now access the first version of the Prolific API to connect your platform to Prolific! Our aim is to allow anyone to build integrations with Prolific.

This is just the first version, so we’d love to get your thoughts:

  • Do you want to see more functionalities?
  • How can we make it better?
  • What would help you with your integration plan?

Leave your thoughts below!

(@Samuel_Dupret check it out)

Hi,
Are there any examples for R?

1 Like

The tool we are currently using to share our API, offers code generation in many languages but sadly not R.

@Eli_Awtrey proposed to create an R package. @Eli_Awtrey can you help @Tim_Bates ?

2 Likes

Most analysis is done in R now, I imagine?
My use cases would be

  1. Approve participants automatically. Something like:
passingPIDs = someFunction(df)
prolificApprove(passingPIDs, studyID)
  1. Merging demographics with Questionnaire data:
demog = prolificGetDemo(myStudy)
df = mergeDemog(df, demog)

Others opportunities might be a bit one-off to bother automating, like triggering data download when study finishes

2 Likes

Hi Tim,

At the moment, we are focusing on documenting / improving the API and rely on the community to build open sourced clients / packages in different languages.

In the future, we might start building packages for languages that the community has not picked up but are very valuable like R.

Approving submissions is documented here
I add to the list of endpoints that needs documentation how to get demographic data of the submissions.

Thanks for the details of your needs, that helps us plan better.

1 Like

Hi all,

We have expanded the documentation for the API.


Now there is fully detailed information on how to define prescreening requirements for your studies.

Do you need information on how to do something via the API that is not already documented?

Please let us know in this thread.

Hi! I’m really glad that an API is being added to Prolific!

This feature request might be a little late for my current project, but one thing I’d love to have is an API for updating an allowlist for a study. I’m trying to run a 2 stage study (as suggested in your custom sample docs) where the first study is a quick study for custom prescreening, and the second is the actual study for people who meet my specific requirements.

Currently, I have to manually copy the list of eligible prolific IDs from stage 1 and paste them into the “add participants to allowlist” form on the Prolific website. It would be great if I could use the API to add participants to the allowlist, so that I can programmatically add people to stage 2 who meet my custom prescreening requirements as soon as they submit their stage 1 results. I don’t think the allowlist is currently documented in the eligibility_requirements field of “Create a draft study”, nor is there an endpoint for updating an active study.

Hi @Eric_Zeng ,

Check out our updated documentation that explains how to update requirements on draft study.

You can use something like this to set all the participants you want to allow access to your second study.

curl -X PATCH "https://api.prolific.co/api/v1/studies/$study_id/" \
    -H "authorization: Token $token" \
    -d "
{
  "eligibility_requirements": [
    {
      "_cls": "web.eligibility.models.CustomWhitelistEligibilityRequirement",
      "attributes": [
        {
          "value": [
            "$participant_id1",
            "$participant_id2",
          ]
        }
      ]
    }
  ]
}"

If you want a token and try it out, send us an email to integrations@prolific.co

Great, thanks Jonas! This looks like exactly what I need.

1 Like

Hi,

I’ve been trying to work with the API and I have come across a question that doesn’t seem to be in the documentation.

In order to approve a submission the API header requires a Referer (API doc)
However, it is not specified what Referer is and it is the only place in the API documentation that is mentioned.
Is this a leftover from an early beta version of the API and can it be ignored or where would I find what to enter there?

I hope that you can help me and thanks in advance :slight_smile:

Hi @Mads_Kock_Pedersen ,

We will improve that soon, for now, send https://api.prolific.co as the referrer for that endpoint.

Thank you @Jonas_Anso, that was a great help.

And thank you for a great API. I’ve been playing a bit around with it, and it’s very easy to use and quite good documentation already.

1 Like

We have changed the location of our API docs.

https://docs.prolific.co/docs/api-docs/public/

Same thing, new location :slight_smile:

We are constantly improving our docs, if you find something missing, or something we can improve please let us know.

Hi @Jonas_Anso,

since I would like to familiarize myself with your API, I requested a token for authentication via e-Mail to integrations@prolific.co on last Wednesday.

However, I did not (yet) get any response, not even a notification that my mail was received.
Is integrations@prolific.co actually monitored and the right address to request an API token?

1 Like

Hi @Simon_Lenau

I have sent the token, let me know if you have any issues or questions.

Thank you @Jonas_Anso!

In the meanwhile, I tried it out quite a bit, and find the API very useful.

The only thing I am struggling to find out is if and how I can specify the workspace and project a study is created in.

From retrieving studies from /api/v1/studies/{id}/, I see that there are fields for the project and the workspace identifier. However, when creating (or updating) a study, specifying these fields in the uploaded json files does not seem to have any effect.

I really wonder whether I am doing something wrong. I know that workspaces are still a beta feature, but I can not even manage to specify a project for new studies.

I would appreciate any help / support in this regard.

Thank you!

1 Like

Hi @Simon_Lenau ,

Thanks a lot for trying out our beta for workspaces and sorry that we do not have good documentation available yet on how to create a study inside a project.
We will update the docs when the feature is widely adopted.

Currently, it is not possible to do it.

Please let me know if you can use an account that is not in the beta.

If that is not possible by next week I can give you some details on how to create a study inside a project.

If you would like to have a deeper chat, send us an email at integrations@prolific.co

1 Like

Hi,

I just started playing with the API. Looks great so far, but I still get some 500 errors.

I tried the following and all are working as expected:

  • /api/v1/study-cost-calculator/
  • /api/v1/eligibility-requirements/
  • /api/v1/studies/
  • /api/v1/studies/{id}
  • /api/v1/submissions/
  • /api/v1/submissions/{id}/transition/
  • /api/v1/submissions/bonus-payments/
  • /api/v1/bulk-bonus-payments/{id}/pay/

But when trying to use /api/v1/eligibility-count/ or /api/v1/studies/ (POST to create a draft) I get a 500 status.

Trying the two POST data examples in the API docs with /api/v1/eligibility-count/ I get:

Status 500, when using first example:

{
  "eligibility_requirements": []
}

Status 500, when using second example:

{
  "eligibility_requirements": [
    {
      "type": "range",
      "attributes": [
        {
          "name": "min_age",
          "value": 27
        },
        {
          "name": "max_age",
          "value": 61
        }
      ],
      "query": {
        "id": "54ac6ea9fdf99b2204feb893"
      },
      "_cls": "web.eligibility.models.AgeRangeEligibilityRequirement"
    }
  ]
}

However, I get status 200 when using:

{}

Error message of status 500:

{'error': {'additional_information': '/api/v1/errors/',
           'detail': 'The API was unable to process the request.: \n'
                     '    A problem has occurred while trying to process the request.\n'
                     '    Please see error message for more details.\n'
                     '    If the issue persists please contact an admin.\n'
                     '    ',
           'error_code': 100000,
           'interactive': False,
           'status': 500,
           'title': "We're sorry. There was an error while  performing the "
                    'requested action.'}}

Also get the same error when trying the minimal_study example for /api/v1/studies/.

What am I doing wrong here?

2 Likes

Hey @jul, welcome to the community! We’re glad you’re here :tada:

@Jonas_Anso, any ideas? :slight_smile:

Thanks @jul for checking out and reaching out to us.

I will look into this issue tomorrow morning and let you know what I find.