Studycollections 6 endpoints

GET /api/v1/study-collections/mutually-exclusive

List studies

operationId: StudyCollections_listMutuallyExclusive

Parameters

Name In Required Type Description
project_id query required string

Responses

4XX

Error

200

List of mutually exclusive study collections

GET /api/v1/study-collections/mutually-exclusive
POST /api/v1/study-collections/mutually-exclusive

Create a mutually exclusive study collection.

  • Studies and study collections must be created separately and then added to the mutually exclusive study collection.
  • Both the studies and the study collection must be in the same project.
  • You can only add draft studies to a mutually exclusive study collection.
  • Adding studies which are already in one study collection to another study
    collection will remove the study from the original study collection.
operationId: StudyCollections_createMutuallyExclusiveCollection

Request Body

application/json
schema MutuallyExclusiveStudyCollectionUpdate
Property Type Required
name string optional
study_ids array optional
publish_at string optional
description string optional

Responses

4XX

Error

201

Created

POST /api/v1/study-collections/mutually-exclusive
DELETE /api/v1/study-collections/mutually-exclusive/{id}

Delete a mutually exclusive study collection. This will not delete the studies in the collection.

  • This can only be completed if the study collection is unpublished.
  • This will not delete the studies in the collection.
operationId: StudyCollections_deleteMutuallyExclusive

Parameters

Name In Required Type Description
id path required string

Responses

4XX

Error

204

Deleted

DELETE /api/v1/study-collections/mutually-exclusive/{id}
GET /api/v1/study-collections/mutually-exclusive/{id}

Get a mutually exclusive study collection

operationId: StudyCollections_getMutuallyExclusive

Parameters

Name In Required Type Description
id path required string

Responses

4XX

Error

200

Mutually exclusive study collection

GET /api/v1/study-collections/mutually-exclusive/{id}
PATCH /api/v1/study-collections/mutually-exclusive/{id}

Update a mutually exclusive study collection

operationId: StudyCollections_updateMutuallyExclusive

Parameters

Name In Required Type Description
id path required string

Request Body

application/json
schema MutuallyExclusiveStudyCollectionUpdate
Property Type Required
name string optional
study_ids array optional
publish_at string optional
description string optional

Responses

4XX

Error

200

Mutually exclusive study collection

PATCH /api/v1/study-collections/mutually-exclusive/{id}
POST /api/v1/study-collections/mutually-exclusive/{id}/transition

Transition a mutually exclusive study collection. This is used to:

  • Publish a study collection
  • Cancel publish a study collection
  • Schedule publish a study collection
    • This can be done by setting the publish_at on the study collection at create or patch, then transitioning with the “SCHEDULE_PUBLISH” action
    • Or optionally the publish_at can be provided directly in the body of the transition request
operationId: StudyCollections_transitionMutuallyExclusive

Parameters

Name In Required Type Description
id path required string

Request Body

application/json
schema StudyCollectionsTransitionMutuallyExclusiveRequest
Property Type Required
action string optional
publish_at string optional

Responses

4XX

Error

200

Mutually exclusive study collection

POST /api/v1/study-collections/mutually-exclusive/{id}/transition

Submissions 5 endpoints

GET /api/v1/submissions

Returns basic information of the submissions, including the study id, participant id, status and start timestamp

operationId: Submissions_listBasicInfo

Parameters

Name In Required Type Description
study query optional string

Optional filter by study ID. This is the ID we pass to the survey platform using %STUDY_ID%

Responses

4XX

Error

200

List submissions

GET /api/v1/submissions
POST /api/v1/submissions/bulk-approve

Bulk approve study submissions to pay participants after they have
completed your survey or experiment. There are two variant payloads to
this request.

  1. You can supply a Study ID, and a list of participant IDs, or
  2. You can provide a list of submission IDs
operationId: Submissions_bulkApprove

Request Body

application/json
schema SubmissionsBulkApproveRequest

Responses

4XX

Error

200

