openapi: 3.0.3 info: title: Prolific API description: >- The Prolific API is a versioned REST interface for the Prolific online research participant recruitment platform. Researchers use it to programmatically create and publish studies, review and approve submissions, manage participant groups, projects and workspaces, apply demographic filters and requirements, pay bonuses, message participants, and subscribe to event webhooks (hooks). The API is served from https://api.prolific.com/api/v1 and follows a standard REST pattern: a collection endpoint (.../resource/) for GET (list) and POST (create), and an element endpoint (.../resource/{id}/) for GET, PATCH/PUT, and DELETE. All requests are authenticated with an API token supplied in the Authorization header as "Token ". version: v1 contact: name: Prolific url: https://docs.prolific.com/api-reference license: name: Proprietary url: https://www.prolific.com/terms servers: - url: https://api.prolific.com/api/v1 description: Prolific API v1 security: - tokenAuth: [] tags: - name: Studies description: Create, publish, and manage research studies. - name: Submissions description: Review, approve, reject, and return participant submissions. - name: Participant Groups description: Saved, dynamic groups of participant IDs used as allowlist/blocklist filters. - name: Projects description: Organize studies within a workspace. - name: Workspaces description: Top-level containers that hold projects, fund studies, and scope teams. - name: Messages description: Communicate with participants. - name: Hooks description: Event webhook subscriptions and signing secrets. - name: Filters description: Demographic and screening requirements and eligibility counts. - name: Bonuses description: Bulk bonus payments to participants. - name: Users description: Authenticated account and user identity. paths: /studies/: get: operationId: listStudies tags: [Studies] summary: List all studies description: Lists all studies, with the option to filter by study status. parameters: - name: state in: query required: false schema: type: string description: Filter studies by status (e.g. UNPUBLISHED, ACTIVE, COMPLETED). responses: '200': description: A paginated list of studies. content: application/json: schema: $ref: '#/components/schemas/StudyList' '401': $ref: '#/components/responses/Unauthorized' post: operationId: createStudy tags: [Studies] summary: Create a draft study description: Creates a new draft study. Publishing is a separate transition step. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StudyInput' responses: '201': description: The created draft study. content: application/json: schema: $ref: '#/components/schemas/Study' '401': $ref: '#/components/responses/Unauthorized' /studies/{id}/: parameters: - $ref: '#/components/parameters/StudyId' get: operationId: getStudy tags: [Studies] summary: Retrieve a study responses: '200': description: A study. content: application/json: schema: $ref: '#/components/schemas/Study' '401': $ref: '#/components/responses/Unauthorized' patch: operationId: updateStudy tags: [Studies] summary: Update a study requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StudyInput' responses: '200': description: The updated study. content: application/json: schema: $ref: '#/components/schemas/Study' '401': $ref: '#/components/responses/Unauthorized' delete: operationId: deleteStudy tags: [Studies] summary: Delete a study responses: '204': description: The study was deleted. '401': $ref: '#/components/responses/Unauthorized' /studies/{id}/transition/: parameters: - $ref: '#/components/parameters/StudyId' post: operationId: transitionStudy tags: [Studies] summary: Transition study status description: >- Change the status of a study, e.g. PUBLISH a draft, START, PAUSE, or STOP an active study. requestBody: required: true content: application/json: schema: type: object properties: action: type: string enum: [PUBLISH, START, PAUSE, STOP] responses: '200': description: The study in its new status. content: application/json: schema: $ref: '#/components/schemas/Study' '401': $ref: '#/components/responses/Unauthorized' /studies/{id}/cost/: parameters: - $ref: '#/components/parameters/StudyId' get: operationId: getStudyCost tags: [Studies] summary: Show study cost description: Returns the calculated cost of a study including participant rewards and platform fee. responses: '200': description: Study cost breakdown. content: application/json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' /submissions/: get: operationId: listSubmissions tags: [Submissions] summary: List submissions description: >- Returns basic information of submissions, including study id, participant id, status and start timestamp. A study id is required. parameters: - name: study in: query required: true schema: type: string description: The study ID to list submissions for. - name: page_size in: query required: false schema: type: integer default: 20 responses: '200': description: A paginated list of submissions. content: application/json: schema: $ref: '#/components/schemas/SubmissionList' '401': $ref: '#/components/responses/Unauthorized' /submissions/{id}/: parameters: - $ref: '#/components/parameters/SubmissionId' get: operationId: getSubmission tags: [Submissions] summary: Retrieve a submission responses: '200': description: A submission. content: application/json: schema: $ref: '#/components/schemas/Submission' '401': $ref: '#/components/responses/Unauthorized' /submissions/{id}/transition/: parameters: - $ref: '#/components/parameters/SubmissionId' post: operationId: transitionSubmission tags: [Submissions] summary: Approve or reject a submission description: Transition a completed submission to APPROVE or REJECT. requestBody: required: true content: application/json: schema: type: object properties: action: type: string enum: [APPROVE, REJECT] rejection_category: type: string message: type: string responses: '200': description: The submission in its new status. content: application/json: schema: $ref: '#/components/schemas/Submission' '401': $ref: '#/components/responses/Unauthorized' /submissions/{id}/request-return/: parameters: - $ref: '#/components/parameters/SubmissionId' post: operationId: requestReturnSubmission tags: [Submissions] summary: Request participant return submission requestBody: required: true content: application/json: schema: type: object properties: request_return_reasons: type: array items: type: string responses: '200': description: Return requested. content: application/json: schema: $ref: '#/components/schemas/Submission' '401': $ref: '#/components/responses/Unauthorized' /submissions/bulk-approve/: post: operationId: bulkApproveSubmissions tags: [Submissions] summary: Bulk approve submissions requestBody: required: true content: application/json: schema: type: object properties: study_id: type: string submission_ids: type: array items: type: string responses: '200': description: Submissions queued for approval. content: application/json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' /participant-groups/: get: operationId: listParticipantGroups tags: [Participant Groups] summary: Get all participant groups description: List participant groups scoped to a workspace_id or project_id. parameters: - name: workspace_id in: query required: false schema: type: string - name: project_id in: query required: false schema: type: string responses: '200': description: A list of participant groups. content: application/json: schema: $ref: '#/components/schemas/ParticipantGroupList' '401': $ref: '#/components/responses/Unauthorized' post: operationId: createParticipantGroup tags: [Participant Groups] summary: Create participant group requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ParticipantGroupInput' responses: '201': description: The created participant group. content: application/json: schema: $ref: '#/components/schemas/ParticipantGroup' '401': $ref: '#/components/responses/Unauthorized' /participant-groups/{id}/: parameters: - $ref: '#/components/parameters/GroupId' get: operationId: getParticipantGroup tags: [Participant Groups] summary: Get a participant group responses: '200': description: A participant group. content: application/json: schema: $ref: '#/components/schemas/ParticipantGroup' '401': $ref: '#/components/responses/Unauthorized' patch: operationId: updateParticipantGroup tags: [Participant Groups] summary: Update a participant group requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ParticipantGroupInput' responses: '200': description: The updated participant group. content: application/json: schema: $ref: '#/components/schemas/ParticipantGroup' '401': $ref: '#/components/responses/Unauthorized' delete: operationId: deleteParticipantGroup tags: [Participant Groups] summary: Delete a participant group responses: '204': description: The participant group was deleted. '401': $ref: '#/components/responses/Unauthorized' /participant-groups/{id}/participants/: parameters: - $ref: '#/components/parameters/GroupId' get: operationId: getGroupParticipants tags: [Participant Groups] summary: Get group participants responses: '200': description: The participant IDs in the group. content: application/json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' post: operationId: addGroupParticipants tags: [Participant Groups] summary: Add participants to group requestBody: required: true content: application/json: schema: type: object properties: participant_ids: type: array items: type: string responses: '200': description: Participants added. content: application/json: schema: $ref: '#/components/schemas/ParticipantGroup' '401': $ref: '#/components/responses/Unauthorized' delete: operationId: removeGroupParticipants tags: [Participant Groups] summary: Remove participants from group requestBody: required: true content: application/json: schema: type: object properties: participant_ids: type: array items: type: string responses: '200': description: Participants removed. content: application/json: schema: $ref: '#/components/schemas/ParticipantGroup' '401': $ref: '#/components/responses/Unauthorized' /workspaces/: get: operationId: listWorkspaces tags: [Workspaces] summary: Get user's workspaces responses: '200': description: A list of workspaces. content: application/json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' post: operationId: createWorkspace tags: [Workspaces] summary: Create a workspace requestBody: required: true content: application/json: schema: type: object properties: title: type: string description: type: string responses: '201': description: The created workspace. content: application/json: schema: $ref: '#/components/schemas/Workspace' '401': $ref: '#/components/responses/Unauthorized' /workspaces/{workspace_id}/: parameters: - $ref: '#/components/parameters/WorkspaceId' get: operationId: getWorkspace tags: [Workspaces] summary: Get workspace responses: '200': description: A workspace. content: application/json: schema: $ref: '#/components/schemas/Workspace' '401': $ref: '#/components/responses/Unauthorized' patch: operationId: updateWorkspace tags: [Workspaces] summary: Update a workspace requestBody: required: true content: application/json: schema: type: object responses: '200': description: The updated workspace. content: application/json: schema: $ref: '#/components/schemas/Workspace' '401': $ref: '#/components/responses/Unauthorized' /workspaces/{workspace_id}/balance/: parameters: - $ref: '#/components/parameters/WorkspaceId' get: operationId: getWorkspaceBalance tags: [Workspaces] summary: Get workspace balance responses: '200': description: The workspace wallet balance. content: application/json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' /workspaces/{workspace_id}/projects/: parameters: - $ref: '#/components/parameters/WorkspaceId' get: operationId: listProjects tags: [Projects] summary: Get all projects in a workspace responses: '200': description: A list of projects. content: application/json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' post: operationId: createProject tags: [Projects] summary: Create a project requestBody: required: true content: application/json: schema: type: object properties: title: type: string responses: '201': description: The created project. content: application/json: schema: $ref: '#/components/schemas/Project' '401': $ref: '#/components/responses/Unauthorized' /projects/{id}/: parameters: - $ref: '#/components/parameters/ProjectId' get: operationId: getProject tags: [Projects] summary: Get project responses: '200': description: A project. content: application/json: schema: $ref: '#/components/schemas/Project' '401': $ref: '#/components/responses/Unauthorized' patch: operationId: updateProject tags: [Projects] summary: Update a project requestBody: required: true content: application/json: schema: type: object responses: '200': description: The updated project. content: application/json: schema: $ref: '#/components/schemas/Project' '401': $ref: '#/components/responses/Unauthorized' /messages/: get: operationId: getMessages tags: [Messages] summary: Retrieve messages description: Get messages between you and another user, or your messages with all users. parameters: - name: user_id in: query required: false schema: type: string - name: created_after in: query required: false schema: type: string format: date-time responses: '200': description: A list of messages. content: application/json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' post: operationId: sendMessage tags: [Messages] summary: Send a message requestBody: required: true content: application/json: schema: type: object properties: recipient_id: type: string body: type: string study_id: type: string responses: '201': description: The message was sent. content: application/json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' /messages/unread/: get: operationId: getUnreadMessages tags: [Messages] summary: Retrieve unread messages responses: '200': description: A list of unread messages. content: application/json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' /hooks/event-types/: get: operationId: listEventTypes tags: [Hooks] summary: List subscribable event types responses: '200': description: A list of event types. content: application/json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' /hooks/secrets/: get: operationId: listSecrets tags: [Hooks] summary: List all secrets responses: '200': description: A list of signing secrets. content: application/json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' post: operationId: createSecret tags: [Hooks] summary: Create or replace a secret requestBody: required: true content: application/json: schema: type: object properties: workspace_id: type: string responses: '201': description: The created secret. content: application/json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' /hooks/subscriptions/: get: operationId: listSubscriptions tags: [Hooks] summary: List all subscriptions responses: '200': description: A list of subscriptions. content: application/json: schema: $ref: '#/components/schemas/SubscriptionList' '401': $ref: '#/components/responses/Unauthorized' post: operationId: createSubscription tags: [Hooks] summary: Create a subscription requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionInput' responses: '201': description: The created subscription. content: application/json: schema: $ref: '#/components/schemas/Subscription' '401': $ref: '#/components/responses/Unauthorized' /hooks/subscriptions/{id}/: parameters: - $ref: '#/components/parameters/SubscriptionId' get: operationId: getSubscription tags: [Hooks] summary: Retrieve a subscription responses: '200': description: A subscription. content: application/json: schema: $ref: '#/components/schemas/Subscription' '401': $ref: '#/components/responses/Unauthorized' patch: operationId: updateSubscription tags: [Hooks] summary: Update a subscription requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionInput' responses: '200': description: The updated subscription. content: application/json: schema: $ref: '#/components/schemas/Subscription' '401': $ref: '#/components/responses/Unauthorized' delete: operationId: deleteSubscription tags: [Hooks] summary: Delete a subscription responses: '204': description: The subscription was deleted. '401': $ref: '#/components/responses/Unauthorized' /hooks/subscriptions/{id}/confirm/: parameters: - $ref: '#/components/parameters/SubscriptionId' post: operationId: confirmSubscription tags: [Hooks] summary: Confirm a subscription responses: '200': description: The subscription was confirmed. content: application/json: schema: $ref: '#/components/schemas/Subscription' '401': $ref: '#/components/responses/Unauthorized' /hooks/subscriptions/{id}/events/: parameters: - $ref: '#/components/parameters/SubscriptionId' get: operationId: getSubscriptionEvents tags: [Hooks] summary: Get subscription events responses: '200': description: Delivered events for the subscription. content: application/json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' /filters/: get: operationId: listFilters tags: [Filters] summary: List all filters description: List all filters (requirements) that can be applied to your filter sets or studies. responses: '200': description: A list of filters. content: application/json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' /filters/{filter_id}/distribution/: parameters: - name: filter_id in: path required: true schema: type: string get: operationId: getFilterDistribution tags: [Filters] summary: Get filter distribution responses: '200': description: The distribution of participants across the filter's values. content: application/json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' /participant-counts/: post: operationId: countParticipants tags: [Filters] summary: Count participants description: Count how many eligible participants match a set of filters. requestBody: required: true content: application/json: schema: type: object properties: filters: type: array items: type: object responses: '200': description: The count of eligible participants. content: application/json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' /submissions/bonus-payments/: post: operationId: setupBonusPayments tags: [Bonuses] summary: Set up bonuses description: >- Create a bulk bonus payment for a study from a CSV of participant/submission IDs and amounts. This does not pay the bonuses; call the pay endpoint after. requestBody: required: true content: application/json: schema: type: object properties: study_id: type: string csv_bonuses: type: string description: 'CSV rows of , or ,.' responses: '201': description: The created bulk bonus payment. content: application/json: schema: type: object properties: id: type: string total_amount: type: number '401': $ref: '#/components/responses/Unauthorized' /bulk-bonus-payments/{id}/pay/: parameters: - name: id in: path required: true schema: type: string post: operationId: payBonusPayments tags: [Bonuses] summary: Pay bonuses description: >- Pay a previously created bulk bonus payment. Payment is made asynchronously against your workspace balance. Up to 200 participants per request. responses: '200': description: The bonus payment was queued for payment. content: application/json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' /users/me/: get: operationId: getMe tags: [Users] summary: Retrieve the authenticated user description: Returns the basic account information for the authenticated user, including ID and email. responses: '200': description: The authenticated user. content: application/json: schema: $ref: '#/components/schemas/User' '401': $ref: '#/components/responses/Unauthorized' /users/{id}/: parameters: - name: id in: path required: true schema: type: string get: operationId: getUser tags: [Users] summary: Retrieve a user responses: '200': description: A user. content: application/json: schema: $ref: '#/components/schemas/User' '401': $ref: '#/components/responses/Unauthorized' components: securitySchemes: tokenAuth: type: apiKey in: header name: Authorization description: 'API token supplied as "Token ".' parameters: StudyId: name: id in: path required: true schema: type: string description: The study ID. SubmissionId: name: id in: path required: true schema: type: string description: The submission ID. GroupId: name: id in: path required: true schema: type: string description: The participant group ID. WorkspaceId: name: workspace_id in: path required: true schema: type: string description: The workspace ID. ProjectId: name: id in: path required: true schema: type: string description: The project ID. SubscriptionId: name: id in: path required: true schema: type: string description: The hook subscription ID. responses: Unauthorized: description: Authentication credentials were missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' schemas: Error: type: object properties: error: type: object properties: detail: type: string error_code: type: integer Study: type: object properties: id: type: string name: type: string internal_name: type: string description: type: string status: type: string external_study_url: type: string total_available_places: type: integer reward: type: integer description: Reward per participant in the study currency's minor units. estimated_completion_time: type: integer project: type: string filters: type: array items: type: object StudyInput: type: object properties: name: type: string description: type: string external_study_url: type: string total_available_places: type: integer reward: type: integer estimated_completion_time: type: integer project: type: string filters: type: array items: type: object StudyList: type: object properties: results: type: array items: $ref: '#/components/schemas/Study' _links: type: object Submission: type: object properties: id: type: string participant_id: type: string study_id: type: string status: type: string started_at: type: string format: date-time completed_at: type: string format: date-time SubmissionList: type: object properties: results: type: array items: $ref: '#/components/schemas/Submission' _links: type: object ParticipantGroup: type: object properties: id: type: string name: type: string project_id: type: string workspace_id: type: string participant_count: type: integer ParticipantGroupInput: type: object properties: name: type: string project_id: type: string participant_ids: type: array items: type: string ParticipantGroupList: type: object properties: results: type: array items: $ref: '#/components/schemas/ParticipantGroup' Project: type: object properties: id: type: string title: type: string description: type: string workspace: type: string Workspace: type: object properties: id: type: string title: type: string description: type: string owner: type: string naivety_distribution_rate: type: number Subscription: type: object properties: id: type: string event_type: type: string target_url: type: string is_enabled: type: boolean workspace_id: type: string SubscriptionInput: type: object properties: event_type: type: string target_url: type: string workspace_id: type: string SubscriptionList: type: object properties: results: type: array items: $ref: '#/components/schemas/Subscription' User: type: object properties: id: type: string email: type: string name: type: string