Bulk approve in progress

POST /api/v1/submissions/bulk-approve
GET /api/v1/submissions/{id}

Returns the detailed information of a submission, including the
study id, participant id, status and start timestamp

operationId: Submissions_getDetail

Parameters

Name In Required Type Description
id path required string

Submission id. This is the ID we pass to the survey platform
using %SESSION_ID%

Responses

4XX

Error

200

Found

GET /api/v1/submissions/{id}
POST /api/v1/submissions/{id}/request-return

This is an experimental feature that may be subject to change in the future.

It offers researchers the ability to ask a participant to return a submission. The return reason must be provided in the request and can be any free text string.
The Prolific UI allows users to select any of the following options:

  • Didn’t finish the study
  • Encountered technical problems
  • Withdrew consent
  • Other ( uses the free text input)

This constructs a message around the reasons provided so there is no need to provide additional text beyond the reasons.

operationId: Submissions_requestReturn

Parameters

Name In Required Type Description
id path required string

The submission id

Request Body

required
application/json
schema SubmissionsRequestReturnRequest
Property Type Required
request_return_reasons array required

Responses

4XX

Error

200

A message is sent to the participant belonging to the submission asking them to return.

POST /api/v1/submissions/{id}/request-return
POST /api/v1/submissions/{id}/transition

Transition a submission to APPROVED or REJECTED. Once the status is changed, it can not be restored to its previous value.

We strongly recommend that, when giving approval to a submission through the API, you first observe the submission.status.change
event for a status transition to
AWAITING_REVIEW before making the approval request. Our system is currently unable to process approvals before this transition.
Note this endpoint is idempotent, so if you make the same request twice, the second request will be ignored.

operationId: Submissions_transitionById

Parameters

Name In Required Type Description
id path required string

Submission id. This is the ID we pass to the survey platform
using %SESSION_ID%

Request Body

application/json
schema SubmissionTransition
Property Type Required
action string required
message string optional
rejection_category string optional

Responses

4XX

Error

200

Updated

POST /api/v1/submissions/{id}/transition

Surveys 10 endpoints

GET /api/v1/surveys

Get all the surveys for a researcher.

operationId: Surveys_getAll

Parameters

Name In Required Type Description
researcher_id query required string
offset query optional integer
limit query optional integer

Responses

4XX

Error

200

Successful Response

GET /api/v1/surveys
POST /api/v1/surveys

You can create a survey with either sections -> questions or just questions. This allows you to decide
how much flexibility you want in your survey design. However, if you want to render the survey in the Prolific Application, you must use sections.

operationId: Surveys_createOrUpdate

Request Body

required
application/json
schema SurveyIn
Property Type Required
title string required
sections array optional
id string optional
title string required
questions array required
id string optional
type string required
title string required
answers array required
id string optional
value string required
questions array optional
id string optional
type string required
title string required
answers array required
id string optional
value string required
researcher_id string required

Responses

4XX

Error

201

Successful Response

POST /api/v1/surveys
DELETE /api/v1/surveys/{survey_id}

Delete a single Survey.

operationId: Surveys_deleteSingleSurvey

Parameters

Name In Required Type Description
survey_id path required string

Responses

4XX

Error

200

Successful Response

DELETE /api/v1/surveys/{survey_id}
GET /api/v1/surveys/{survey_id}

Get a single survey given an ID.

operationId: Surveys_getSurveyById

Parameters

Name In Required Type Description
survey_id path required string

Responses

4XX

Error

200

Successful Response

GET /api/v1/surveys/{survey_id}
DELETE /api/v1/surveys/{survey_id}/responses

Delete all the responses for a given Survey.

operationId: Surveys_deleteAllResponses

Parameters

Name In Required Type Description
survey_id path required string

Responses

4XX

Error

200

Successful Response

DELETE /api/v1/surveys/{survey_id}/responses
GET /api/v1/surveys/{survey_id}/responses

Get all the responses for a given Survey.

operationId: Surveys_getAllResponses

Parameters

Name In Required Type Description
survey_id path required string

Responses

4XX

Error

200

Successful Response

GET /api/v1/surveys/{survey_id}/responses
POST /api/v1/surveys/{survey_id}/responses

Create a Response for a survey.

operationId: Surveys_createResponse

Parameters

Name In Required Type Description
survey_id path required string

Request Body

required
application/json
schema SurveyResponseIn
Property Type Required
sections array optional
questions array required
answers array required
value string required
answer_id string required
question_id string required
question_title string required
section_id string required
questions array optional
answers array required
value string required
answer_id string required
question_id string required
question_title string required
submission_id string required
participant_id string required

Responses

4XX

Error

201

Successful Response

POST /api/v1/surveys/{survey_id}/responses
GET /api/v1/surveys/{survey_id}/responses/summary

Get an aggregated summary of responses for a given survey.

operationId: Surveys_getSummaryResponses

Parameters

Name In Required Type Description
survey_id path required string

Responses

4XX

Error

200

Successful response

GET /api/v1/surveys/{survey_id}/responses/summary
DELETE /api/v1/surveys/{survey_id}/responses/{response_id}

Delete a single Response.

operationId: Surveys_deleteResponse

Parameters

Name In Required Type Description
survey_id path required string
response_id path required string

Responses

4XX

Error

200

Successful Response

DELETE /api/v1/surveys/{survey_id}/responses/{response_id}
GET /api/v1/surveys/{survey_id}/responses/{response_id}

Get a single response for a survey.

operationId: Surveys_getResponse

Parameters

Name In Required Type Description
survey_id path required string
response_id path required string

Responses

4XX

Error

200

Successful Response

GET /api/v1/surveys/{survey_id}/responses/{response_id}

Users 1 endpoints

GET /api/v1/users/me

Use this endpoint to test your token and retrieve the basic information of your account.

Add an Authorization header with the value Token <your token>.

operationId: Users_getUser

Responses

4XX

Error

200

Successful Response

GET /api/v1/users/me

Workspaces 5 endpoints

GET /api/v1/workspaces

Gets a list of all workspaces that the user is a member of.

operationId: Workspaces_getAllUserWorkspaces

Responses

4XX

Error

200

Success

GET /api/v1/workspaces
POST /api/v1/workspaces

Creates a new workspace and adds the user as a Workspace Admin.

operationId: Workspaces_createWorkspaceAdmin

Request Body

application/json
schema CreateWorkspace
Property Type Required
title string required
currency_code string optional
naivety_distribution_rate number optional

Responses

4XX

Error

201

Created workspace

POST /api/v1/workspaces
GET /api/v1/workspaces/{workspace_id}

Gets a workspace’s details

operationId: Workspaces_getDetails

Parameters

Name In Required Type Description
workspace_id path required string

Workspace id

Responses

4XX

Error

200

Success

GET /api/v1/workspaces/{workspace_id}
PATCH /api/v1/workspaces/{workspace_id}

Updates a workspace’s details.

operationId: Workspaces_updateDetails

Parameters

Name In Required Type Description
workspace_id path required string

Workspace id

Request Body

application/json
schema Workspace
Property Type Required
id string required
owner string optional
title string required
users array optional
id string required
name string optional
email string optional
roles array optional
wallet string optional
projects array optional
id string required
owner string optional
title string required
users array optional
id string required
name string optional
email string optional
roles array optional
description string optional
naivety_distribution_rate number optional
description string optional
naivety_distribution_rate number optional

Responses

4XX

Error

200

Updated workspace redirect link

PATCH /api/v1/workspaces/{workspace_id}
GET /api/v1/workspaces/{workspace_id}/balance

Provides details of the funds available in the workspace.

operationId: Workspaces_getBalance

Parameters

Name In Required Type Description
workspace_id path required string

Workspace id

Responses

4XX

Error

200

Success

GET /api/v1/workspaces/{workspace_id}/balance