{"openapi":"3.1.0","info":{"title":"API Reference","version":"1.0.0"},"paths":{"/api/v1/users/me/":{"get":{"operationId":"get-user","summary":"Retrieve a user","description":"Use this endpoint to test your token and retrieve the basic information of your account.\n\nAdd an `Authorization` header with the value `Token `.","tags":["users"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/researchers/participants/":{"post":{"operationId":"create-test-participant-for-researcher","summary":"Create a test participant for a researcher","description":"### Overview\nCreates a test participant with the same details as the researcher and the supplied email. This participant will\nbypass any fraud checks and on-boarding steps.\n\n### Enabling the feature\nThis endpoint is only enabled for select workspaces and will need enabling before the endpoint can be used.\n\n### Participant Limitations\n- The participant will be limited to take studies only in the workspaces associated to the researcher and where\nthe feature is enabled.\n- The participant will not be able to cashout any balance earned from completing studies.\n\n### Usage\n- The API response contains the participant ID. This can be used in a custom allowlist or participant group to\ntarget the participant on studies. This enables the researcher to test the study set up end-to-end.\n- A randomly generated password is assigned to the participant account. We recommend that you request to reset\nthe password, and use this new password to login to the participant account.\n","tags":["users"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTestParticipantForResearcherResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTestParticipantForResearcher"}}}}}},"/api/v1/data-collection/batches":{"get":{"operationId":"get-task-builder-batches","summary":"List Batches","description":"Get all AI Task Builder batches by workspace id","tags":["aiTaskBuilder"],"parameters":[{"name":"workspace_id","in":"query","description":"The unique identifier of the workspace","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AI Task Builder_GetTaskBuilderBatches_Response_200"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create-task-builder-batch","summary":"Create a Batch","description":"Create a new AI Task Builder batch. The dataset does not need to be in READY status at creation time.\n\n### Configurable task layouts via `batch_items`\n\nYou can configure a custom task layout using `batch_items` which also stores instructions and content as part of batch creation. It replaces the deprecated `POST /api/v1/data-collection/batches/{batch_id}/instructions` endpoint, which will reject requests on batches that were created with `batch_items`.\n\n`batch_items` is a nested layout describing what is shown to participants:\n\n- `batch_items` is an ordered array of **pages**. Each page is shown to participants as a single screen.\n- Each page has an ordered array of **rows**.\n- Each row has 1 or 2 **columns** rendered side-by-side.\n- Each column has one or more **items** — a dataset field reference, a content block (`image`, `rich_text`), or an instruction (`free_text`, `free_text_with_unit`, `multiple_choice`, `multiple_choice_with_free_text`, `file_upload`).\n\nItems are a discriminated union on `type`. Each `dataset_field` item references a field in the attached dataset by name — only fields with type `text`, `image_url`, `audio_url`, or `video_url` are permitted, and the same field may not be referenced more than once on the same page.\n\nOn a successful response, every item in `batch_items` is returned with a server-assigned `id`.\n\nIf `batch_items` fails server-side validation (for example: a `dataset_field` item used when no v4 dataset with a populated schema is attached, an unknown `dataset_field`, the same `dataset_field` referenced more than once on a page, an `answer_limit` larger than the number of options, or a `default_unit` that does not match the supplied `unit_options`), the request fails with **`422 Unprocessable Entity`** and an `INVALID_BATCH_ITEMS` payload containing per-item `page` / `row` / `column` / `item` locations. See the `BatchItemsValidationError` schema for the full shape.","tags":["aiTaskBuilder"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AITaskBuilderBatchCreate"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable Entity — `batch_items` failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchItemsValidationError"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The name of the batch"},"workspace_id":{"type":"string","description":"The ID of the Prolific workspace"},"dataset_id":{"type":"string","format":"uuid","description":"The ID of the dataset to attach (optional at creation time)"},"task_details":{"$ref":"#/components/schemas/ApiV1DataCollectionBatchesPostRequestBodyContentApplicationJsonSchemaTaskDetails","description":"Task metadata displayed to participants"},"batch_items":{"type":["array","null"],"items":{"$ref":"#/components/schemas/BatchItemsPage"},"description":"Inline pages of instructions and content shown to participants. Each entry is a page\ncontaining rows of columns of items (dataset field references, content blocks, or\ninstructions). When supplied, this is the recommended way to author instructions —\nthe legacy `POST /batches/{batch_id}/instructions` endpoint is rejected for batches\ncreated with `batch_items`."}},"required":["name","workspace_id","task_details"]}}}}}},"/api/v1/data-collection/batches/{batch_id}":{"get":{"operationId":"get-task-builder-batch","summary":"Get a Batch","description":"Get a specific AI Task Builder batch by its unique identifier.","tags":["aiTaskBuilder"],"parameters":[{"name":"batch_id","in":"path","description":"The unique identifier of the AI Task Builder batch","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AITaskBuilderBatch"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"update-task-builder-batch","summary":"Update a Batch","description":"Update an existing AI Task Builder batch. You can update the name, task details, associated dataset, and/or `batch_items`. The dataset does not need to be in READY status for updates.\n\nWhen updating `batch_items`, include the `id` of any existing pages, rows, columns, or items you want to preserve — items without an `id` are treated as new and assigned one server-side. Omitting an existing `id` removes that entry. The same validation rules as on create apply, and validation failures return **`422 Unprocessable Entity`** with the `BatchItemsValidationError` payload.","tags":["aiTaskBuilder"],"parameters":[{"name":"batch_id","in":"path","description":"The unique identifier of the batch","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AITaskBuilderBatch"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable Entity — `batch_items` failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchItemsValidationError"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"task_details":{"$ref":"#/components/schemas/ApiV1DataCollectionBatchesBatchIdPatchRequestBodyContentApplicationJsonSchemaTaskDetails"},"dataset_id":{"type":"string","format":"uuid"},"batch_items":{"type":["array","null"],"items":{"$ref":"#/components/schemas/BatchItemsPage"},"description":"Replacement layout for the batch's instructions and content. Include the `id`\nof any existing pages, rows, columns, or items you want to preserve; omit `id`\nto add new entries. Items absent from the payload are removed."},"auto_sync_enabled":{"type":"boolean","description":"When `true`, datapoints subsequently appended to the batch's attached dataset\n(via `POST /datasets/{dataset_id}/datapoints`) automatically trigger a sync that\nmaterialises tasks for them — no explicit `POST /batches/{batch_id}/sync` call is\nneeded. When `false`, appended datapoints are only picked up by an explicit\nsync. If this field is omitted from the PATCH payload, the existing auto-sync\nsetting is left unchanged."}}}}}}}},"/api/v1/data-collection/batches/{batch_id}/sync":{"post":{"operationId":"sync-task-builder-batch","summary":"Sync a Batch","description":"Triggers an asynchronous sync job that materialises tasks for any datapoints appended to the\nbatch's attached dataset since it was set up (or since the last sync). Returns immediately\nwith a `sync_id`; the work is performed by a background worker.\n\nThe batch must be in `READY` status and have an attached dataset. Syncs for the same batch are\nserialised, so a new sync picks up wherever the previous one left off.\n\nPoll `GET /batches/{batch_id}/syncs/{sync_id}` until the returned job reaches a terminal\nstatus (`complete` or `failed`).","tags":["aiTaskBuilder"],"parameters":[{"name":"batch_id","in":"path","description":"The unique identifier of the batch to sync","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"Sync job accepted and queued. The returned job has status `queued`; poll the sync-status\nendpoint for progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncJob"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/data-collection/batches/{batch_id}/syncs/{sync_id}":{"get":{"operationId":"get-batch-sync-status","summary":"Get Batch Sync Status","description":"Returns the current status of a batch sync job created by `POST /batches/{batch_id}/sync`.\n\nA sync job transitions through the following statuses:\n- `queued` — sync accepted, awaiting the background worker.\n- `processing` — the worker is materialising tasks.\n\n**Terminal statuses:**\n- `complete` — the sync finished. `tasks_created`, `datapoints_processed`, `groups_created`, and `groups_expanded` are populated.\n- `failed` — the sync failed. `reason` is populated.\n\nContinue polling while the status is `queued` or `processing`.","tags":["aiTaskBuilder"],"parameters":[{"name":"batch_id","in":"path","description":"The unique identifier of the batch","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"sync_id","in":"path","description":"The sync job ID returned by `POST /batches/{batch_id}/sync`","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sync job status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncJob"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Sync job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/data-collection/batches/{batch_id}/status":{"get":{"operationId":"get-task-builder-batch-status","summary":"Get Batch Status","description":"Get the current status of an AI Task Builder batch.","tags":["aiTaskBuilder"],"parameters":[{"name":"batch_id","in":"path","description":"The unique identifier of the AI Task Builder batch","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AI Task Builder_GetTaskBuilderBatchStatus_Response_200"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/data-collection/batches/{batch_id}/setup":{"post":{"operationId":"setup-task-builder-batch","summary":"Setup a Batch","description":"The setup process creates all of the **tasks** within the batch according to your configuration.\nEach datapoint in the dataset is paired with all instructions to create a task. Tasks are then organized into task groups.\n\n**V3 datasets:** The dataset must be in a **READY** status before setup can be initiated.\n\n**V4 datasets:** The dataset must have at least one import job with status **complete**. V4 datasets do not have a `READY` status — readiness is determined per import job via `GET /datasets/{dataset_id}/imports/{import_id}`.\n\nThe dataset can be attached either at batch creation time or via the `dataset_id` parameter in this request.\n\nUpon successful invocation, the setup process will begin asynchronously, and the batch will be set to a **PROCESSING** status.\n\nTo retrieve the status of the setup, call the `GET /api/v1/data-collection/batches/{batch_id}/status` endpoint.\nThe setup is complete once the batch status changes to **READY**.","tags":["aiTaskBuilder"],"parameters":[{"name":"batch_id","in":"path","description":"The unique identifier of the AI Task Builder batch","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AI Task Builder_SetupTaskBuilderBatch_Response_202"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dataset_id":{"type":"string","format":"uuid","description":"The ID of the dataset to use for task generation. Optional if a dataset was already attached at batch creation time."},"tasks_per_group":{"type":"integer","minimum":1,"default":1,"description":"The number of tasks to randomly assign to each task group. Participants complete one task group per submission.\nIf your dataset includes a META_TASK_GROUP_ID column, those groupings take precedence over this parameter."}}}}}}}},"/api/v1/data-collection/batches/{batch_id}/responses":{"get":{"operationId":"get-task-builder-batch-task-responses","summary":"Get Batch Responses","description":"Get responses for an AI Task Builder batch as JSON. Returns individual response records for programmatic processing.","tags":["aiTaskBuilder"],"parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AI Task Builder_GetTaskBuilderBatchTaskResponses_Response_200"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/data-collection/batches/{batch_id}/report/":{"get":{"operationId":"get-task-builder-batch-report","summary":"Get Batch Report","description":"Get a presigned URL to download the batch responses as a CSV report. The CSV contains your original dataset with additional columns for participant responses.","tags":["aiTaskBuilder"],"parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AI Task Builder_GetTaskBuilderBatchReport_Response_200"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/data-collection/batches/{batch_id}/duplicate":{"post":{"operationId":"duplicate-task-builder-batch","summary":"Duplicate a Batch","description":"Create a duplicate of an existing AI Task Builder batch. The dataset does not need to be in READY status for duplication. Supports two modes:\n- Duplicate with dataset (default): Creates a copy with the same dataset (the dataset is shared between both batches, not duplicated)\n- Duplicate without dataset: Creates a copy that requires a new dataset upload (set upload_new_dataset to true)\n\nYou can optionally provide a new name for the duplicated batch. If no name is provided, the duplicate will be named \"[Original Batch Name] (Copy)\".","tags":["aiTaskBuilder"],"parameters":[{"name":"batch_id","in":"path","description":"The unique identifier of the batch to duplicate","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AITaskBuilderBatchCreate"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Optional name for the duplicated batch. If not provided, a default name will be generated."},"upload_new_dataset":{"type":"boolean","default":false,"description":"If true, creates the batch without copying the dataset (user must upload a new one). If false or omitted, duplicates with the existing dataset."}}}}}}}},"/api/v1/data-collection/batches/{batch_id}/export":{"post":{"operationId":"request-batch-export","summary":"Request a Batch Export","description":"Initiates an asynchronous export of all participant responses and uploaded files for a batch as a ZIP archive.\n\nThe export is generated out-of-band to handle large batches without hitting API timeout limits. The endpoint returns immediately with one of two outcomes:\n\n- **202 Accepted** — a new export job has been enqueued. Use the returned `export_id` to poll `GET /batches/{batch_id}/export/{export_id}` for status.\n- **200 OK** — a recent export already exists and is ready to download immediately.\n\nSubsequent POST requests for the same batch are idempotent while an export is generating or complete; they return the existing job ID or download URL rather than re-triggering generation.\n\nOnly researchers with workspace access to the batch can request an export.","tags":["aiTaskBuilder"],"parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Export already complete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchExportComplete"}}}},"403":{"description":"Forbidden — user does not have workspace access to this batch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/data-collection/batches/{batch_id}/export/{export_id}":{"get":{"operationId":"get-batch-export-status","summary":"Get Batch Export Status","description":"Polls the status of an asynchronous batch export job initiated by `POST /batches/{batch_id}/export`.\n\nReturns the current status of the export:\n\n- **generating** — the export is still being built; continue polling.\n- **complete** — the export is ready; a presigned HTTPS download URL is included. URLs are valid for 1 hour and are automatically refreshed if expired.\n- **failed** — generation failed (e.g. the archive was deleted from storage). Re-send `POST /batches/{batch_id}/export` to retry.","tags":["aiTaskBuilder"],"parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"export_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Export status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchExportStatus"}}}},"404":{"description":"Export job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/data-collection/datasets":{"post":{"operationId":"create-task-builder-dataset","summary":"Create a Dataset","description":"Create a new AI Task Builder dataset.\n\nPass an optional `schema` to create a **V4 dataset** with a structured schema. V4 datasets accept JSONL and CSV uploads, track each upload as an import job, and allow `dataset_field` items in `batch_items` to reference named schema fields. Without a `schema`, a V3 dataset is created (CSV/ZIP only, legacy flow).\n\nV4 dataset creation requires the feature to be enabled for the workspace.","tags":["aiTaskBuilder"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AITaskBuilderDataset"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The name or identifier of the AI Task Builder dataset."},"workspace_id":{"type":"string","description":"The ID of the Prolific workspace the dataset will be created in."},"schema":{"$ref":"#/components/schemas/DatasetSchema","description":"Optional schema definition. When provided, a V4 dataset is created. Omit for a V3 dataset."}},"required":["name","workspace_id"]}}}}}},"/api/v1/data-collection/datasets/{dataset_id}":{"get":{"operationId":"get-task-builder-dataset","summary":"Get a Dataset","description":"Get a specific AI Task Builder dataset by its unique identifier.\n\nFor **V4 datasets**, the response includes the dataset `schema` (if one has been set) and an `imports` array listing all import jobs for this dataset.\n\nFor **V3 datasets**, the response includes `status`, `filename`, and `has_predetermined_grouping_id` instead.","tags":["aiTaskBuilder"],"parameters":[{"name":"dataset_id","in":"path","description":"The unique identifier of the AI Task Builder dataset","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AITaskBuilderDataset"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Dataset not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"update-task-builder-dataset","summary":"Update a Dataset Schema","description":"Updates the schema of an existing **V4 dataset**. Each successful update writes a new schema\nversion.\n\n**Schema migration.** If the dataset already had a schema, changing it starts an asynchronous\n**schema migration** that re-normalises the dataset's existing datapoints against the new\nversion. In that case the response includes a `migration_job_id`; poll\n`GET /datasets/{dataset_id}/schema-migrations/{job_id}` with it until the job reaches a\nterminal status. When this is the dataset's **first** schema, no migration is needed and\n`migration_job_id` is omitted.\n\n**Constraints:**\n- V4 datasets only — a `400` is returned for V3 datasets.\n- The `task_group_id` column designation cannot be changed once the dataset has datapoints; attempting to do so returns `400`.","tags":["aiTaskBuilder"],"parameters":[{"name":"dataset_id","in":"path","description":"The unique identifier of the V4 dataset to update","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Dataset updated. Returns the updated dataset. When the update triggered a schema\nmigration, `migration_job_id` is present — poll the schema-migration endpoint with it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AI Task Builder_UpdateTaskBuilderDataset_Response_200"}}}},"400":{"description":"Bad request — not a V4 dataset, or an attempt to change the `task_group_id` column on a\ndataset that already has datapoints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the user does not have access to the dataset's workspace.","content":{"application/json":{"schema":{"description":"Any type"}}}},"404":{"description":"Dataset not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"schema":{"$ref":"#/components/schemas/DatasetSchema","description":"The new schema definition for the dataset."}},"required":["schema"]}}}}}},"/api/v1/data-collection/datasets/{dataset_id}/upload-url/{filename}":{"get":{"operationId":"get-dataset-upload-url","summary":"Get Dataset Upload URL","description":"Generates a presigned S3 URL for uploading a file to the dataset. Use the returned URL to PUT the file directly to S3.\n\n**V3 datasets** (CSV/ZIP): returns `upload_url` and `http_method`. After the upload completes, poll `GET /datasets/{dataset_id}/status` for processing status.\n\n**V4 datasets** (JSONL/CSV): additionally returns `import_id`. After the upload completes, poll `GET /datasets/{dataset_id}/imports/{import_id}` for per-upload status. Multiple upload URLs can be requested before any upload completes — each creates a distinct import job and S3 key.\n\nSupported file types:\n- V3: `.csv`, `.zip`\n- V4: `.csv`, `.jsonl`","tags":["aiTaskBuilder"],"parameters":[{"name":"dataset_id","in":"path","description":"The ID of the dataset to upload files to","required":true,"schema":{"type":"string"}},{"name":"filename","in":"path","description":"The name of the file to upload (e.g. `data.jsonl`)","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Presigned URL generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AI Task Builder_getDatasetUploadUrl_Response_201"}}}},"400":{"description":"Bad request (e.g., unsupported file type for this dataset version)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (e.g., user does not have access to the workspace)","content":{"application/json":{"schema":{"description":"Any type"}}}},"404":{"description":"Dataset not found","content":{"application/json":{"schema":{"description":"Any type"}}}}}}},"/api/v1/data-collection/datasets/{dataset_id}/imports/{import_id}":{"get":{"operationId":"get-dataset-import-status","summary":"Get Dataset Import Status","description":"Returns the current status of a V4 dataset import job. Each import job represents one ingestion operation and transitions through the following statuses:\n- `uninitialised` — Presigned url requested, but not yet used\n- `processing` — Datapoints received for ingestion, work underway\n- `queued` — Datapoints received for ingestion, awaiting a previous import job to complete before processing can commence\n\n**Terminal statuses:**\n- `complete` — all records were accepted. `accepted_count` is populated.\n- `partial` — some records were accepted and some rejected. `accepted_count`, `rejected_count`, and `errors` are populated. The accepted records are available for use.\n- `failed` — extraction failed entirely (e.g. file could not be parsed). `reason` is populated. No records were ingested.\n- `pending_schema` — the dataset has no schema set; upload is paused until a schema is defined.\n\nContinue polling while the status is `uninitialised`, `queued`, or `processing`.","tags":["aiTaskBuilder"],"parameters":[{"name":"dataset_id","in":"path","description":"The unique identifier of the dataset","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"import_id","in":"path","description":"The import job ID returned by `GET /datasets/{dataset_id}/upload-url/{filename}`","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Import job status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetImportJob"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Import job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/data-collection/datasets/{dataset_id}/datapoints":{"post":{"operationId":"append-dataset-datapoints","summary":"Append Datapoints to a Dataset","description":"Synchronously appends one or more JSONL records to an existing **V4 dataset**. Unlike the\nfile-upload flow, this endpoint processes the whole payload within the request and returns the\naccepted/rejected counts directly — there is no async import job to poll.\n\n**Request body:** JSONL — one JSON object per line — sent with a JSONL content type\n(e.g. `application/x-ndjson`). Blank lines are skipped. CSV is not supported on this endpoint.\n\nEach record is validated against the dataset's current schema. Valid records are persisted as\ndatapoints and sort after every existing datapoint. Records that are malformed or violate the\nschema are rejected individually and reported in `errors` — they do not fail the whole request.\nRe-appending an identical record is idempotent (counted as accepted, not written twice).\n\n**Limits and preconditions:**\n- At most 1000 records per request. Larger imports should use the file-upload flow.\n- The dataset must be V4 and have a schema defined.\n- Rejected with `409 Conflict` while a dataset import or a schema migration is in progress.\n\nIf the dataset is attached to any batches with `auto_sync_enabled`, a sync is triggered\nautomatically for the newly written datapoints.","tags":["aiTaskBuilder"],"parameters":[{"name":"dataset_id","in":"path","description":"The unique identifier of the V4 dataset to append to","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Append processed. Returns per-request accepted/rejected counts. A `200` is returned even\nwhen some (or all) records were rejected — inspect `rejected` and `errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetAppendResult"}}}},"400":{"description":"Bad request — missing body, CSV payload, empty JSONL, too many records, a non-V4 dataset,\nor a dataset with no schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the user does not have access to the dataset's workspace.","content":{"application/json":{"schema":{"description":"Any type"}}}},"404":{"description":"Dataset not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — a dataset import or a schema migration is in progress. Retry once it completes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"string"}}}}}},"/api/v1/data-collection/datasets/{dataset_id}/schema-migrations/{job_id}":{"get":{"operationId":"get-schema-migration-status","summary":"Get Schema Migration Status","description":"Returns the current status of a schema migration job, which reprocesses a V4 dataset's\ndatapoints against a newer schema version.\n\nA migration job has these statuses:\n- `processing` — the migration is underway.\n\n**Terminal statuses:**\n- `complete` — all datapoints were reprocessed. `reprocessed_count` is populated.\n- `partial` — some datapoints were reprocessed and some fields could not be re-normalised (and\n were nulled). `reprocessed_count`, `failed_count`, and `errors` are populated.\n- `failed` — the migration failed entirely. `reason` is populated.\n\nContinue polling while the status is `processing`.","tags":["aiTaskBuilder"],"parameters":[{"name":"dataset_id","in":"path","description":"The unique identifier of the dataset","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"job_id","in":"path","description":"The schema migration job ID","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Schema migration job status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchemaMigrationJob"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Schema migration job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/data-collection/datasets/{dataset_id}/status":{"get":{"operationId":"get-task-builder-dataset-status","summary":"Get Dataset Status","description":"Get status for AI Task Builder dataset.","tags":["aiTaskBuilder"],"parameters":[{"name":"dataset_id","in":"path","description":"The unique identifier of the AI Task Builder dataset","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AI Task Builder_GetTaskBuilderDatasetStatus_Response_200"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/data-collection/batches/{batch_id}/instructions":{"get":{"operationId":"get-task-builder-instructions","summary":"Get Batch Instructions","description":"Get the instructions for an AI Task Builder batch.\n\n\n\n**Deprecated.**\n\nAll responses include the [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) headers `Deprecation: true` and `Sunset: Tue, 01 Sep 2026 23:59:59 GMT`. Migrate to the `batch_items` flow before the sunset date.\n\n","tags":["aiTaskBuilder"],"parameters":[{"name":"batch_id","in":"path","description":"Batch ID","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AI Task Builder_GetTaskBuilderInstructions_Response_200"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create-task-builder-instructions","summary":"Create Batch Instructions","description":"Create instructions for a Task Builder batch.\n\n\n\n**Deprecated for batches that use `batch_items`.**\n\nAll responses include the [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) headers `Deprecation: true` and `Sunset: Tue, 01 Sep 2026 23:59:59 GMT`.\n\nIf the target batch was created with `batch_items` (the per-item instructions flow), this endpoint will respond with **`422 Unprocessable Entity`** and an error message directing you to manage instructions via the `batch_items` payload instead.\n\nLegacy batches (where `batch_items` is `null`) continue to work and return `201 Created`.\n\n","tags":["aiTaskBuilder"],"parameters":[{"name":"batch_id","in":"path","description":"The unique identifier of the AI Task Builder batch","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Created. Returned only for legacy batches (`batch_items` is `null`).","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AITaskBuilderInstruction"}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Returned when the target batch uses `batch_items`. Instructions must be managed via the `batch_items` payload instead of this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"instructions":{"type":"array","items":{"$ref":"#/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItems"},"description":"The instructions to create for the AI Task Builder batch."}},"required":["instructions"]}}}}},"put":{"operationId":"update-task-builder-instructions","summary":"Update Batch Instructions","description":"Updates the instructions for a task builder batch. This is a full replacement - all instructions must be included in the request.\n\nInclude the `id` field for existing instructions you want to preserve. Instructions without an `id` will be created as new.\n\n\n\n**Deprecated for batches that use `batch_items`.**\n\nIf the target batch was created with `batch_items` (the per-item instructions flow), this endpoint will respond with **`422 Unprocessable Entity`** and an error message directing you to manage instructions via the `batch_items` payload instead.\n\nThe response will also include the [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) headers `Deprecation: true` and `Sunset: Tue, 01 Sep 2026 23:59:59 GMT`. Legacy batches (where `batch_items` is `null`) are unaffected and continue to work as before.\n\n","tags":["aiTaskBuilder"],"parameters":[{"name":"batch_id","in":"path","description":"Batch ID","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated. Returned only for legacy batches (`batch_items` is `null`).","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AITaskBuilderInstruction"}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Returned when the target batch uses `batch_items`. Instructions must be managed via the `batch_items` payload instead of this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"instructions":{"type":"array","items":{"$ref":"#/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItems"},"description":"The instructions for the batch."}},"required":["instructions"]}}}}}},"/api/v1/data-collection/collections":{"get":{"operationId":"list-collections","summary":"List Collections","description":"Get all AI Task Builder Collections for a workspace.","tags":["aiTaskBuilder"],"parameters":[{"name":"workspace_id","in":"query","description":"The unique identifier of the workspace","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AI Task Builder_ListCollections_Response_200"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create-collection","summary":"Create a Collection","description":"Create a new AI Task Builder Collection. Collections allow you to define static content and instructions without requiring a dataset upload.\n\nUnlike Batches, Collections do not require a dataset or setup step — they can be published to a study immediately after creation.","tags":["aiTaskBuilder"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionCreateRequest"}}}}}},"/api/v1/data-collection/collections/{collection_id}":{"get":{"operationId":"get-collection","summary":"Get a Collection","description":"Get a specific AI Task Builder Collection by its unique identifier.","tags":["aiTaskBuilder"],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"update-collection","summary":"Update a Collection","description":"Update an existing AI Task Builder Collection. This is a full replacement — all fields must be provided.\n\nTo preserve existing entities (collection items, page items) when updating, include their `id` fields in the request. Entities without IDs will be created as new, and existing entities not included in the request will be deleted.","tags":["aiTaskBuilder"],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionUpdateRequest"}}}}}},"/api/v1/data-collection/collections/{collection_id}/responses":{"get":{"operationId":"get-collection-responses","summary":"Get Collection Responses","description":"Get responses for an AI Task Builder Collection.\n\n**Note:** This endpoint is coming soon and is not yet available.","tags":["aiTaskBuilder"],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AI Task Builder_GetCollectionResponses_Response_200"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/data-collection/collections/{collection_id}/export":{"post":{"operationId":"request-collection-export","summary":"Request a Collection Export","description":"Initiates an asynchronous export of all participant responses and uploaded files for a collection as a ZIP archive.\n\nThe export is generated out-of-band to handle large collections without hitting API timeout limits. The endpoint returns immediately with one of two outcomes:\n\n- **202 Accepted** — a new export job has been enqueued. Use the returned `export_id` to poll `GET /collections/{collection_id}/export/{export_id}` for status.\n- **200 OK** — a recent export already exists and is ready to download immediately.\n\nSubsequent POST requests for the same collection are idempotent while an export is generating or complete; they return the existing job ID or download URL rather than re-triggering generation.\n\nOnly researchers with workspace access to the collection can request an export.","tags":["aiTaskBuilder"],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Export already complete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionExportComplete"}}}},"403":{"description":"Forbidden — user does not have workspace access to this collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/data-collection/collections/{collection_id}/export/{export_id}":{"get":{"operationId":"get-collection-export-status","summary":"Get Collection Export Status","description":"Polls the status of an asynchronous collection export job initiated by `POST /collections/{collection_id}/export`.\n\nReturns the current status of the export:\n\n- **generating** — the export is still being built; continue polling.\n- **complete** — the export is ready; a presigned HTTPS download URL is included. URLs are valid for 1 hour and are automatically refreshed if expired.\n- **failed** — generation failed (e.g. the archive was deleted from storage). Re-send `POST /collections/{collection_id}/export` to retry.","tags":["aiTaskBuilder"],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"export_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Export status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionExportStatus"}}}},"404":{"description":"Export job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/studies/":{"get":{"operationId":"get-studies","summary":"List all studies","description":"List all studies, with the option to filter by study status.","tags":["studies"],"parameters":[{"name":"state","in":"query","description":"Filter studies by status. Accepts a string in the format \"(active|published|...)\", where \"active\" and \"published\" are example statuses.","required":false,"schema":{"$ref":"#/components/schemas/ApiV1StudiesGetParametersState"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of studies","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudiesListResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}}}},"post":{"operationId":"create-study","summary":"Create a draft study","description":"Create a draft study. Publishing a study is a two step process, first create a draft study then publish it.\n\n## Taskflow Studies:\nTaskflow studies are created in the same manner as regular studies, however instead of providing an **external_study_url**, you should\nprovide an access_details array with **access_detail** objects instead, containing an external_url field and a total_allocation field.","tags":["studies"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Study"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStudy"}}}}}},"/api/v1/projects/{project_id}/studies/":{"get":{"operationId":"get-project-studies","summary":"List all studies in a project","description":"List all of your studies in a project.\n\nFor projects with a large number of studies, pagination can be used to optimize the response size and performance. To paginate, use the `page`, `page_size` and `ordering` query parameters. For example, to retrieve the first 10 studies, use `/api/v1/projects/{project_id}/studies/?page=1&page_size=10&ordering=-date_created`.","tags":["studies"],"parameters":[{"name":"project_id","in":"path","description":"Project id","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","description":"The page number to retrieve.","required":false,"schema":{"type":"integer"}},{"name":"page_size","in":"query","description":"The number of studies to retrieve per page.","required":false,"schema":{"type":"integer"}},{"name":"ordering","in":"query","description":"The ordering of the studies. Use `-date_created` to order by date created in descending order.","required":false,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of studies for the given project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudiesListResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}}}}},"/api/v1/projects/{project_id}/studies/{study_id}/":{"delete":{"operationId":"delete-project-study","summary":"Delete a study from a project","description":"Delete a study and remove it from a project. Only draft studies can be deleted.","tags":["studies"],"parameters":[{"name":"project_id","in":"path","description":"Project id","required":true,"schema":{"type":"string"}},{"name":"study_id","in":"path","description":"Study id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}}}}},"/api/v1/studies/{id}/":{"get":{"operationId":"get-study","summary":"Retrieve a study","description":"Retrieve a study by id. If you are polling the API for updates to a study, consider using a [Hook](#tag/Hooks). We will call your endpoint when certain events occur on your study, such as new completed submissions or changes in status.","tags":["studies"],"parameters":[{"name":"id","in":"path","description":"Study id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Study"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"delete-study","summary":"Delete a study","description":"Published studies cannot be deleted, but you can delete draft studies.","tags":["studies"],"parameters":[{"name":"id","in":"path","description":"Study id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Studies_DeleteStudy_Response_200"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"update-study","summary":"Update a study","description":"You can update any field for a draft study.\n\nOnce the study has been published only the following fields can be updated with some restrictions:\n- internal_name: Internal name of the study, not shown to participants\n- total_available_places: Only increasing is allowed. A completed study will become active again and resume recruiting of participants. For more information, check the [guide](https://researcher-help.prolific.com/en/articles/445201-how-do-i-increase-places-on-a-study)\n- access_details: Sending an access_detail will add a new task and increase overall study places by the number in the total_allocation field. Sending both access_details and total_available_places will increase places on existing URLs by the number specified on the access_detail.\n- data_collection_metadata.annotators_per_task: For AI Task Builder Batch studies, you can increase the number of annotators per task. This will automatically recalculate `total_available_places` based on the number of task groups multiplied by the new value. Note: This value can only be increased, not decreased, on a published study.\n- submissions_config: This allows you to update the max_submissions_per_participant, max_concurrent_submissions, or auto_rejection_categories. Please note decreasing max_submissions_per_participant will not affect submissions that have already been created.","tags":["studies"],"parameters":[{"name":"id","in":"path","description":"Study id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Study"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseStudy"}}}}}},"/api/v1/studies/{id}/transition/":{"post":{"operationId":"publish-study","summary":"Transition a study's status","description":"Transition a study between statuses using one of the available actions.\n\nThe following transitions are available:\n\n| Current Status | Action | Resulting Status |\n|---|---|---|\n| UNPUBLISHED | PUBLISH | ACTIVE |\n| UNPUBLISHED | SCHEDULE_PUBLISH | SCHEDULED |\n| SCHEDULED | CANCEL_PUBLISH | UNPUBLISHED |\n| ACTIVE | PAUSE | PAUSED |\n| ACTIVE | STOP | COMPLETED |\n| PAUSED | START | ACTIVE |\n| PAUSED | STOP | COMPLETED |\n\n**Action details:**\n- **PUBLISH**: Publish a draft study so participants can take part. The study must be fully configured.\n- **SCHEDULE_PUBLISH**: Schedule a draft study to be published at a future time. A `publish_at` field (ISO 8601 datetime) must be set either on the study or provided in this request.\n- **CANCEL_PUBLISH**: Cancel a scheduled publication, returning the study to draft.\n- **PAUSE**: Temporarily pause an active study. Participants already taking part can still complete, but no new participants will be recruited.\n- **START**: Resume a paused study.\n- **STOP**: Stop a study completely. To make it active again you will need to increase the number of places.\n\nTo learn more about it check out [help center](https://researcher-help.prolific.com/en/articles/445200-pausing-stopping-a-study)","tags":["studies"],"parameters":[{"name":"id","in":"path","description":"Study id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Study"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudyTransition"}}}}}},"/api/v1/studies/{id}/test-study":{"post":{"operationId":"create-test-study","summary":"Create a test study","description":"### Overview\n- Make sure atleast one test participant is created and exists against the user before hitting this endpoint.\n - To create test participant: POST /api/v1/researchers/participants/\n- Create and publish a test study from a draft study to all the test participants associated with the workspace.\n- This will allow a data collector to test the study as a participant.\n## Prerequisites\n✅ **Required:**\n- At least one active test participant (created via [`POST /api/v1/researchers/participants/`](#))\n- Study must be in draft status\n- Feature enabled for your workspace (contact support if unavailable)\n### Enabling the feature\nThis endpoint is only enabled for select workspaces and will need enabling before the endpoint can be used.\n","tags":["studies"],"parameters":[{"name":"id","in":"path","description":"Study id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestStudySetUpResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/studies/{id}/access-details-progress/":{"get":{"operationId":"get-study-access-details-progress","summary":"Get taskflow progress","description":"Returns per-URL allocation progress for a Taskflow study (studies configured with `access_details`).\nEach item in `progress` corresponds to one `external_url` from the study's access details, including how many participants are allocated and any screenout-driven capacity increments.\n\nReturns **404** if the study has no access-details collection (not a Taskflow study).","tags":["studies"],"parameters":[{"name":"id","in":"path","description":"Study id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Taskflow progress for the study's access details collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudyAccessDetailsProgress"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/studies/{id}/cost/":{"get":{"operationId":"get-study-cost","summary":"Show Study cost","description":"Returns cost information about the study. Default behaviour is to return cost at the time of the request, but projected cost can be requested via a query parameter.","tags":["studies"],"parameters":[{"name":"id","in":"path","description":"Study id","required":true,"schema":{"type":"string"}},{"name":"is_projected","in":"query","description":"Return the projected cost of the study","required":false,"schema":{"type":"boolean","default":false}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Return the total cost for the study","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudyTotalCost"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}}}}},"/api/v1/studies/{id}/submissions/":{"get":{"operationId":"get-study-submissions","summary":"List study submissions","description":"Returns basic information of the submissions, including the study id, participant id, status and start timestamp","tags":["studies"],"parameters":[{"name":"id","in":"path","description":"Study id","required":true,"schema":{"type":"string"}},{"name":"ordering","in":"query","description":"Field to sort results by. Prefix with `-` for descending order. Allowed values: `started_at`, `completed_at`, `status`, `ip`, `time_taken`, `participant_id`, `study_code`.","required":false,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List submissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionListResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}}}}},"/api/v1/studies/{id}/submissions/counts/":{"get":{"operationId":"count-study-submissions-by-status","summary":"Count study submissions by status","description":"Returns a count of the number of submissions per submission status in the study.","tags":["studies"],"parameters":[{"name":"id","in":"path","description":"Study id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Count of number of submissions per submission status for a study","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionsCountResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}}}}},"/api/v1/studies/{id}/credentials/report/":{"get":{"operationId":"download-study-credential-report","summary":"Download credential usage report","description":"Download a CSV report of credential usage for a study. The report includes participant IDs, submission IDs, usernames, and credential status (USED/UNUSED). This endpoint is only available for studies that have credentials configured.","tags":["studies"],"parameters":[{"name":"id","in":"path","description":"Study id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file containing credential usage report","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}}}}},"/api/v1/studies/{id}/export/":{"get":{"operationId":"export-study","summary":"Download demographic data","description":"**Deprecated - please use the new [Demographic Export](https://docs.prolific.com/docs/api-docs/public/#tag/Studies/operation/ExportDemographicData) endpoint instead.**\n\n**This endpoint will be sunset after the 14th of April 2026**\n\nDownload a snapshot of the participants' filter responses at the time that they took your study.\n\nIn addition to the responses to all filters applied to the study (subject to change), you'll also have access to the following data:\n\n* Submission id\n* Participant id\n* Submission status\n* Started date-time\n * Expressed in UTC\n * ISO 8601 formatted\n* Completed date-time\n * Expressed in UTC\n * ISO 8601 formatted\n* Time taken (in seconds)\n* Age\n* Sex\n * Participants were asked the following question: What is your sex, as recorded on legal/official documents?\n* Ethnicity (simplified)\n* First language\n* Current country of residence\n* Nationality\n* Country of birth\n* Student status\n* Employment status\n* Reviewed at date-time\n * Expressed in UTC\n * ISO 8601 formatted\n* Completion code ('entered code')\n* Total approvals\n\nLearn more on [Exporting Prolific demographic data](https://researcher-help.prolific.com/en/article/b2943f).","tags":["studies"],"parameters":[{"name":"id","in":"path","description":"Study id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Downloaded","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"deprecated":true}},"/api/v1/studies/{id}/demographic-export/":{"post":{"operationId":"export-demographic-data","summary":"Export demographic data","description":"Create and download a demographic export for a study. This endpoint allows you to export participant demographic data with optional study filter data.\n\n**Filter Support**: This endpoint supports applying demographic filters to export data for participants who match specific criteria.\n\nWhen filters are provided, the export includes both base demographic data (age, sex, country, etc.) and the filters.\n\nWhen no filters are provided, the export includes only base demographic data for all participants who took the study, excluding any study-specific filter responses.\n\n**Export Usage**: Please note that you may only select up to 15 filters per export. You are also limited to 2 different filter export requests.\n\nYou may download the same request as many times as you need. To check your current usage and see your latest export history, use the [Demographic Export History](https://docs.prolific.com/docs/api-docs/public/#tag/Studies/operation/GetDemographicExportHistory) endpoint.\n\n**Basic Data Included**: The export includes the following data fields:\n* Submission ID\n* Participant ID\n* Submission status\n* Started date-time\n * Expressed in UTC\n * ISO 8601 formatted\n* Completed date-time\n * Expressed in UTC\n * ISO 8601 formatted\n* Time taken (in seconds)\n* Age\n* Sex\n * Participants were asked the following question: What is your sex, as recorded on legal/official documents?\n* Ethnicity (simplified)\n* First language\n* Current country of residence\n* Nationality\n* Country of birth\n* Student status\n* Employment status\n* Reviewed at date-time\n * Expressed in UTC\n * ISO 8601 formatted\n* Completion code ('entered code')\n* Total approvals\n\nLearn more on [Exporting Prolific demographic data](https://researcher-help.prolific.com/en/article/b2943f).","tags":["studies"],"parameters":[{"name":"id","in":"path","description":"Study ID","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Demographic data exported successfully","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemographicExportRequest"}}}}}},"/api/v1/studies/{id}/demographic-export-history/":{"get":{"operationId":"get-demographic-export-history","summary":"Get demographic export history","description":"Retrieve the latest demographic export request history for a study. This endpoint returns information about your most recent export request, including the filters used and the total number of export combinations made.\n\n**Usage**: Use this endpoint to check your current export usage and see what filters were used in your latest request. This helps you understand your remaining export quota and track your export history.\n\n**Export Limits**: You are limited to 2 different filter combinations per study. This endpoint helps you track your usage against this limit.\n\nLearn more on [Exporting Prolific demographic data](https://researcher-help.prolific.com/en/article/b2943f).","tags":["studies"],"parameters":[{"name":"id","in":"path","description":"Study ID","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Export history retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemographicExportHistoryResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/studies/{id}/clone/":{"post":{"operationId":"duplicate-study","summary":"Duplicate a study","description":"Duplicating a study can save a lot of time and effort compared to creating a new study from scratch, since all of the information and data from the original study will be carried over to the new study. Additionally, duplicating a study can help ensure that the new study is set up consistently with the original, reducing the risk of errors or inconsistencies.\n\nTo prevent repeat participation, a block list containing the original study will be added to the duplicated study's filters unless `block_previous_participants` is set to `false` in the request body.","tags":["studies"],"parameters":[{"name":"id","in":"path","description":"Study id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Duplicated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Study"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"block_previous_participants":{"type":"boolean","default":true,"description":"Controls whether the block list is added or not."}}}}}}}},"/api/v1/study-cost-calculator/":{"post":{"operationId":"calculate-study-cost","summary":"Calculate the study cost","description":"Calculate the study cost, including VAT and fees.","tags":["studies"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Calculated total cost","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudyCostResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudyCostRequest"}}}}}},"/api/v1/filters/":{"get":{"operationId":"get-filters","summary":"List all filters","description":"List all filters that can be applied to your filter sets or studies.","tags":["filters"],"parameters":[{"name":"detailed","in":"query","description":"Include extra information required to sort and categorise filters in the Prolific app. This is not required for API use. Default false.","required":false,"schema":{"type":"string"}},{"name":"workspace_id","in":"query","description":"The workspace ID for the workspace you are creating a study or filterset in. This is used to get contextual data such as previous studies and participant groups.","required":false,"schema":{"type":"string"}},{"name":"filter_tag","in":"query","description":"Can be used to return only Custom Group filters.","required":false,"schema":{"type":"string"}},{"name":"include_deprecated","in":"query","description":"When true, deprecated filters are included in the response. Defaults to false. Used by the UI to resolve deprecated filters applied to existing studies.","required":false,"schema":{"type":"boolean","default":false}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of filters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilterList"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/filters/{id}/distribution/":{"get":{"operationId":"get-filter-distribution","summary":"Get filter distribution","description":"Get the distribution of a filter.","tags":["filters"],"parameters":[{"name":"id","in":"path","description":"ID of the filter to get distribution for. Only filters tagged with \"custom-group\" are supported.","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"query","description":"ID of your current workspace.","required":true,"schema":{"type":"string"}},{"name":"distribution_filters","in":"query","description":"Filters to get distributions for. This should be a comma-separated list of filter IDs. Only filters tagged with \"allow-distribution\" are supported.","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Filter distribution","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilterDistribution"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/eligibility-count/":{"post":{"operationId":"get-eligible-count","summary":"Count participants","description":"Count how many participants meet all the given filters.\nOnly participants that pass **every one** of the filters are counted.\nZero means that there are less than 5 participants. We do not show lower numbers to protect the privacy of the participants.\n\nTo see a list of filters that may be passed to this endpoint, see the documentation for filters.","tags":["filters"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Count","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequirementsCount"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequirementsCountRequest"}}}}}},"/api/v1/filter-sets/":{"get":{"operationId":"get-filter-sets","summary":"List all filter sets","description":"List of all filter sets in the specified workspace.","tags":["filterSets"],"parameters":[{"name":"workspace_id","in":"query","description":"ID of the workspace to get filter sets for.","required":false,"schema":{"type":"string"}},{"name":"organisation_id","in":"query","description":"ID of the organisation to get filter sets for.","required":false,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of filter sets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilterSetList"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create-filter-set","summary":"Create filter set","description":"Create a filter set from a list of filters","tags":["filterSets"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Filter set created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Filter Sets_CreateFilterSet_Response_201"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFilterSet"}}}}}},"/api/v1/filter-sets/{id}/":{"get":{"operationId":"get-filter-set","summary":"Get filter set","description":"Get details of a filter set.","tags":["filterSets"],"parameters":[{"name":"id","in":"path","description":"ID of the filter set.","required":true,"schema":{"type":"string"}},{"name":"version_number","in":"query","description":"Allows you to specify a specific version of the filter set to retrieve.","required":false,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Filter set details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Filter Sets_GetFilterSet_Response_200"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"delete-filter-set","summary":"Delete filter set","description":"Delete a filter set.","tags":["filterSets"],"parameters":[{"name":"id","in":"path","description":"ID of the filter set.","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted the filter set","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"update-filter-set","summary":"Update filter set","description":"Update the details of a filter set.","tags":["filterSets"],"parameters":[{"name":"id","in":"path","description":"ID of the filter set.","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Filter set updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Filter Sets_UpdateFilterSet_Response_200"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFilterSet"}}}}}},"/api/v1/filter-sets/{id}/clone/":{"post":{"operationId":"clone-filter-set","summary":"Clone filter set","description":"Create a copy of a filter set.","tags":["filterSets"],"parameters":[{"name":"id","in":"path","description":"ID of the filter set.","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Filter set cloned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Filter Sets_CloneFilterSet_Response_201"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_name":{"type":"string","description":"A new name for the cloned filter set."}}}}}}}},"/api/v1/filter-sets/{id}/lock/":{"post":{"operationId":"lock-filter-set","summary":"Lock filter set for editing","description":"Lock the filter set for editing.","tags":["filterSets"],"parameters":[{"name":"id","in":"path","description":"ID of the filter set.","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Filter set locked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Filter Sets_LockFilterSet_Response_200"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/filter-sets/{id}/unlock/":{"post":{"operationId":"unlock-filter-set","summary":"Unlock filter set for editing","description":"Unlock the filter set for editing.","tags":["filterSets"],"parameters":[{"name":"id","in":"path","description":"ID of the filter set.","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Filter set locked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Filter Sets_UnlockFilterSet_Response_200"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/participant-groups/":{"get":{"operationId":"get-participant-groups","summary":"Get a list of all participant groups within a project or workspace","tags":["participantGroups"],"parameters":[{"name":"active","in":"query","description":"Filter by the active (not deleted) status of the participant group.","required":false,"schema":{"$ref":"#/components/schemas/ApiV1ParticipantGroupsGetParametersActive"}},{"name":"filter","in":"query","required":true,"schema":{"$ref":"#/components/schemas/ApiV1ParticipantGroupsGetParametersFilter"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Request successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantGroupListResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create-participant-group","summary":"Create a new participant group within a workspace","tags":["participantGroups"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Participant group created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantGroupResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"workspace_id":{"type":"string","description":"The id of the workspace to create the participant group in. Either a workspace or organisation ID must be specified."},"organisation_id":{"type":"string","description":"The id of the organisation to create the participant group in. Either a workspace or organisation ID must be specified."},"name":{"type":"string","description":"The name of the participant group"},"description":{"type":"string","description":"A description of the participant group"},"participant_ids":{"type":"array","items":{"type":"string"},"description":"The ids of participants to be initially added to the group"}},"required":["name"]}}}}}},"/api/v1/participant-groups/{id}/":{"get":{"operationId":"get-participant-group","summary":"Get a participant group","tags":["participantGroups"],"parameters":[{"name":"id","in":"path","description":"The id of the participant group","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Request successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantGroupResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"delete-participant-group","summary":"Delete a participant group","tags":["participantGroups"],"parameters":[{"name":"id","in":"path","description":"The id of the participant group","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"update-participant-group","summary":"Update a participant group","tags":["participantGroups"],"parameters":[{"name":"id","in":"path","description":"The id of the participant group","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Request successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantGroupResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantGroupUpdate"}}}}}},"/api/v1/participant-groups/{id}/participants/":{"get":{"operationId":"get-participant-group-participants","summary":"Get a list of all participants within a participant group","tags":["participantGroups"],"parameters":[{"name":"id","in":"path","description":"The id of the participant group to get participants for","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Request successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantGroupMembershipListResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"add-to-participant-group","summary":"Add participants to a participant group","description":"Append participants to a participant group if they are not already members. If a participant is already a member of the group, they will be ignored.\n","tags":["participantGroups"],"parameters":[{"name":"id","in":"path","description":"The id of the participant group to add the participant to","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"All participant(s) now in participant group","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantGroupMembershipListResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantIDList"}}}}},"delete":{"operationId":"remove-from-participant-group","summary":"Remove participants from a participant group","description":"Remove specified participants from a participant group if they are members. If a participant is not a member of the group, they will be ignored.\n","tags":["participantGroups"],"parameters":[{"name":"id","in":"path","description":"The id of the participant group to remove the participant(s) from","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"All participant(s) now in participant group","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantGroupMembershipListResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantIDList"}}}}}},"/api/v1/submissions/":{"get":{"operationId":"get-submissions","summary":"List submissions","description":"Returns basic information of submissions, including study id, participant id, status and start timestamp.\n\n**Filtering and Ordering:**\n- Filter by status, completion state, dates, and study\n- Order by start time, reward amount, or study name\n- Paginate by page_size and page (Default page_size is 20)\n- Boolean parameters accept multiple formats: 1/0, true/false, yes/no, t/f (case-insensitive)\n- Date parameters use DD/MM/YYYY format\n- Status parameters are case-insensitive with underscore normalization","tags":["submissions"],"parameters":[{"name":"study","in":"query","description":"Filter by study ID (required). This is the ID we pass to the survey platform using %STUDY_ID%","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","description":"Filter by submission status (case-insensitive). Valid values include ACTIVE, AWAITING_REVIEW, APPROVED, REJECTED, RETURNED, SCREENED_OUT, TIMED-OUT","required":false,"schema":{"$ref":"#/components/schemas/ApiV1SubmissionsGetParametersStatus"}},{"name":"completed","in":"query","description":"Filter by completion status. Accepts 1/true/yes/t for completed, 0/false/no/f for incomplete (case-insensitive)","required":false,"schema":{"$ref":"#/components/schemas/ApiV1SubmissionsGetParametersCompleted"}},{"name":"returned","in":"query","description":"Filter by returned status. Accepts 1/true/yes/t for returned, 0/false/no/f for not returned (case-insensitive)","required":false,"schema":{"$ref":"#/components/schemas/ApiV1SubmissionsGetParametersReturned"}},{"name":"awaiting_review","in":"query","description":"Filter by awaiting review status. Accepts 1/true/yes/t for awaiting review, 0/false/no/f for not awaiting review (case-insensitive)","required":false,"schema":{"$ref":"#/components/schemas/ApiV1SubmissionsGetParametersAwaitingReview"}},{"name":"approved","in":"query","description":"Filter by approved status. Accepts 1/true/yes/t for approved, 0/false/no/f for not approved (case-insensitive)","required":false,"schema":{"$ref":"#/components/schemas/ApiV1SubmissionsGetParametersApproved"}},{"name":"active","in":"query","description":"Filter by active status. Accepts 1/true/yes/t for active, 0/false/no/f for not active (case-insensitive)","required":false,"schema":{"$ref":"#/components/schemas/ApiV1SubmissionsGetParametersActive"}},{"name":"timeout","in":"query","description":"Filter by timed out status. Accepts 1/true/yes/t for timed out, 0/false/no/f for not timed out (case-insensitive)","required":false,"schema":{"$ref":"#/components/schemas/ApiV1SubmissionsGetParametersTimeout"}},{"name":"rejected","in":"query","description":"Filter by rejected status. Accepts 1/true/yes/t for rejected, 0/false/no/f for not rejected (case-insensitive)","required":false,"schema":{"$ref":"#/components/schemas/ApiV1SubmissionsGetParametersRejected"}},{"name":"screened_out","in":"query","description":"Filter by screened out status. Accepts 1/true/yes/t for screened out, 0/false/no/f for not screened out (case-insensitive)","required":false,"schema":{"$ref":"#/components/schemas/ApiV1SubmissionsGetParametersScreenedOut"}},{"name":"completeoractive","in":"query","description":"Filter for submissions that are either completed or active. Accepts 1/true/yes/t to include, 0/false/no/f to exclude (case-insensitive)","required":false,"schema":{"$ref":"#/components/schemas/ApiV1SubmissionsGetParametersCompleteoractive"}},{"name":"submitted_from","in":"query","description":"Filter submissions completed after the given date. Format DD/MM/YYYY (e.g., 01/01/2024)","required":false,"schema":{"type":"string","pattern":"^[0-3][0-9]/[0-1][0-9]/[0-9]{4}$"}},{"name":"submitted_before","in":"query","description":"Filter submissions completed before the given date. Format DD/MM/YYYY (e.g., 31/12/2024)","required":false,"schema":{"type":"string","pattern":"^[0-3][0-9]/[0-1][0-9]/[0-9]{4}$"}},{"name":"ordering","in":"query","description":"Order results by field. Prefix with '-' for descending order. Supported values are started_at, submission_reward, study_name","required":false,"schema":{"$ref":"#/components/schemas/ApiV1SubmissionsGetParametersOrdering"}},{"name":"page_size","in":"query","description":"Number of items to return per page (Default 20)","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","description":"Page number to retrieve (Default 1)","required":false,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List submissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionListResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}}}}},"/api/v1/submissions/{id}/":{"get":{"operationId":"get-submission","summary":"Retrieve a submission","description":"Returns the detailed information of a submission, including the\nstudy id, participant id, status and start timestamp","tags":["submissions"],"parameters":[{"name":"id","in":"path","description":"Submission id. This is the ID we pass to the survey platform\nusing %SESSION_ID%","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionDetail"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/submissions/{id}/transition/":{"post":{"operationId":"transition-submission","summary":"Approve or reject a submission","description":"Transition a submission to `APPROVED`, `REJECTED`, `PARTIALLY APPROVED`, `AWAITING REVIEW` or `SCREENED OUT`. Once the status is changed, it can not be restored to its previous value.\n\nYou can only transition a submission to PARTIALLY APPROVED or SCREENED OUT by:\n - setting up the study with the appropriate completion codes (only some workspaces have access to these features)\n - providing the correct completion code in the request body\n - providing the necessary data in the request body (to PARTIALLY APPROVE a submission)\n\nNote this endpoint is idempotent, so if you make the same request twice, the second request will be ignored.","tags":["submissions"],"parameters":[{"name":"id","in":"path","description":"Submission id. This is the ID we pass to the survey platform\nusing %SESSION_ID%","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Submission"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionTransition"}}}}}},"/api/v1/submissions/{id}/request-return/":{"post":{"operationId":"request-submission-return","summary":"Request the participant who submitted the response to return their response","description":"**This is an experimental feature that may be subject to change in the future.**
\nIt 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:\n* Didn't finish the study\n* Encountered technical problems\n* Withdrew consent\n* Other ( uses the free text input)\n\nThis constructs a message around the reasons provided so there is no need to provide additional text beyond the reasons.\n\"Example\"\n","tags":["submissions"],"parameters":[{"name":"id","in":"path","description":"The submission id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"A message is sent to the participant belonging to the submission asking them to return.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnRequestedResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request_return_reasons":{"type":"array","items":{"type":"string"}}},"required":["request_return_reasons"]}}}}}},"/api/v1/submissions/bulk-approve/":{"post":{"operationId":"bulk-approve-submissions","summary":"Bulk approve submissions","description":"Bulk approve study submissions to pay participants after they have\ncompleted your survey or experiment. There are two variant payloads to\nthis request.\n\n- You can supply a Study ID, and a list of participant IDs, or\n- You can provide a list of submission IDs\n\nWe strongly recommend that you provide a list of submission IDs. These submissions do not need to be from the same study.\n\nWe recommend a maximum of 1,000 submission or participant IDs per request.","tags":["submissions"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Bulk approve in progress","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Submissions_BulkApproveSubmissions_Request"}}}}}},"/api/v1/submissions/signals/upload-url/{filename}":{"get":{"operationId":"get-submission-feedback-upload-url","summary":"Request a feedback upload URL","description":"Request a temporary, pre-signed URL to upload a feedback file for your completed studies.\n\nThis is the first step of a two-step upload process:\n 1. Call this endpoint to receive a pre-signed `upload_url`.\n 2. Upload your file directly to that URL with an HTTP `PUT` request before it expires.\n\n\n Supported file formats are CSV, XLS, XLSX, JSON, TXT and PDF. The maximum file size is 5GB. Please check the [supported file formats](/api-reference/submission-feedback-upload#supported-file-formats) section for more details.\n","tags":["submissionFeedbackUpload"],"parameters":[{"name":"filename","in":"path","description":"The name of the file you want to upload, including its extension (e.g. `participant_feedback.csv`).","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"query","description":"The ID of the Prolific workspace the feedback belongs to.","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Pre-signed upload URL generated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Submission Feedback Upload_GetSubmissionFeedbackUploadUrl_Response_201"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/submissions/bonus-payments/":{"post":{"operationId":"create-bonus-payments","summary":"Set up bonuses","description":"Set up bonus payments to one or more participants/submissions in a study.\n\nYou need the study id, the participant|submission ids and the request in CSV format.\n\nThe csv_bonuses field needs to be structured in the format of either:\n\n- `,\\n`.\n- `,\\n`.\n\n**Note: The amount will be in the study currency. The amount should be a decimal value, e.g. 1.50 for £1.50.**\nWarning: An amount of 30 will pay £/$30.00.\n\nAs an example, `60ffe5c8371090c7041d43f8,4.25` would be a bonus of £4.25 for participant 60ffe5c8371090c7041d43f8 in a study with GBP currency.\n\nSetting up a bonus payment does not actually pay them, to do so check [/api/v1/bulk-bonus-payments/{id}/pay/](#tag/Bonuses/paths/~1api~1v1~1bulk-bonus-payments~1%7Bid%7D~1pay~1/post)\n\nThe submission and participant IDs need to have taken part in the study in order for this call to be successful.\nIf not, you will get a \"400\" HTTP response back, which explains which IDs are incorrect.\n\nWe recommend a maximum of 200 participant or submission IDs per request.","tags":["bonuses"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Bonus created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkBonus"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"study_id":{"type":"string"},"csv_bonuses":{"type":"string"}}}}}}}},"/api/v1/bulk-bonus-payments/{id}/pay/":{"post":{"operationId":"pay-bonus-payments","summary":"Pay bonuses","description":"Bonus payments are made asynchronously.\nThe payment will be done in the following minutes and your balance will be updated accordingly.\n\n\nThis endpoint is **not idempotent**. Sending multiple requests with the same bulk bonus payment ID will result in participants being paid multiple times. Ensure you send this request only once per bulk payment.\n","tags":["bonuses"],"parameters":[{"name":"id","in":"path","description":"Bulk bonus payment id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"Successfully received bonus payments request. The bonuses will be paid asynchronously.","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/messages/":{"get":{"operationId":"get-messages","summary":"Retrieve messages","description":"Get messages between you and another user or your messages with all users.","tags":["messages"],"parameters":[{"name":"user_id","in":"query","description":"Another user ID, must be provided if no created_after date is provided.","required":false,"schema":{"type":"string"}},{"name":"created_after","in":"query","description":"Only fetch messages created after timestamp. Datetime in ISO8601 format. Must be provided if no user_id is provided. You can only fetch up to the last 30 days of messages.","required":false,"schema":{"type":"string"}},{"name":"excluded_sender_ids","in":"query","description":"A comma-separated list of sender IDs whose messages should be excluded from the response. Maximum 10 IDs.\n\ne.g. `excluded_sender_ids=abc,def`.\n","required":false,"schema":{"type":"string"}},{"name":"workspace_id","in":"query","description":"Optional. The ID of one of your workspaces. When provided, the response contains the messages belonging to that workspace rather than the messages belonging to your own account, so you see the conversations of every member of the workspace in one place.\n\nThis parameter is intended for workspaces that have workspace messaging enabled. If workspace messaging is not enabled for the given workspace, no messages are returned.\n\nYou must be a member of the workspace you request. This parameter cannot be used by participants.\n\nRead more about workspace messaging: https://researcher-help.prolific.com/en/articles/445238-workspace-messaging\n","required":false,"schema":{"type":"string"}},{"name":"study_id","in":"query","description":"Optional. Only return messages sent with this exact `study_id`. Use `study_id=null` to return only messages that are not associated with any study. Omit the parameter to return messages regardless of study. Only supported alongside `created_after`. Cannot be combined with `user_id` or `excluded_sender_ids`.\n","required":false,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Messages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Messages"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}},"503":{"description":"Message service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}},"504":{"description":"Message query timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}}}},"post":{"operationId":"send-message","summary":"Send a message","description":"Send a message to a participant or another researcher","tags":["messages"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"The message has been sent","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessage"}}}}}},"/api/v1/messages/bulk/":{"post":{"operationId":"bulk-message-participants","summary":"Send a message to multiple participants","description":"Send a message to multiple participants.","tags":["messages"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"The message has been sent","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendBulkMessage"}}}}}},"/api/v1/messages/participant-group/":{"post":{"operationId":"send-message-to-participant-group","summary":"Send a message to a participant group","description":"Send a message to a participant group.","tags":["messages"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"The message has been sent","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageParticipantGroup"}}}}}},"/api/v1/messages/unread/":{"get":{"operationId":"get-unread-messages","summary":"Retrieve unread messages","description":"Get all unread messages.\nThe messages you have sent are never returned, only messages you have received and not read.\nIt does not mark those messages as read.","tags":["messages"],"parameters":[{"name":"workspace_id","in":"query","description":"Optional. The ID of one of your workspaces. When provided, the response contains the unread messages belonging to that workspace rather than the unread messages belonging to your own account, so you see the unread messages of every member of the workspace in one place.\n\nThis parameter is intended for workspaces that have workspace messaging enabled. If workspace messaging is not enabled for the given workspace, no unread messages are returned.\n\nYou must be a member of the workspace you request. This parameter cannot be used by participants.\n\nRead more about workspace messaging: https://researcher-help.prolific.com/en/articles/445238-workspace-messaging\n","required":false,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Messages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Messages"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}},"503":{"description":"Message service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}},"504":{"description":"Message query timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}}}}},"/api/v1/workspaces/":{"get":{"operationId":"get-workspaces","summary":"Get all a user's workspaces","description":"Gets a list of all workspaces that the user is a member of.","tags":["workspaces"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspacesListResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create-workspace","summary":"Create a workspace","description":"Creates a new workspace and adds the user as a Workspace Admin.","tags":["workspaces"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Created workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkspace"}}}}}},"/api/v1/workspaces/{workspace_id}/":{"get":{"operationId":"get-workspace","summary":"Get workspace","description":"Gets a workspace's details","tags":["workspaces"],"parameters":[{"name":"workspace_id","in":"path","description":"Workspace id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"update-workspace","summary":"Update a workspace","description":"Updates a workspace's details.","tags":["workspaces"],"parameters":[{"name":"workspace_id","in":"path","description":"Workspace id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated workspace redirect link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}}}}},"/api/v1/workspaces/{workspace_id}/balance/":{"get":{"operationId":"get-workspace-balance","summary":"Get the balance of a workspace","description":"Provides details of the funds available in the workspace.","tags":["workspaces"],"parameters":[{"name":"workspace_id","in":"path","description":"Workspace id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceBalance"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/workspaces/{workspace_id}/projects/":{"get":{"operationId":"get-projects","summary":"Get all projects in a workspace","description":"Gets a list of all the projects within the workspace.","tags":["projects"],"parameters":[{"name":"workspace_id","in":"path","description":"Workspace id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectShortListResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create-project","summary":"Create a project","description":"Creates a new project within the workspace.\nWhen this project is created, it adds the user as a Project Editor.\nSet `type` to `PUBLIC` to create a public project.","tags":["projects"],"parameters":[{"name":"workspace_id","in":"path","description":"Workspace id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Successfully created project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProject"}}}}}},"/api/v1/projects/{project_id}/":{"get":{"operationId":"get-project","summary":"Get project","description":"Gets a project's details","tags":["projects"],"parameters":[{"name":"project_id","in":"path","description":"Project id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"update-project","summary":"Update a project","description":"Update a project's details.\nPublic projects support partial updates to `public_details`.\nOnce a public project has published studies, `public_details.title` can no longer be changed.","tags":["projects"],"parameters":[{"name":"project_id","in":"path","description":"Project id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated project redirect link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProject"}}}}}},"/api/v1/surveys/":{"get":{"operationId":"get-surveys","summary":"Get all surveys","description":"Get all the surveys for a researcher.","tags":["surveys"],"parameters":[{"name":"researcher_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAllSurveysResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create-survey","summary":"Create survey","description":"You can create a survey with either `sections -> questions` or just `questions`. This allows you to decide\nhow much flexibility you want in your survey design. However, if you want to render the survey in the Prolific Application, you must use `sections`.","tags":["surveys"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurveyOut"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurveyIn"}}}}}},"/api/v1/surveys/{survey_id}":{"get":{"operationId":"get-survey","summary":"Get survey","description":"Get a single survey given an ID.","tags":["surveys"],"parameters":[{"name":"survey_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurveyOut"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"delete-survey","summary":"Delete survey","description":"Delete a single Survey.","tags":["surveys"],"parameters":[{"name":"survey_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"description":"Any type"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/surveys/{survey_id}/responses/":{"get":{"operationId":"get-responses","summary":"Get all responses","description":"Get all the responses for a given Survey.","tags":["surveys"],"parameters":[{"name":"survey_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"description":"Any type"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create-response","summary":"Create response","description":"Create a Response for a survey.","tags":["surveys"],"parameters":[{"name":"survey_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurveyResponseOut"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurveyResponseIn"}}}}},"delete":{"operationId":"delete-responses","summary":"Delete all responses","description":"Delete all the responses for a given Survey.","tags":["surveys"],"parameters":[{"name":"survey_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"description":"Any type"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/surveys/{survey_id}/responses/summary/":{"get":{"operationId":"get-summary","summary":"Get summary of responses","description":"Get an aggregated summary of responses for a given survey.","tags":["surveys"],"parameters":[{"name":"survey_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurveySummary"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/surveys/{survey_id}/responses/{response_id}":{"get":{"operationId":"get-response","summary":"Get response","description":"Get a single response for a survey.","tags":["surveys"],"parameters":[{"name":"survey_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"response_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurveyResponseOut"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"delete-response","summary":"Delete a response","description":"Delete a single Response.","tags":["surveys"],"parameters":[{"name":"survey_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"response_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"description":"Any type"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/hooks/event-types/":{"get":{"operationId":"get-event-types","summary":"List all subscribable event types","description":"You can subscribe to any of the event types defined in this response.","tags":["webhooks"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of event types that can be subscribed to.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventTypeList"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/hooks/secrets/":{"get":{"operationId":"get-secrets","summary":"List all secrets","description":"A view of all the secrets for the workspaces you belong to.","tags":["webhooks"],"parameters":[{"name":"workspace_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecretList"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create-secret","summary":"Create/replace a secret","description":"Generate a secret for verifying the request signature header of the subscription payload. If a secret already exists, this call will delete the old secret and create a new one.","tags":["webhooks"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecretDetail"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSecret"}}}}}},"/api/v1/hooks/subscriptions/":{"get":{"operationId":"get-subscriptions","summary":"List all subscriptions","description":"A view of all subscriptions you have created.","tags":["webhooks"],"parameters":[{"name":"is_enabled","in":"query","description":"A filter to only pull back enabled subscriptions. Default true.","required":false,"schema":{"type":"boolean"}},{"name":"workspace_id","in":"query","description":"The Workspace ID we want to get the subscriptions for. If not given, the subscriptions for all of your workspaces will be returned.","required":false,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of subscriptions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionList"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create-subscription","summary":"Create a subscription","description":"Create a subscription for an event type. When an event is triggered in the Prolific system, the hook will automatically notify the specified target URL.\n\nBefore creating a subscription, you must ensure that you have created a secret for your workspace.\n\nA new subscription is created with `is_enabled` set to `false` and won't receive any events until it has been confirmed via the [confirm subscription endpoint](/api-reference/webhooks/confirm-subscription).","tags":["webhooks"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionList"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionDetail"}}}}}},"/api/v1/hooks/subscriptions/{subscription_id}/":{"get":{"operationId":"get-subscription","summary":"Retrieve a subscription","description":"Get a single subscription","tags":["webhooks"],"parameters":[{"name":"subscription_id","in":"path","description":"Subscription id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionDetail"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"confirm-subscription","summary":"Confirm a subscription","description":"Confirm a subscription to an event type","tags":["webhooks"],"parameters":[{"name":"subscription_id","in":"path","description":"Subscription id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionDetail"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionConfirmation"}}}}},"delete":{"operationId":"delete-subscription","summary":"Delete a subscription","description":"If you no longer require to be notified of a certain event type, you can delete a subscription. If you want to temporarily pause notifications, you can use the PATCH request documented.","tags":["webhooks"],"parameters":[{"name":"subscription_id","in":"path","description":"Subscription id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"update-subscription","summary":"Update a subscription","description":"This allows you to update a subscription. For example you can temporarily disable or enable a subscription if you wish.","tags":["webhooks"],"parameters":[{"name":"subscription_id","in":"path","description":"Subscription id","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionDetail"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionUpdateDetail"}}}}}},"/api/v1/hooks/subscriptions/{subscription_id}/events/":{"get":{"operationId":"get-events","summary":"Get subscription events","description":"Get all of the events that have triggered for the given subscription.","tags":["webhooks"],"parameters":[{"name":"subscription_id","in":"path","description":"Subscription id","required":true,"schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}},{"name":"status","in":"query","description":"Filter events by status. Accepts a single status or a JSON array of statuses as a string.","required":false,"schema":{"type":"string"}},{"name":"resource_id","in":"query","description":"Filter events by the ID of the resource for which the event was sent.","required":false,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionEventList"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/invitations/":{"post":{"operationId":"create-invitation","summary":"Create a new invitation","description":"Initiate a new invitation process for adding users to a Workspace.\n\nThis operation can be performed only by authenticated users who are admins for the specified workspace. Invitations will be sent to the email addresses provided in the request.\n","tags":["invitations"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Invitation created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvitationResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvitationRequest"}}}}}},"/api/v1/reward-recommendations/":{"get":{"operationId":"calculate-reward-recommendations","summary":"Calculate reward recommendations","description":"Calculate the recommended participant reward rates for a data collection, optionally based upon a given set of filters","tags":["rewardRecommendations"],"parameters":[{"name":"workspace_id","in":"query","description":"The ID of the workspace in which you'll be creating the study","required":true,"schema":{"type":"string"}},{"name":"currency","in":"query","description":"An ISO 4217 currency code. Note that we only support a selection of currency codes as per the enum values.","required":true,"schema":{"$ref":"#/components/schemas/ApiV1RewardRecommendationsGetParametersCurrency"}},{"name":"screener_ids","in":"query","description":"A URL-encoded, comma-delimited list of filter IDs (e.g. custom group filter IDs) that you plan to apply to your study.\n\nThere are various methods of converting an array of filter IDs to a URL-encoded, comma delimited array e.g:\n\nJavaScript:\n\n```js\nconst screenerIDs = [\"mandarin\", \"spanish\"];\nconst encodedScreenerIDs = encodeURIComponent(screenerIDs.join(\",\"));\nconst url = `https://api.prolific.com/api/v1/reward-recommendations?screener_ids=${encodedScreenerIDs}&workspace_id=¤cy=GBP`\n```\n\nPython:\n\n```python\nimport urllib.parse\n\nscreener_ids = [\"mandarin\", \"spanish\"]\nencoded_screener_ids = urllib.parse.quote(\",\".join(screener_ids))\nurl = f\"https://api.prolific.com/api/v1/reward-recommendations?screener_ids={encoded_screener_ids}&workspace_id=¤cy=GBP\"\n```","required":false,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"A list of reward recommendations. We suggest using the first recommendation in the list as this is guaranteed to be the most recent set of reward rates.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RewardRecommendationsResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}}}}},"/.well-known/study/jwks.json":{"get":{"operationId":"get-study-jwks","summary":"Retrieve JSON Web Key Set (JWKS)","description":"Fetches the public keys that can be used to verify JWTs signed by Prolific. Clients should cache these keys and update them at least daily.\n\nTo verify the signature of a JWT you must verify the following:\n* The JWT signature is authentic by verifying it with the public key from Prolific that correlates with the KID.\n* The JWT hasn't expired, by checking the `exp` claim.\n* The `aud` claim is the correct domain for your tool.\n* The `prolific` claim matches your expected payload as set in the `external_study_url` property. It always includes `PROLIFIC_PID`, `STUDY_ID`, `SESSION_ID`, and `workspace_id`. When the workspace is linked to an organisation, it also includes `organisation_id`.\n","tags":["wellKnownEndpoints"],"responses":{"200":{"description":"Successful response with the JWKS.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JWKSResponse"}}}}}}},"/api/v1/credentials/":{"get":{"operationId":"list-credential-pools","summary":"List credential pools for a workspace","description":"Retrieve a list of credential pools belonging to a specific workspace.\nEach credential pool summary includes the pool ID, total number of credentials, number of available (unredeemed) credentials, and the workspace ID.","tags":["credentials"],"parameters":[{"name":"workspace_id","in":"query","description":"The workspace ID to filter credential pools by","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Credential pools retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credentials_ListCredentialPools_Response_200"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}},"403":{"description":"Forbidden - User does not have workspace.workspace_update permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}},"502":{"description":"Bad Gateway - Credentials service unavailable or internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}}}},"post":{"operationId":"create-credential-pool","summary":"Create credential pool","description":"Create a new workspace-level credential pool. Credential pools contain username/password pairs that can be assigned to participants when they start a study. This allows researchers to provide pre-provisioned credentials for third-party platforms.\nThe credentials are provided as a CSV string where each line contains a username and password separated by a comma (e.g., \"user1,pass1\\nuser2,pass2\").","tags":["credentials"],"parameters":[{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Credential pool created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credentials_CreateCredentialPool_Response_201"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}},"403":{"description":"Forbidden - User does not have workspace.workspace_update permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}},"409":{"description":"Conflict - Duplicate credentials detected (username already exists in pool)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}},"502":{"description":"Bad Gateway - Credentials service unavailable or internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"credentials":{"type":"string","description":"CSV-formatted credentials (username,password per line)"},"workspace_id":{"type":"string","description":"The ID of the workspace this credential pool belongs to"}},"required":["credentials","workspace_id"]}}}}}},"/api/v1/credentials/{credential_pool_id}/":{"patch":{"operationId":"update-credential-pool","summary":"Update credential pool","description":"Add new credentials to an existing credential pool. This operation is additive - new credentials are appended to the existing pool rather than replacing them. The credentials service validates that no duplicate usernames exist.\nThe credentials are provided as a CSV string where each line contains a username and password separated by a comma (e.g., \"user4,pass4\\nuser5,pass5\").","tags":["credentials"],"parameters":[{"name":"credential_pool_id","in":"path","description":"Credential pool ID","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Credential pool updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credentials_UpdateCredentialPool_Response_200"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}},"403":{"description":"Forbidden - User does not have workspace.workspace_update permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}},"404":{"description":"Not Found - Credential pool does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}},"409":{"description":"Conflict - Duplicate credentials detected (username already exists in pool)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}},"502":{"description":"Bad Gateway - Credentials service unavailable or internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"credentials":{"type":"string","description":"CSV-formatted credentials to add (username,password per line)"}},"required":["credentials"]}}}}}}},"servers":[{"url":"https://api.prolific.com","description":"Production"}],"components":{"schemas":{"User":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"}},"required":["id","email"],"title":"User"},"ErrorDetailDetail2":{"type":"object","properties":{"any_field":{"type":"array","items":{"type":"string"},"description":"Name of the field with a validation error and as a value an array with the error descriptions"}},"description":"All fields with validation errors","title":"ErrorDetailDetail2"},"ErrorDetailDetail":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"$ref":"#/components/schemas/ErrorDetailDetail2"}],"description":"Error detail","title":"ErrorDetailDetail"},"ErrorDetail":{"type":"object","properties":{"status":{"type":"integer","description":"Status code as in the http standards"},"error_code":{"type":"integer","description":"Internal error code"},"title":{"type":"string","description":"Error title"},"detail":{"$ref":"#/components/schemas/ErrorDetailDetail","description":"Error detail"},"additional_information":{"type":"string","description":"Optional extra information"},"traceback":{"type":"string","description":"Optional debug information"},"interactive":{"type":"boolean"}},"required":["status","error_code","title","detail"],"title":"ErrorDetail"},"Error":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"title":"Error"},"CreateTestParticipantForResearcher":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"- The email of the test participant.\n- This cannot be an email that has been registered with Prolific already.\n"}},"required":["email"],"title":"CreateTestParticipantForResearcher"},"CreateTestParticipantForResearcherResponse":{"type":"object","properties":{"participant_id":{"type":"string","format":"objectId","description":"The ID of the test participant"}},"title":"CreateTestParticipantForResearcherResponse"},"AiTaskBuilderBatchDatasetsItems":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"total_datapoint_count":{"type":"integer","minimum":0},"filename":{"type":"string","description":"The filename of the dataset"}},"required":["id","total_datapoint_count","filename"],"title":"AiTaskBuilderBatchDatasetsItems"},"AiTaskBuilderBatchStatus":{"type":"string","enum":["UNINITIALISED","PROCESSING","READY","ERROR"],"title":"AiTaskBuilderBatchStatus"},"AiTaskBuilderBatchTaskDetails":{"type":"object","properties":{"task_name":{"type":"string"},"task_introduction":{"type":"string","description":"HTML formatted task introduction"},"task_steps":{"type":"string","description":"HTML formatted task steps"}},"required":["task_name","task_introduction","task_steps"],"title":"AiTaskBuilderBatchTaskDetails"},"BatchItemsPageDisplayPosition":{"type":"string","enum":["intro","outro","body"],"description":"Renders the page once — before (\"intro\") or after (\"outro\") the repeating body —\ninstead of once per datapoint. Omit (or set \"body\") for the default repeating\nbehaviour. Pages with display_position \"intro\" or \"outro\" may only contain\nrich_text/image content blocks, not instructions or dataset_field refs.","title":"BatchItemsPageDisplayPosition"},"BatchItemsDatasetFieldRefType":{"type":"string","enum":["dataset_field"],"title":"BatchItemsDatasetFieldRefType"},"BatchItemsImageBlockType":{"type":"string","enum":["image"],"title":"BatchItemsImageBlockType"},"BatchItemsRichTextBlockType":{"type":"string","enum":["rich_text"],"title":"BatchItemsRichTextBlockType"},"BatchItemsRichTextBlockContentFormat":{"type":"string","enum":["html","markdown"],"default":"html","description":"Format of the `content` field. Defaults to `html`.","title":"BatchItemsRichTextBlockContentFormat"},"BatchItemsFreeTextInstructionType":{"type":"string","enum":["free_text"],"title":"BatchItemsFreeTextInstructionType"},"ValidationRuleType":{"type":"string","enum":["number","string"],"description":"The expected input type. When \"number\", the input must be numeric and min/max constrain the numeric value. When \"string\", the input is treated as text and min/max constrain the character count.","title":"ValidationRuleType"},"ValidationRule":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ValidationRuleType","description":"The expected input type. When \"number\", the input must be numeric and min/max constrain the numeric value. When \"string\", the input is treated as text and min/max constrain the character count."},"min":{"type":["number","null"],"format":"double","description":"Minimum value (for type \"number\") or minimum character count (for type \"string\"). Null means unbounded. When type is \"string\", must be a non-negative integer. If both min and max are provided, min must be less than or equal to max."},"max":{"type":["number","null"],"format":"double","description":"Maximum value (for type \"number\") or maximum character count (for type \"string\"). Null means unbounded. When type is \"string\", must be a non-negative integer. If both min and max are provided, max must be greater than or equal to min."}},"required":["type"],"description":"Optional validation constraints for input values","title":"ValidationRule"},"BatchItemsFreeTextWithUnitInstructionType":{"type":"string","enum":["free_text_with_unit"],"title":"BatchItemsFreeTextWithUnitInstructionType"},"BatchItemsFreeTextWithUnitInstructionUnitOptionsItemsValue":{"oneOf":[{"type":"string"},{"type":"number","format":"double"},{"type":"boolean"}],"title":"BatchItemsFreeTextWithUnitInstructionUnitOptionsItemsValue"},"BatchItemsFreeTextWithUnitInstructionUnitOptionsItems":{"type":"object","properties":{"label":{"type":"string"},"value":{"$ref":"#/components/schemas/BatchItemsFreeTextWithUnitInstructionUnitOptionsItemsValue"},"validation":{"$ref":"#/components/schemas/ValidationRule"}},"required":["label","value"],"title":"BatchItemsFreeTextWithUnitInstructionUnitOptionsItems"},"BatchItemsFreeTextWithUnitInstructionUnitPosition":{"type":"string","enum":["prefix","suffix"],"description":"Position of the unit selector relative to the text input.","title":"BatchItemsFreeTextWithUnitInstructionUnitPosition"},"BatchItemsMultipleChoiceInstructionType":{"type":"string","enum":["multiple_choice"],"title":"BatchItemsMultipleChoiceInstructionType"},"BatchItemsMultipleChoiceInstructionOptionsItemsValue":{"oneOf":[{"type":"string"},{"type":"number","format":"double"},{"type":"boolean"}],"title":"BatchItemsMultipleChoiceInstructionOptionsItemsValue"},"BatchItemsMultipleChoiceInstructionOptionsItems":{"type":"object","properties":{"label":{"type":"string"},"value":{"$ref":"#/components/schemas/BatchItemsMultipleChoiceInstructionOptionsItemsValue"},"exclusive":{"type":"boolean","description":"When true, selecting this option deselects all other options. Useful for \"None of the above\" style options. Not allowed when `answer_limit` is 1, and at least one non-exclusive option must remain if any option is exclusive."}},"required":["label","value"],"title":"BatchItemsMultipleChoiceInstructionOptionsItems"},"BatchItemsMultipleChoiceWithFreeTextInstructionType":{"type":"string","enum":["multiple_choice_with_free_text"],"title":"BatchItemsMultipleChoiceWithFreeTextInstructionType"},"BatchItemsMultipleChoiceWithFreeTextInstructionOptionsItemsValue":{"oneOf":[{"type":"string"},{"type":"number","format":"double"},{"type":"boolean"}],"title":"BatchItemsMultipleChoiceWithFreeTextInstructionOptionsItemsValue"},"BatchItemsMultipleChoiceWithFreeTextInstructionOptionsItems":{"type":"object","properties":{"label":{"type":"string"},"value":{"$ref":"#/components/schemas/BatchItemsMultipleChoiceWithFreeTextInstructionOptionsItemsValue"},"heading":{"type":"string","description":"Required. Section heading that groups this option."},"exclusive":{"type":"boolean","description":"When true, selecting this option deselects all other options."}},"required":["label","value","heading"],"title":"BatchItemsMultipleChoiceWithFreeTextInstructionOptionsItems"},"BatchItemsFileUploadInstructionType":{"type":"string","enum":["file_upload"],"title":"BatchItemsFileUploadInstructionType"},"BatchItemsItem":{"oneOf":[{"type":"object","properties":{"type":{"$ref":"#/components/schemas/BatchItemsDatasetFieldRefType"},"field":{"type":"string","minLength":1,"description":"Name of the dataset schema field to reference."}},"required":["type","field"],"description":"References a field in the batch's attached dataset. At task time, the dataset value\nfor the current datapoint is rendered at this position. Only dataset schema fields of\ntype `text`, `image_url`, `audio_url`, or `video_url` are permitted, and the same field may not be referenced more\nthan once on the same page."},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/BatchItemsImageBlockType"},"id":{"type":"string","description":"Server-assigned identifier; present on responses. Include to preserve an existing item when updating."},"url":{"type":"string","format":"uri","pattern":"^https://","description":"HTTPS URL of the image. Non-HTTPS URLs are rejected."},"alt_text":{"type":"string","minLength":1,"description":"Alt text shown to screen readers. Required for accessibility."},"caption":{"type":"string","description":"Optional caption displayed below the image."}},"required":["type","url","alt_text"],"description":"An image content block rendered inline within the batch layout."},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/BatchItemsRichTextBlockType"},"id":{"type":"string","description":"Server-assigned identifier; present on responses. Include to preserve an existing item when updating."},"content":{"type":"string","minLength":1,"description":"Rich text content. Interpreted as HTML by default, or as Markdown when `content_format` is set to `markdown` (converted to HTML server-side before storage)."},"content_format":{"$ref":"#/components/schemas/BatchItemsRichTextBlockContentFormat","default":"html","description":"Format of the `content` field. Defaults to `html`."}},"required":["type","content"],"description":"A rich-text content block rendered inline within the batch layout."},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/BatchItemsFreeTextInstructionType"},"id":{"type":"string","description":"Server-assigned identifier; present on responses. Include to preserve an existing item when updating."},"description":{"type":"string","description":"The question or prompt displayed to participants."},"helper_text":{"type":"string","description":"Additional guidance text displayed below the question."},"placeholder_text_input":{"type":"string","description":"Placeholder text displayed in the input field."},"validation":{"$ref":"#/components/schemas/ValidationRule","description":"Optional validation constraints for the input value."}},"required":["type","description"],"description":"Free-text input instruction."},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/BatchItemsFreeTextWithUnitInstructionType"},"id":{"type":"string","description":"Server-assigned identifier; present on responses. Include to preserve an existing item when updating."},"description":{"type":"string","description":"The question or prompt displayed to participants."},"helper_text":{"type":"string"},"placeholder_text_input":{"type":"string"},"unit_options":{"type":"array","items":{"$ref":"#/components/schemas/BatchItemsFreeTextWithUnitInstructionUnitOptionsItems"},"description":"Available units the participant can select from."},"default_unit":{"type":"string","description":"Default selected unit. Must match the `value` of one of the entries in `unit_options`."},"unit_position":{"$ref":"#/components/schemas/BatchItemsFreeTextWithUnitInstructionUnitPosition","description":"Position of the unit selector relative to the text input."}},"required":["type","description","unit_options","unit_position"],"description":"Free-text input instruction paired with a unit selector."},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/BatchItemsMultipleChoiceInstructionType"},"id":{"type":"string","description":"Server-assigned identifier; present on responses. Include to preserve an existing item when updating."},"description":{"type":"string","description":"The question or prompt displayed to participants."},"helper_text":{"type":"string"},"placeholder_text_input":{"type":"string"},"answer_limit":{"type":"integer","minimum":-1,"description":"Number of options that can be selected. Use `1` for single-select, `-1` for unlimited, or any number up to the total options."},"disable_dropdown":{"type":"boolean","default":false,"description":"When true, always renders checkbox/radio elements instead of a dropdown select."},"options":{"type":"array","items":{"$ref":"#/components/schemas/BatchItemsMultipleChoiceInstructionOptionsItems"}}},"required":["type","description","answer_limit","options"],"description":"Multiple-choice instruction."},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/BatchItemsMultipleChoiceWithFreeTextInstructionType"},"id":{"type":"string","description":"Server-assigned identifier; present on responses. Include to preserve an existing item when updating."},"description":{"type":"string"},"helper_text":{"type":"string"},"placeholder_text_input":{"type":"string"},"answer_limit":{"type":"integer","minimum":-1},"disable_dropdown":{"type":"boolean","default":false},"options":{"type":"array","items":{"$ref":"#/components/schemas/BatchItemsMultipleChoiceWithFreeTextInstructionOptionsItems"}}},"required":["type","description","answer_limit","options"],"description":"Multiple-choice instruction with an additional free-text input per selected option."},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/BatchItemsFileUploadInstructionType"},"id":{"type":"string","description":"Server-assigned identifier; present on responses. Include to preserve an existing item when updating."},"description":{"type":"string"},"helper_text":{"type":"string"},"accepted_file_types":{"type":"array","items":{"type":"string","pattern":"^\\."},"description":"File extensions to accept (each must start with a dot, e.g. `.jpg`). Defaults to `[\".jpg\", \".jpeg\", \".png\", \".heic\", \".heif\"]`."},"max_file_size_mb":{"type":"number","format":"double","exclusiveMinimum":0,"description":"Maximum size in megabytes per file. Defaults to 25."},"min_file_count":{"type":"integer","minimum":1,"description":"Minimum number of files required. Defaults to 1."},"max_file_count":{"type":"integer","minimum":1,"description":"Maximum number of files allowed. Defaults to 10. Must be greater than or equal to `min_file_count`."}},"required":["type","description"],"description":"File upload instruction."}],"discriminator":{"propertyName":"type"},"description":"A single item within a column. One of: a dataset field reference (`dataset_field`),\na content block (`image`, `rich_text`), or an instruction (`free_text`,\n`free_text_with_unit`, `multiple_choice`, `multiple_choice_with_free_text`, `file_upload`).\nDiscriminated on `type`.","title":"BatchItemsItem"},"BatchItemsColumn":{"type":"object","properties":{"id":{"type":"string","description":"Server-assigned identifier; present on responses. Include to preserve an existing column when updating."},"items":{"type":"array","items":{"$ref":"#/components/schemas/BatchItemsItem"}}},"required":["items"],"description":"A column within a row. Contains one or more items rendered top-to-bottom.","title":"BatchItemsColumn"},"BatchItemsRow":{"type":"object","properties":{"id":{"type":"string","description":"Server-assigned identifier; present on responses. Include to preserve an existing row when updating."},"columns":{"type":"array","items":{"$ref":"#/components/schemas/BatchItemsColumn"}}},"required":["columns"],"description":"A row within a page. Renders 1 or 2 columns side-by-side.","title":"BatchItemsRow"},"BatchItemsPage":{"type":"object","properties":{"id":{"type":"string","description":"Server-assigned identifier; present on responses. Include to preserve an existing page when updating."},"display_position":{"$ref":"#/components/schemas/BatchItemsPageDisplayPosition","description":"Renders the page once — before (\"intro\") or after (\"outro\") the repeating body —\ninstead of once per datapoint. Omit (or set \"body\") for the default repeating\nbehaviour. Pages with display_position \"intro\" or \"outro\" may only contain\nrich_text/image content blocks, not instructions or dataset_field refs."},"rows":{"type":"array","items":{"$ref":"#/components/schemas/BatchItemsRow"}}},"required":["rows"],"description":"A single page of a batch's inline layout. Each page is rendered as one screen to participants\nand contains an ordered list of rows. On responses, includes a server-assigned `id`; omit\n`id` on create to add a new page.","title":"BatchItemsPage"},"AITaskBuilderBatch":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time","description":"An ISO-8601 formatted string representing the batch creation time, in UTC."},"created_by":{"type":"string","description":"User ID of the Prolific user that created the resource."},"datasets":{"type":"array","items":{"$ref":"#/components/schemas/AiTaskBuilderBatchDatasetsItems"}},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/AiTaskBuilderBatchStatus"},"total_task_count":{"type":"integer","minimum":0},"total_instruction_count":{"type":"integer","minimum":0},"workspace_id":{"type":"string"},"schema_version":{"type":"integer"},"task_details":{"$ref":"#/components/schemas/AiTaskBuilderBatchTaskDetails"},"total_task_groups":{"type":"integer","minimum":0},"batch_items":{"type":["array","null"],"items":{"$ref":"#/components/schemas/BatchItemsPage"},"description":"The persisted `batch_items` layout, populated when the batch was created with\n`batch_items`. `null` for legacy batches authored via the standalone instructions\nendpoint. Every page, row, column, and item carries a server-assigned `id`."},"auto_sync_enabled":{"type":"boolean","description":"When `true`, datapoints appended to the batch's attached dataset automatically trigger a\nsync that materialises tasks for them. Optional — absent on batches that have never\nenabled auto-sync. Absent or `false` mean auto-sync is off."}},"required":["id","created_at","created_by","datasets","name","status","total_task_count","total_instruction_count","workspace_id","schema_version","task_details","total_task_groups"],"title":"AITaskBuilderBatch"},"ApiV1DataCollectionBatchesGetResponsesContentApplicationJsonSchemaMeta":{"type":"object","properties":{"count":{"type":"integer","description":"Total number of batches"}},"title":"ApiV1DataCollectionBatchesGetResponsesContentApplicationJsonSchemaMeta"},"AI Task Builder_GetTaskBuilderBatches_Response_200":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/AITaskBuilderBatch"}},"meta":{"$ref":"#/components/schemas/ApiV1DataCollectionBatchesGetResponsesContentApplicationJsonSchemaMeta"}},"title":"AI Task Builder_GetTaskBuilderBatches_Response_200"},"ApiV1DataCollectionBatchesPostRequestBodyContentApplicationJsonSchemaTaskDetails":{"type":"object","properties":{"task_name":{"type":"string","description":"The title displayed to participants"},"task_introduction":{"type":"string","description":"HTML formatted introduction shown at the start of the task"},"task_steps":{"type":"string","description":"HTML formatted step-by-step instructions"}},"required":["task_name","task_introduction","task_steps"],"description":"Task metadata displayed to participants","title":"ApiV1DataCollectionBatchesPostRequestBodyContentApplicationJsonSchemaTaskDetails"},"AiTaskBuilderBatchCreateDatasetsItems":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"total_datapoint_count":{"type":"integer","minimum":0}},"required":["id","total_datapoint_count"],"title":"AiTaskBuilderBatchCreateDatasetsItems"},"AiTaskBuilderBatchCreateStatus":{"type":"string","enum":["UNINITIALISED","PROCESSING","READY","ERROR"],"title":"AiTaskBuilderBatchCreateStatus"},"AiTaskBuilderBatchCreateTaskDetails":{"type":"object","properties":{"task_name":{"type":"string"},"task_introduction":{"type":"string","description":"HTML formatted task introduction"},"task_steps":{"type":"string","description":"HTML formatted task steps"}},"required":["task_name","task_introduction","task_steps"],"title":"AiTaskBuilderBatchCreateTaskDetails"},"AITaskBuilderBatchCreate":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time","description":"An ISO-8601 formatted string representing the batch creation time, in UTC."},"created_by":{"type":"string","description":"User ID of the Prolific user that created the resource."},"datasets":{"type":"array","items":{"$ref":"#/components/schemas/AiTaskBuilderBatchCreateDatasetsItems"}},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/AiTaskBuilderBatchCreateStatus"},"total_task_count":{"type":"integer","minimum":0},"total_instruction_count":{"type":"integer","minimum":0},"workspace_id":{"type":"string"},"task_details":{"$ref":"#/components/schemas/AiTaskBuilderBatchCreateTaskDetails"},"batch_items":{"type":["array","null"],"items":{"$ref":"#/components/schemas/BatchItemsPage"},"description":"The persisted `batch_items` layout, returned only when `batch_items` was supplied on\ncreate. Every page, row, column, and item is returned with a server-assigned `id`."}},"required":["id","created_at","created_by","datasets","name","status","total_task_count","total_instruction_count","workspace_id","task_details"],"title":"AITaskBuilderBatchCreate"},"BatchItemsValidationErrorType":{"type":"string","enum":["INVALID_BATCH_ITEMS"],"title":"BatchItemsValidationErrorType"},"BatchItemsValidationErrorIssuesItems":{"type":"object","properties":{"page":{"type":"integer","minimum":0,"description":"Zero-based index of the page containing the invalid item."},"row":{"type":"integer","minimum":0,"description":"Zero-based index of the row within the page."},"column":{"type":"integer","minimum":0,"description":"Zero-based index of the column within the row."},"item":{"type":"integer","minimum":0,"description":"Zero-based index of the item within the column."},"type":{"type":"string","description":"The item `type` that failed validation (e.g. `dataset_field`, `multiple_choice`, `file_upload`)."},"field":{"type":"string","description":"Dataset field name. Present only for `dataset_field` validation issues."},"message":{"type":"string","description":"Human-readable validation error message."}},"required":["page","row","column","item","type","message"],"title":"BatchItemsValidationErrorIssuesItems"},"BatchItemsValidationError":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/BatchItemsValidationErrorType"},"message":{"type":"string"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/BatchItemsValidationErrorIssuesItems"}}},"required":["type","message","issues"],"description":"`422 Unprocessable Entity` payload returned when `batch_items` fails server-side\nvalidation on create or update. Each entry in `issues` pinpoints the offending item\nusing zero-based `page` / `row` / `column` / `item` indices, and describes what was\nwrong (e.g. `dataset_field` used without a v4 dataset and populated schema attached,\nunknown dataset field, the same dataset field referenced more than once on a page,\n`answer_limit` exceeds options, `default_unit` does not match `unit_options`,\n`min_file_count` greater than `max_file_count`).","title":"BatchItemsValidationError"},"ApiV1DataCollectionBatchesBatchIdPatchRequestBodyContentApplicationJsonSchemaTaskDetails":{"type":"object","properties":{"task_name":{"type":"string"},"task_introduction":{"type":"string","description":"HTML formatted task introduction"},"task_steps":{"type":"string","description":"HTML formatted task steps"}},"required":["task_name","task_introduction","task_steps"],"title":"ApiV1DataCollectionBatchesBatchIdPatchRequestBodyContentApplicationJsonSchemaTaskDetails"},"UpdateTaskBuilderBatchRequestBadRequestError":{"type":"object","properties":{"message":{"type":"string"}},"title":"UpdateTaskBuilderBatchRequestBadRequestError"},"SyncJobStatus":{"type":"string","enum":["queued","processing","complete","failed"],"description":"Current status of the sync job.","title":"SyncJobStatus"},"SyncJob":{"type":"object","properties":{"batch_id":{"type":"string","format":"uuid","description":"The batch this sync job belongs to."},"dataset_id":{"type":"string","format":"uuid","description":"The dataset whose appended datapoints are being synced."},"sync_id":{"type":"string","format":"uuid","description":"The unique identifier of the sync job."},"created_at":{"type":"string","format":"date-time","description":"When the sync job was created (ISO 8601, UTC)."},"updated_at":{"type":"string","format":"date-time","description":"When the sync job was last updated (ISO 8601, UTC)."},"status":{"$ref":"#/components/schemas/SyncJobStatus","description":"Current status of the sync job."},"tasks_created":{"type":"integer","minimum":0,"description":"Number of tasks created this sync. Present when status is `complete`."},"datapoints_processed":{"type":"integer","minimum":0,"description":"Number of datapoints processed this sync. Present when status is `complete`."},"groups_created":{"type":"integer","minimum":0,"description":"Number of new task groups created this sync. Present when status is `complete`."},"groups_expanded":{"type":"integer","minimum":0,"description":"Number of existing task groups grown this sync. Non-zero only for predetermined-grouping\nbatches; always `0` for tasks-per-group batches. Present when status is `complete`."},"reason":{"type":"string","description":"Human-readable reason for failure. Present when status is `failed`."}},"required":["batch_id","dataset_id","sync_id","created_at","updated_at","status"],"description":"Tracks the asynchronous materialisation of tasks for datapoints appended to a batch's dataset\nsince setup or the last sync. Created by `POST /batches/{batch_id}/sync`; poll\n`GET /batches/{batch_id}/syncs/{sync_id}` until a terminal status (`complete` or `failed`).\n\nThe shape depends on `status`: the fields below marked as terminal-only are present only for\nthe corresponding status.","title":"SyncJob"},"SyncTaskBuilderBatchRequestBadRequestError":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable reason the batch cannot be synced."},"detail":{"type":"string","description":"Additional context, when available."}},"title":"SyncTaskBuilderBatchRequestBadRequestError"},"ApiV1DataCollectionBatchesBatchIdStatusGetResponsesContentApplicationJsonSchemaStatus":{"type":"string","enum":["UNINITIALISED","PROCESSING","READY","ERROR"],"description":"The status of the Batch - one of 'UNINITIALISED', 'PROCESSING', 'READY', 'ERROR'","title":"ApiV1DataCollectionBatchesBatchIdStatusGetResponsesContentApplicationJsonSchemaStatus"},"AI Task Builder_GetTaskBuilderBatchStatus_Response_200":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/ApiV1DataCollectionBatchesBatchIdStatusGetResponsesContentApplicationJsonSchemaStatus","description":"The status of the Batch - one of 'UNINITIALISED', 'PROCESSING', 'READY', 'ERROR'"}},"title":"AI Task Builder_GetTaskBuilderBatchStatus_Response_200"},"AI Task Builder_SetupTaskBuilderBatch_Response_202":{"type":"object","properties":{},"description":"Empty response body","title":"AI Task Builder_SetupTaskBuilderBatch_Response_202"},"AiTaskBuilderTaskResponseResponseType":{"type":"string","enum":["multiple_choice","free_text","free_text_with_unit","multiple_choice_with_free_text","file_upload"],"title":"AiTaskBuilderTaskResponseResponseType"},"AiTaskBuilderTaskResponseResponseAnswerItemsValue":{"oneOf":[{"type":"string"},{"type":"number","format":"double"},{"type":"boolean"}],"title":"AiTaskBuilderTaskResponseResponseAnswerItemsValue"},"AiTaskBuilderTaskResponseResponseAnswerItems":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/AiTaskBuilderTaskResponseResponseAnswerItemsValue"}},"description":"The participant's answer value","title":"AiTaskBuilderTaskResponseResponseAnswerItems"},"AiTaskBuilderTaskResponseResponse":{"type":"object","properties":{"instruction_id":{"type":"string"},"type":{"$ref":"#/components/schemas/AiTaskBuilderTaskResponseResponseType"},"answer":{"type":"array","items":{"$ref":"#/components/schemas/AiTaskBuilderTaskResponseResponseAnswerItems"}}},"required":["instruction_id","type","answer"],"title":"AiTaskBuilderTaskResponseResponse"},"AITaskBuilderTaskResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"batch_id":{"type":"string"},"participant_id":{"type":"string"},"submission_id":{"type":"string","description":"The Prolific submission ID"},"correlation_id":{"type":"string","description":"Correlation ID for tracking"},"response":{"$ref":"#/components/schemas/AiTaskBuilderTaskResponseResponse"},"task_id":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"description":"Any type"}},"schema_version":{"type":"integer"},"no_submission":{"type":"boolean"}},"required":["id","created_at","batch_id","participant_id","response","task_id"],"title":"AITaskBuilderTaskResponse"},"ApiV1DataCollectionBatchesBatchIdResponsesGetResponsesContentApplicationJsonSchemaMeta":{"type":"object","properties":{"count":{"type":"integer","description":"Total number of responses"}},"title":"ApiV1DataCollectionBatchesBatchIdResponsesGetResponsesContentApplicationJsonSchemaMeta"},"AI Task Builder_GetTaskBuilderBatchTaskResponses_Response_200":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/AITaskBuilderTaskResponse"}},"meta":{"$ref":"#/components/schemas/ApiV1DataCollectionBatchesBatchIdResponsesGetResponsesContentApplicationJsonSchemaMeta"}},"title":"AI Task Builder_GetTaskBuilderBatchTaskResponses_Response_200"},"ApiV1DataCollectionBatchesBatchIdReportGetResponsesContentApplicationJsonSchemaHttpMethod":{"type":"string","enum":["GET"],"description":"HTTP method to use with the presigned URL","title":"ApiV1DataCollectionBatchesBatchIdReportGetResponsesContentApplicationJsonSchemaHttpMethod"},"AI Task Builder_GetTaskBuilderBatchReport_Response_200":{"type":"object","properties":{"url":{"type":"string","description":"Presigned URL to download the CSV report"},"expires_at":{"type":"string","format":"date-time","description":"When the presigned URL expires"},"http_method":{"$ref":"#/components/schemas/ApiV1DataCollectionBatchesBatchIdReportGetResponsesContentApplicationJsonSchemaHttpMethod","description":"HTTP method to use with the presigned URL"}},"title":"AI Task Builder_GetTaskBuilderBatchReport_Response_200"},"BatchExportCompleteStatus":{"type":"string","enum":["complete"],"title":"BatchExportCompleteStatus"},"BatchExportComplete":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/BatchExportCompleteStatus"},"url":{"type":"string","format":"uri","description":"Presigned HTTPS URL for downloading the ZIP archive. Valid for 1 hour. Re-poll to get a refreshed URL if expired."},"expires_at":{"type":"string","format":"date-time","description":"ISO 8601 timestamp indicating when the presigned URL expires."}},"required":["status","url","expires_at"],"description":"An export job that has completed successfully. The ZIP archive is ready to download.","title":"BatchExportComplete"},"BatchExportStatusOneOf0Status":{"type":"string","enum":["generating"],"title":"BatchExportStatusOneOf0Status"},"BatchExportStatus0":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/BatchExportStatusOneOf0Status"},"export_id":{"type":"string","format":"uuid","description":"The export job ID. Use this with `GET /batches/{batch_id}/export/{export_id}` to poll for status."}},"required":["status","export_id"],"description":"An export job that has been enqueued and is currently being generated.","title":"BatchExportStatus0"},"BatchExportStatusOneOf1Status":{"type":"string","enum":["complete"],"title":"BatchExportStatusOneOf1Status"},"BatchExportStatus1":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/BatchExportStatusOneOf1Status"},"url":{"type":"string","format":"uri","description":"Presigned HTTPS URL for downloading the ZIP archive. Valid for 1 hour. Re-poll to get a refreshed URL if expired."},"expires_at":{"type":"string","format":"date-time","description":"ISO 8601 timestamp indicating when the presigned URL expires."}},"required":["status","url","expires_at"],"description":"An export job that has completed successfully. The ZIP archive is ready to download.","title":"BatchExportStatus1"},"BatchExportStatusOneOf2Status":{"type":"string","enum":["failed"],"title":"BatchExportStatusOneOf2Status"},"BatchExportStatus2":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/BatchExportStatusOneOf2Status"}},"required":["status"],"description":"An export job that failed to generate, or whose archive has since been deleted. Re-send `POST /batches/{batch_id}/export` to retry.","title":"BatchExportStatus2"},"BatchExportStatus":{"oneOf":[{"$ref":"#/components/schemas/BatchExportStatus0"},{"$ref":"#/components/schemas/BatchExportStatus1"},{"$ref":"#/components/schemas/BatchExportStatus2"}],"description":"The current status of a batch export job.","title":"BatchExportStatus"},"DatasetSchemaFieldType":{"type":"string","enum":["text","image_url","audio_url","video_url","metadata","task_group_id"],"description":"Field type:\n- `text` — a text value shown to participants. Can be referenced by `dataset_field` items in `batch_items`.\n- `image_url` — a URL pointing to an image shown to participants. Can be referenced by `dataset_field` items in `batch_items`.\n- `audio_url` — a URL pointing to an audio file shown to participants in Prolific's audio player. Audio must be externally hosted using a direct-file HTTPS URL. Supported formats are `.mp3`, `.wav`, `.aac`, and `.m4a`.\n- `video_url` — a URL pointing to a video file shown to participants in Prolific's video player. Video must be externally hosted using a direct-file HTTPS URL. Supported formats are `.mp4`, `.mov`, `.webm`, and `.m4v`.\n- `metadata` — an internal value included in exports but not shown to participants (equivalent to the `META_` prefix in V3 CSV datasets).\n- `task_group_id` — groups datapoints into task groups. Rows with the same `task_group_id` value are assigned to the same participant. Equivalent to `META_TASK_GROUP_ID` in V3 CSV datasets. At most one field per schema may have this type.","title":"DatasetSchemaFieldType"},"DatasetSchemaField":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/DatasetSchemaFieldType","description":"Field type:\n- `text` — a text value shown to participants. Can be referenced by `dataset_field` items in `batch_items`.\n- `image_url` — a URL pointing to an image shown to participants. Can be referenced by `dataset_field` items in `batch_items`.\n- `audio_url` — a URL pointing to an audio file shown to participants in Prolific's audio player. Audio must be externally hosted using a direct-file HTTPS URL. Supported formats are `.mp3`, `.wav`, `.aac`, and `.m4a`.\n- `video_url` — a URL pointing to a video file shown to participants in Prolific's video player. Video must be externally hosted using a direct-file HTTPS URL. Supported formats are `.mp4`, `.mov`, `.webm`, and `.m4v`.\n- `metadata` — an internal value included in exports but not shown to participants (equivalent to the `META_` prefix in V3 CSV datasets).\n- `task_group_id` — groups datapoints into task groups. Rows with the same `task_group_id` value are assigned to the same participant. Equivalent to `META_TASK_GROUP_ID` in V3 CSV datasets. At most one field per schema may have this type."},"label":{"type":"string","maxLength":255,"description":"Optional human-readable label for the field, used in the participant interface."}},"required":["type"],"description":"Descriptor for a single field in a dataset schema.","title":"DatasetSchemaField"},"DatasetSchema":{"type":"object","properties":{"strict":{"type":"boolean","description":"When `true`, records that are missing any field defined in the schema are rejected during import. When `false`, missing fields are allowed and treated as absent."},"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DatasetSchemaField"},"description":"A map of field key to field descriptor. The key is used to reference the field in `batch_items` (`dataset_field` items) and in JSONL records."}},"required":["strict","fields"],"description":"A researcher-defined schema that specifies the fields in a V4 dataset. Each field has a type that determines how it is rendered to participants and how it can be referenced in `batch_items`.\n\nConstraints:\n- Maximum 200 fields per schema.\n- Field keys: 1–128 characters.\n- Field labels: maximum 255 characters.","title":"DatasetSchema"},"AiTaskBuilderDatasetSchemaVersion":{"type":"string","enum":["3","4"],"description":"Internal dataset version. 3 = legacy CSV/ZIP; 4 = structured schema with JSONL/CSV import tracking.","title":"AiTaskBuilderDatasetSchemaVersion"},"AiTaskBuilderDatasetStatus":{"type":"string","enum":["ERROR","PROCESSING","READY","UNINITIALISED"],"description":"Processing status. **V3 datasets only.** V4 datasets track status per import job via `imports`.","title":"AiTaskBuilderDatasetStatus"},"DatasetImportJobType":{"type":"string","enum":["file_upload"],"description":"The type of import. Currently always `file_upload`.","title":"DatasetImportJobType"},"DatasetImportJobStatus":{"type":"string","enum":["uninitialised","queued","processing","complete","partial","failed","pending_schema"],"description":"Current status of the import job.","title":"DatasetImportJobStatus"},"ImportJobError":{"type":"object","properties":{"record_index":{"type":["integer","null"],"minimum":0,"description":"Zero-based index of the rejected record in the uploaded file."},"field":{"type":["string","null"],"description":"The schema field key that caused the rejection, or `null` if no specific field is implicated.\nThe special value `_raw` indicates a whole-record parse failure (e.g. malformed JSON) rather than a field-level error."},"reason":{"type":["string","null"],"description":"Human-readable description of why the record was rejected."}},"description":"A record-level validation error from a partial import.","title":"ImportJobError"},"DatasetImportJob":{"type":"object","properties":{"dataset_id":{"type":"string","format":"uuid","description":"The dataset this import job belongs to."},"import_id":{"type":"string","format":"uuid","description":"The unique identifier of the import job."},"type":{"$ref":"#/components/schemas/DatasetImportJobType","description":"The type of import. Currently always `file_upload`."},"filename":{"type":["string","null"],"description":"The original filename supplied when the upload URL was requested."},"created_at":{"type":"string","format":"date-time","description":"When the import job was created (ISO 8601, UTC)."},"updated_at":{"type":"string","format":"date-time","description":"When the import job was last updated (ISO 8601, UTC)."},"status":{"$ref":"#/components/schemas/DatasetImportJobStatus","description":"Current status of the import job."},"accepted_count":{"type":"integer","minimum":0,"description":"Number of records successfully ingested. Present when status is `complete` or `partial`."},"rejected_count":{"type":"integer","minimum":0,"description":"Number of records rejected. Present when status is `partial`."},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ImportJobError"},"description":"Record-level validation errors. Present when status is `partial`."},"reason":{"type":"string","description":"Human-readable reason for failure. Present when status is `failed`."}},"required":["dataset_id","import_id","type","created_at","updated_at","status"],"description":"Tracks the lifecycle of a single file upload to a V4 dataset.\n\nAn import job is created when `GET /datasets/{dataset_id}/upload-url/{filename}` is called. It transitions through the following statuses:\n\n| Status | Meaning |\n|---|---|\n| `uninitialised` | Import job created; file not yet uploaded to S3 |\n| `queued` | File uploaded; queued for extraction |\n| `processing` | Extraction in progress |\n| `complete` | All records accepted |\n| `partial` | Some records accepted, some rejected — see `errors` |\n| `failed` | Extraction failed entirely — see `reason` |\n| `pending_schema` | Dataset has no schema; upload paused until schema is set |\n\nPoll `GET /datasets/{dataset_id}/imports/{import_id}` until a terminal status is reached (`complete`, `partial`, `failed`, or `pending_schema`).","title":"DatasetImportJob"},"AITaskBuilderDataset":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":"string"},"workspace_id":{"type":"string"},"total_datapoint_count":{"type":"integer","minimum":0},"schema_version":{"$ref":"#/components/schemas/AiTaskBuilderDatasetSchemaVersion","description":"Internal dataset version. 3 = legacy CSV/ZIP; 4 = structured schema with JSONL/CSV import tracking."},"status":{"$ref":"#/components/schemas/AiTaskBuilderDatasetStatus","description":"Processing status. **V3 datasets only.** V4 datasets track status per import job via `imports`."},"filename":{"type":["string","null"],"description":"Filename of the uploaded data file. **V3 datasets only.**"},"has_predetermined_grouping_id":{"type":["boolean","null"],"description":"Whether the dataset contains a `META_TASK_GROUP_ID` column. **V3 datasets only.**"},"schema":{"oneOf":[{"$ref":"#/components/schemas/DatasetSchema"},{"type":"null"}],"description":"The researcher-defined field schema for this dataset. **V4 datasets only.**\n`null` if no schema has been set yet."},"imports":{"type":["array","null"],"items":{"$ref":"#/components/schemas/DatasetImportJob"},"description":"Import jobs for this dataset, most recent first. **V4 datasets only.** `null` for V3 datasets."}},"required":["id","name","created_at","created_by","workspace_id","total_datapoint_count","schema_version"],"description":"An AI Task Builder dataset. The shape of the response varies by `schema_version`:\n\n- **V3 datasets** include `status`, `filename`, and `has_predetermined_grouping_id`.\n- **V4 datasets** include `schema` (the researcher-defined field schema, or `null` if not yet set) and `imports` (the list of import jobs for this dataset). V4 datasets do not include `status` or `filename`.","title":"AITaskBuilderDataset"},"ApiV1DataCollectionDatasetsDatasetIdPatchResponsesContentApplicationJsonSchemaSchemaVersion":{"type":"string","enum":["3","4"],"description":"Internal dataset version. 3 = legacy CSV/ZIP; 4 = structured schema with JSONL/CSV import tracking.","title":"ApiV1DataCollectionDatasetsDatasetIdPatchResponsesContentApplicationJsonSchemaSchemaVersion"},"ApiV1DataCollectionDatasetsDatasetIdPatchResponsesContentApplicationJsonSchemaStatus":{"type":"string","enum":["ERROR","PROCESSING","READY","UNINITIALISED"],"description":"Processing status. **V3 datasets only.** V4 datasets track status per import job via `imports`.","title":"ApiV1DataCollectionDatasetsDatasetIdPatchResponsesContentApplicationJsonSchemaStatus"},"AI Task Builder_UpdateTaskBuilderDataset_Response_200":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":"string"},"workspace_id":{"type":"string"},"total_datapoint_count":{"type":"integer","minimum":0},"schema_version":{"$ref":"#/components/schemas/ApiV1DataCollectionDatasetsDatasetIdPatchResponsesContentApplicationJsonSchemaSchemaVersion","description":"Internal dataset version. 3 = legacy CSV/ZIP; 4 = structured schema with JSONL/CSV import tracking."},"status":{"$ref":"#/components/schemas/ApiV1DataCollectionDatasetsDatasetIdPatchResponsesContentApplicationJsonSchemaStatus","description":"Processing status. **V3 datasets only.** V4 datasets track status per import job via `imports`."},"filename":{"type":["string","null"],"description":"Filename of the uploaded data file. **V3 datasets only.**"},"has_predetermined_grouping_id":{"type":["boolean","null"],"description":"Whether the dataset contains a `META_TASK_GROUP_ID` column. **V3 datasets only.**"},"schema":{"oneOf":[{"$ref":"#/components/schemas/DatasetSchema"},{"type":"null"}],"description":"The researcher-defined field schema for this dataset. **V4 datasets only.**\n`null` if no schema has been set yet."},"imports":{"type":["array","null"],"items":{"$ref":"#/components/schemas/DatasetImportJob"},"description":"Import jobs for this dataset, most recent first. **V4 datasets only.** `null` for V3 datasets."},"migration_job_id":{"type":"string","format":"uuid","description":"The schema migration job started by this update. Present only when the\ndataset already had a schema (i.e. the schema was changed, not set for the\nfirst time). Use with `GET /datasets/{dataset_id}/schema-migrations/{job_id}`."}},"required":["id","name","created_at","created_by","workspace_id","total_datapoint_count","schema_version"],"description":"An AI Task Builder dataset. The shape of the response varies by `schema_version`:\n\n- **V3 datasets** include `status`, `filename`, and `has_predetermined_grouping_id`.\n- **V4 datasets** include `schema` (the researcher-defined field schema, or `null` if not yet set) and `imports` (the list of import jobs for this dataset). V4 datasets do not include `status` or `filename`.","title":"AI Task Builder_UpdateTaskBuilderDataset_Response_200"},"ApiV1DataCollectionDatasetsDatasetIdUploadUrlFilenameGetResponsesContentApplicationJsonSchemaHttpMethod":{"type":"string","enum":["PUT"],"description":"HTTP method to use with the presigned URL.","title":"ApiV1DataCollectionDatasetsDatasetIdUploadUrlFilenameGetResponsesContentApplicationJsonSchemaHttpMethod"},"AI Task Builder_getDatasetUploadUrl_Response_201":{"type":"object","properties":{"dataset_id":{"type":"string","format":"uuid","description":"The ID of the dataset the upload URL was requested for."},"upload_url":{"type":"string","description":"Presigned S3 URL. Make a PUT request to this URL with your file as the body."},"http_method":{"$ref":"#/components/schemas/ApiV1DataCollectionDatasetsDatasetIdUploadUrlFilenameGetResponsesContentApplicationJsonSchemaHttpMethod","description":"HTTP method to use with the presigned URL."},"content_type":{"type":"string","description":"The `Content-Type` header value to use when making the S3 PUT request.\nUse this value exactly — e.g. `application/x-ndjson` for JSONL files."},"expires_at":{"type":"string","format":"date-time","description":"When the presigned URL expires (ISO 8601, UTC). The URL cannot be used after this time."},"file_key":{"type":"string","description":"The S3 object key for the uploaded file. Provided for reference only."},"import_id":{"type":"string","format":"uuid","description":"Import job ID. **V4 datasets only.** Use with `GET /datasets/{dataset_id}/imports/{import_id}` to poll for upload and processing status."}},"required":["dataset_id","upload_url","http_method","content_type","expires_at"],"title":"AI Task Builder_getDatasetUploadUrl_Response_201"},"DatasetAppendError":{"type":"object","properties":{"record_index":{"type":"integer","minimum":0,"description":"One-based index of the rejected non-blank JSONL record in the append request body."},"field":{"type":"string","description":"The schema field key that caused the rejection. The special value `_raw` indicates a\nwhole-record parse failure (for example malformed JSON) rather than a field-level error."},"reason":{"type":"string","description":"Human-readable description of why the record was rejected."}},"required":["record_index","field","reason"],"description":"A record-level validation error from a synchronous JSONL append request.","title":"DatasetAppendError"},"DatasetAppendResult":{"type":"object","properties":{"accepted":{"type":"integer","minimum":0,"description":"Number of records that passed validation (newly written or idempotent duplicates)."},"rejected":{"type":"integer","minimum":0,"description":"Number of records rejected. Equal to the length of `errors`."},"errors":{"type":"array","items":{"$ref":"#/components/schemas/DatasetAppendError"},"description":"Record-level rejections. Empty when every record was accepted."}},"required":["accepted","rejected","errors"],"description":"Result of a synchronous append to a V4 dataset (`POST /datasets/{dataset_id}/datapoints`).\n`accepted` counts records that passed validation (newly written plus idempotent duplicates);\n`rejected` counts records that failed parsing or schema validation, each detailed in `errors`.","title":"DatasetAppendResult"},"SchemaMigrationJobStatus":{"type":"string","enum":["processing","complete","partial","failed"],"description":"Current status of the migration job.","title":"SchemaMigrationJobStatus"},"SchemaMigrationError":{"type":"object","properties":{"datapoint_id":{"type":"string","format":"uuid","description":"The datapoint whose field could not be re-normalised."},"field":{"type":"string","description":"The schema field key that was nulled."},"reason":{"type":"string","description":"Human-readable description of why the field was nulled."}},"required":["datapoint_id","field","reason"],"description":"A single record-level failure — a field that was invalid under the new schema and so was nulled.","title":"SchemaMigrationError"},"SchemaMigrationJob":{"type":"object","properties":{"dataset_id":{"type":"string","format":"uuid","description":"The dataset being migrated."},"job_id":{"type":"string","format":"uuid","description":"The unique identifier of the schema migration job."},"schema_version":{"type":"integer","minimum":1,"description":"The schema version this job reprocesses datapoints up to."},"created_at":{"type":"string","format":"date-time","description":"When the migration job was created (ISO 8601, UTC)."},"updated_at":{"type":"string","format":"date-time","description":"When the migration job was last updated (ISO 8601, UTC)."},"status":{"$ref":"#/components/schemas/SchemaMigrationJobStatus","description":"Current status of the migration job."},"reprocessed_count":{"type":"integer","minimum":0,"description":"Number of datapoints reprocessed. Present when status is `complete` or `partial`."},"failed_count":{"type":"integer","minimum":0,"description":"Number of datapoints with at least one field that could not be re-normalised. Present when status is `partial`."},"errors":{"type":"array","items":{"$ref":"#/components/schemas/SchemaMigrationError"},"description":"Record-level failures — fields nulled because they were invalid under the new schema. Present when status is `partial`."},"reason":{"type":"string","description":"Human-readable reason for failure. Present when status is `failed`."}},"required":["dataset_id","job_id","schema_version","created_at","updated_at","status"],"description":"Tracks the asynchronous re-normalisation of a V4 dataset's datapoints against a newer schema\nversion. Poll `GET /datasets/{dataset_id}/schema-migrations/{job_id}` until a terminal\nstatus (`complete`, `partial`, or `failed`).\n\nThe shape depends on `status`: the fields below marked as terminal-only are present only for\nthe corresponding status.","title":"SchemaMigrationJob"},"ApiV1DataCollectionDatasetsDatasetIdStatusGetResponsesContentApplicationJsonSchemaStatus":{"type":"string","enum":["UNINITIALISED","PROCESSING","READY","ERROR"],"description":"The status of the Dataset - one of 'UNINITIALISED', 'PROCESSING', 'READY', 'ERROR'","title":"ApiV1DataCollectionDatasetsDatasetIdStatusGetResponsesContentApplicationJsonSchemaStatus"},"AI Task Builder_GetTaskBuilderDatasetStatus_Response_200":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/ApiV1DataCollectionDatasetsDatasetIdStatusGetResponsesContentApplicationJsonSchemaStatus","description":"The status of the Dataset - one of 'UNINITIALISED', 'PROCESSING', 'READY', 'ERROR'"}},"title":"AI Task Builder_GetTaskBuilderDatasetStatus_Response_200"},"AiTaskBuilderMultipleChoiceInstructionType":{"type":"string","enum":["multiple_choice"],"title":"AiTaskBuilderMultipleChoiceInstructionType"},"AiTaskBuilderMultipleChoiceInstructionParentType":{"type":"string","enum":["batch","collection"],"title":"AiTaskBuilderMultipleChoiceInstructionParentType"},"AiTaskBuilderMultipleChoiceInstructionOptionsItemsValue":{"oneOf":[{"type":"string"},{"type":"number","format":"double"},{"type":"boolean"}],"description":"Value returned in responses","title":"AiTaskBuilderMultipleChoiceInstructionOptionsItemsValue"},"AiTaskBuilderMultipleChoiceInstructionOptionsItems":{"type":"object","properties":{"label":{"type":"string","description":"Display text shown to participants"},"value":{"$ref":"#/components/schemas/AiTaskBuilderMultipleChoiceInstructionOptionsItemsValue","description":"Value returned in responses"},"exclusive":{"type":"boolean","description":"When true, selecting this option deselects all other options. Useful for \"None of the above\" style options."}},"required":["label","value"],"title":"AiTaskBuilderMultipleChoiceInstructionOptionsItems"},"AiTaskBuilderFreeTextInputInstructionType":{"type":"string","enum":["free_text"],"title":"AiTaskBuilderFreeTextInputInstructionType"},"AiTaskBuilderFreeTextInputInstructionParentType":{"type":"string","enum":["batch","collection"],"title":"AiTaskBuilderFreeTextInputInstructionParentType"},"AiTaskBuilderFreeTextWithUnitInstructionType":{"type":"string","enum":["free_text_with_unit"],"title":"AiTaskBuilderFreeTextWithUnitInstructionType"},"AiTaskBuilderFreeTextWithUnitInstructionParentType":{"type":"string","enum":["batch","collection"],"title":"AiTaskBuilderFreeTextWithUnitInstructionParentType"},"AiTaskBuilderFreeTextWithUnitInstructionUnitOptionsItemsValue":{"oneOf":[{"type":"string"},{"type":"number","format":"double"},{"type":"boolean"}],"description":"Value returned in responses","title":"AiTaskBuilderFreeTextWithUnitInstructionUnitOptionsItemsValue"},"AiTaskBuilderFreeTextWithUnitInstructionUnitOptionsItems":{"type":"object","properties":{"label":{"type":"string","description":"Display text shown to participants"},"value":{"$ref":"#/components/schemas/AiTaskBuilderFreeTextWithUnitInstructionUnitOptionsItemsValue","description":"Value returned in responses"},"validation":{"$ref":"#/components/schemas/ValidationRule","description":"Optional validation constraints for this unit option"}},"required":["label","value"],"title":"AiTaskBuilderFreeTextWithUnitInstructionUnitOptionsItems"},"AiTaskBuilderFreeTextWithUnitInstructionUnitPosition":{"type":"string","enum":["prefix","suffix"],"description":"Position of the unit selector relative to the text input. Use 'prefix' for units before the input (e.g., currency symbols) or 'suffix' for units after the input (e.g., measurements).","title":"AiTaskBuilderFreeTextWithUnitInstructionUnitPosition"},"AiTaskBuilderMultipleChoiceWithFreeTextInstructionType":{"type":"string","enum":["multiple_choice_with_free_text"],"title":"AiTaskBuilderMultipleChoiceWithFreeTextInstructionType"},"AiTaskBuilderMultipleChoiceWithFreeTextInstructionParentType":{"type":"string","enum":["batch","collection"],"title":"AiTaskBuilderMultipleChoiceWithFreeTextInstructionParentType"},"AiTaskBuilderMultipleChoiceWithFreeTextInstructionOptionsItemsValue":{"oneOf":[{"type":"string"},{"type":"number","format":"double"},{"type":"boolean"}],"description":"Value returned in responses","title":"AiTaskBuilderMultipleChoiceWithFreeTextInstructionOptionsItemsValue"},"AiTaskBuilderMultipleChoiceWithFreeTextInstructionOptionsItems":{"type":"object","properties":{"label":{"type":"string","description":"Display text shown to participants"},"value":{"$ref":"#/components/schemas/AiTaskBuilderMultipleChoiceWithFreeTextInstructionOptionsItemsValue","description":"Value returned in responses"},"heading":{"type":"string","description":"Section heading that groups this option"},"exclusive":{"type":"boolean","description":"When true, selecting this option deselects all other options. Useful for \"None of the above\" style options."}},"required":["label","value","heading"],"title":"AiTaskBuilderMultipleChoiceWithFreeTextInstructionOptionsItems"},"AiTaskBuilderFileUploadInstructionType":{"type":"string","enum":["file_upload"],"title":"AiTaskBuilderFileUploadInstructionType"},"AiTaskBuilderFileUploadInstructionParentType":{"type":"string","enum":["batch","collection"],"title":"AiTaskBuilderFileUploadInstructionParentType"},"AITaskBuilderInstruction":{"oneOf":[{"type":"object","properties":{"type":{"$ref":"#/components/schemas/AiTaskBuilderMultipleChoiceInstructionType"},"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"parent_id":{"type":"string","format":"uuid","description":"ID of the parent batch or collection"},"parent_type":{"$ref":"#/components/schemas/AiTaskBuilderMultipleChoiceInstructionParentType"},"created_by":{"type":"string"},"description":{"type":"string","description":"The question or prompt displayed to participants"},"helper_text":{"type":"string","description":"Additional guidance text displayed below the question"},"placeholder_text_input":{"type":"string","description":"Placeholder text displayed in the input field"},"answer_limit":{"type":"integer","minimum":-1,"description":"Number of options that can be selected. Use 1 for single-select, -1 for unlimited, or any number up to the total options."},"disable_dropdown":{"type":"boolean","default":false,"description":"When true, always renders checkbox/radio elements instead of a dropdown select, regardless of option count. By default, a dropdown is used when there are 5 or more options."},"options":{"type":"array","items":{"$ref":"#/components/schemas/AiTaskBuilderMultipleChoiceInstructionOptionsItems"}}},"required":["type","id","created_at","parent_id","parent_type","created_by","description","answer_limit","options"],"description":"multiple_choice variant"},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/AiTaskBuilderFreeTextInputInstructionType"},"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"parent_id":{"type":"string","format":"uuid","description":"ID of the parent batch or collection"},"parent_type":{"$ref":"#/components/schemas/AiTaskBuilderFreeTextInputInstructionParentType"},"created_by":{"type":"string"},"description":{"type":"string","description":"The question or prompt displayed to participants"},"helper_text":{"type":"string","description":"Additional guidance text displayed below the question"},"placeholder_text_input":{"type":"string","description":"Placeholder text displayed in the input field"},"validation":{"$ref":"#/components/schemas/ValidationRule","description":"Optional validation constraints for the input value"}},"required":["type","id","created_at","parent_id","parent_type","created_by","description"],"description":"free_text variant"},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/AiTaskBuilderFreeTextWithUnitInstructionType"},"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"parent_id":{"type":"string","format":"uuid","description":"ID of the parent batch or collection"},"parent_type":{"$ref":"#/components/schemas/AiTaskBuilderFreeTextWithUnitInstructionParentType"},"created_by":{"type":"string"},"description":{"type":"string","description":"The question or prompt displayed to participants"},"helper_text":{"type":"string","description":"Additional guidance text displayed below the question"},"placeholder_text_input":{"type":"string","description":"Placeholder text displayed in the input field"},"unit_options":{"type":"array","items":{"$ref":"#/components/schemas/AiTaskBuilderFreeTextWithUnitInstructionUnitOptionsItems"},"description":"List of available units that participants can select from"},"default_unit":{"type":"string","description":"Default selected unit (must match a value from unit_options)"},"unit_position":{"$ref":"#/components/schemas/AiTaskBuilderFreeTextWithUnitInstructionUnitPosition","description":"Position of the unit selector relative to the text input. Use 'prefix' for units before the input (e.g., currency symbols) or 'suffix' for units after the input (e.g., measurements)."}},"required":["type","id","created_at","parent_id","parent_type","created_by","description","unit_options","unit_position"],"description":"free_text_with_unit variant"},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/AiTaskBuilderMultipleChoiceWithFreeTextInstructionType"},"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"parent_id":{"type":"string","format":"uuid","description":"ID of the parent batch or collection"},"parent_type":{"$ref":"#/components/schemas/AiTaskBuilderMultipleChoiceWithFreeTextInstructionParentType"},"created_by":{"type":"string"},"description":{"type":"string","description":"The question or prompt displayed to participants"},"helper_text":{"type":"string","description":"Additional guidance text displayed below the question"},"placeholder_text_input":{"type":"string","description":"Placeholder text displayed in the input field"},"answer_limit":{"type":"integer","minimum":-1,"description":"Number of options that can be selected. Use 1 for single-select, -1 for unlimited, or any number up to the total options."},"disable_dropdown":{"type":"boolean","default":false,"description":"When true, always renders checkbox/radio elements instead of a dropdown select, regardless of option count. By default, a dropdown is used when there are 5 or more options."},"options":{"type":"array","items":{"$ref":"#/components/schemas/AiTaskBuilderMultipleChoiceWithFreeTextInstructionOptionsItems"}}},"required":["type","id","created_at","parent_id","parent_type","created_by","description","answer_limit","options"],"description":"multiple_choice_with_free_text variant"},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/AiTaskBuilderFileUploadInstructionType"},"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"parent_id":{"type":"string","format":"uuid","description":"ID of the parent batch or collection"},"parent_type":{"$ref":"#/components/schemas/AiTaskBuilderFileUploadInstructionParentType"},"created_by":{"type":"string"},"description":{"type":"string","description":"The prompt describing what to upload"},"helper_text":{"type":"string","description":"Additional guidance text displayed below the question"},"placeholder_text_input":{"type":"string","description":"Placeholder text displayed in the input field"},"accepted_file_types":{"type":"array","items":{"type":"string","pattern":"^\\."},"description":"File extensions to accept (e.g., [\".jpg\", \".png\", \".pdf\"]). Each extension must start with a dot. Defaults to [\".jpg\", \".jpeg\", \".png\", \".heic\", \".heif\"] if not specified."},"max_file_size_mb":{"type":"number","format":"double","exclusiveMinimum":0,"description":"Maximum file size in megabytes per file. Must be a positive number. Defaults to 25."},"min_file_count":{"type":"integer","minimum":1,"description":"Minimum number of files required. Must be at least 1. Defaults to 1."},"max_file_count":{"type":"integer","minimum":1,"description":"Maximum number of files allowed. Must be at least 1 and greater than or equal to min_file_count. Defaults to 10."}},"required":["type","id","created_at","parent_id","parent_type","created_by","description"],"description":"file_upload variant"}],"discriminator":{"propertyName":"type"},"title":"AITaskBuilderInstruction"},"ApiV1DataCollectionBatchesBatchIdInstructionsGetResponsesContentApplicationJsonSchemaMeta":{"type":"object","properties":{"count":{"type":"integer","description":"Total number of instructions"}},"title":"ApiV1DataCollectionBatchesBatchIdInstructionsGetResponsesContentApplicationJsonSchemaMeta"},"AI Task Builder_GetTaskBuilderInstructions_Response_200":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/AITaskBuilderInstruction"}},"meta":{"$ref":"#/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsGetResponsesContentApplicationJsonSchemaMeta"}},"title":"AI Task Builder_GetTaskBuilderInstructions_Response_200"},"ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsType":{"type":"string","enum":["multiple_choice","free_text","free_text_with_unit","multiple_choice_with_free_text","file_upload"],"description":"The type of instruction.","title":"ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsType"},"ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsOptionsItems":{"type":"object","properties":{"label":{"type":"string","description":"The display label for the option."},"value":{"type":"string","description":"The value associated with the option."},"heading":{"type":"string","description":"The heading for the option (required for multiple_choice_with_free_text)."}},"required":["label","value"],"title":"ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsOptionsItems"},"ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItemsValue":{"oneOf":[{"type":"string"},{"type":"number","format":"double"},{"type":"boolean"}],"description":"The value associated with the unit.","title":"ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItemsValue"},"ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItems":{"type":"object","properties":{"label":{"type":"string","description":"The display label for the unit."},"value":{"$ref":"#/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItemsValue","description":"The value associated with the unit."},"validation":{"$ref":"#/components/schemas/ValidationRule","description":"Optional validation constraints for this unit option."}},"required":["label","value"],"title":"ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItems"},"ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitPosition":{"type":"string","enum":["prefix","suffix"],"description":"Required for free_text_with_unit. Position of the unit selector relative to the text input. Use 'prefix' for units before the input (e.g., currency symbols) or 'suffix' for units after the input (e.g., measurements).","title":"ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitPosition"},"ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItems":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsType","description":"The type of instruction."},"description":{"type":"string","description":"The question or prompt displayed to participants."},"helper_text":{"type":"string","description":"Additional guidance text displayed below the question."},"placeholder_text_input":{"type":"string","description":"Placeholder text displayed in the input field."},"answer_limit":{"type":"integer","minimum":-1,"description":"Number of options that can be selected (required for multiple_choice and multiple_choice_with_free_text). Use 1 for single-select, -1 for unlimited."},"disable_dropdown":{"type":"boolean","default":false,"description":"When true, always renders checkbox/radio elements instead of a dropdown select. By default, a dropdown is used when there are 5 or more options."},"options":{"type":"array","items":{"$ref":"#/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsOptionsItems"},"description":"The options (required for multiple_choice and multiple_choice_with_free_text)."},"unit_options":{"type":"array","items":{"$ref":"#/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItems"},"description":"The unit options (required for free_text_with_unit). List of available units that participants can select from."},"default_unit":{"type":"string","description":"For free_text_with_unit. Default selected unit (must match a value from unit_options)."},"unit_position":{"$ref":"#/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitPosition","description":"Required for free_text_with_unit. Position of the unit selector relative to the text input. Use 'prefix' for units before the input (e.g., currency symbols) or 'suffix' for units after the input (e.g., measurements)."},"validation":{"$ref":"#/components/schemas/ValidationRule","description":"Optional validation constraints for the input value (for free_text)."}},"required":["type","description"],"title":"ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItems"},"ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsType":{"type":"string","enum":["multiple_choice","free_text","free_text_with_unit","multiple_choice_with_free_text","file_upload"],"description":"The type of instruction.","title":"ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsType"},"ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsOptionsItems":{"type":"object","properties":{"label":{"type":"string","description":"The display text for the option."},"value":{"type":"string","description":"The value associated with the option."},"heading":{"type":"string","description":"The heading for the option (required for multiple_choice_with_free_text)."}},"required":["label","value"],"title":"ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsOptionsItems"},"ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItemsValue":{"oneOf":[{"type":"string"},{"type":"number","format":"double"},{"type":"boolean"}],"description":"The value associated with the unit.","title":"ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItemsValue"},"ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItems":{"type":"object","properties":{"label":{"type":"string","description":"The display label for the unit."},"value":{"$ref":"#/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItemsValue","description":"The value associated with the unit."},"validation":{"$ref":"#/components/schemas/ValidationRule","description":"Optional validation constraints for this unit option."}},"required":["label","value"],"title":"ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItems"},"ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitPosition":{"type":"string","enum":["prefix","suffix"],"description":"Required for free_text_with_unit. Position of the unit selector relative to the text input. Use 'prefix' for units before the input (e.g., currency symbols) or 'suffix' for units after the input (e.g., measurements).","title":"ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitPosition"},"ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItems":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Include to preserve an existing instruction."},"type":{"$ref":"#/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsType","description":"The type of instruction."},"description":{"type":"string","description":"The question or prompt displayed to participants."},"helper_text":{"type":"string","description":"Additional guidance text displayed below the question."},"placeholder_text_input":{"type":"string","description":"Placeholder text displayed in the input field."},"answer_limit":{"type":"integer","minimum":-1,"description":"Number of options that can be selected (required for multiple_choice and multiple_choice_with_free_text). Use 1 for single-select, -1 for unlimited."},"disable_dropdown":{"type":"boolean","default":false,"description":"When true, always renders checkbox/radio elements instead of a dropdown select."},"options":{"type":"array","items":{"$ref":"#/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsOptionsItems"},"description":"The options (required for multiple_choice and multiple_choice_with_free_text)."},"unit_options":{"type":"array","items":{"$ref":"#/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItems"},"description":"The unit options (required for free_text_with_unit). List of available units that participants can select from."},"default_unit":{"type":"string","description":"For free_text_with_unit. Default selected unit (must match a value from unit_options)."},"unit_position":{"$ref":"#/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitPosition","description":"Required for free_text_with_unit. Position of the unit selector relative to the text input. Use 'prefix' for units before the input (e.g., currency symbols) or 'suffix' for units after the input (e.g., measurements)."},"validation":{"$ref":"#/components/schemas/ValidationRule","description":"Optional validation constraints for the input value (for free_text)."}},"required":["type","description"],"title":"ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItems"},"CollectionSchemaVersion":{"type":"string","enum":["1"],"title":"CollectionSchemaVersion"},"TaskDetails":{"type":"object","properties":{"task_name":{"type":"string","description":"The title displayed to participants"},"task_introduction":{"type":"string","description":"HTML formatted introduction shown at the start of the task"},"task_steps":{"type":"string","description":"HTML formatted step-by-step instructions"}},"required":["task_name","task_introduction","task_steps"],"description":"Task metadata displayed to participants","title":"TaskDetails"},"CollectionItemSchemaVersion":{"type":"string","enum":["1"],"title":"CollectionItemSchemaVersion"},"CollectionMultipleChoiceInstructionType":{"type":"string","enum":["multiple_choice"],"title":"CollectionMultipleChoiceInstructionType"},"CollectionMultipleChoiceInstructionParentType":{"type":"string","enum":["batch","collection"],"title":"CollectionMultipleChoiceInstructionParentType"},"CollectionMultipleChoiceInstructionOptionsItemsValue":{"oneOf":[{"type":"string"},{"type":"number","format":"double"},{"type":"boolean"}],"title":"CollectionMultipleChoiceInstructionOptionsItemsValue"},"CollectionMultipleChoiceInstructionOptionsItems":{"type":"object","properties":{"label":{"type":"string"},"value":{"$ref":"#/components/schemas/CollectionMultipleChoiceInstructionOptionsItemsValue"},"exclusive":{"type":"boolean","description":"When true, selecting this option deselects all other options. Useful for \"None of the above\" style options."}},"required":["label","value"],"title":"CollectionMultipleChoiceInstructionOptionsItems"},"CollectionFreeTextInstructionType":{"type":"string","enum":["free_text"],"title":"CollectionFreeTextInstructionType"},"CollectionFreeTextInstructionParentType":{"type":"string","enum":["batch","collection"],"title":"CollectionFreeTextInstructionParentType"},"CollectionFreeTextWithUnitInstructionType":{"type":"string","enum":["free_text_with_unit"],"title":"CollectionFreeTextWithUnitInstructionType"},"CollectionFreeTextWithUnitInstructionParentType":{"type":"string","enum":["batch","collection"],"title":"CollectionFreeTextWithUnitInstructionParentType"},"CollectionFreeTextWithUnitInstructionUnitOptionsItemsValue":{"oneOf":[{"type":"string"},{"type":"number","format":"double"},{"type":"boolean"}],"description":"Value returned in responses","title":"CollectionFreeTextWithUnitInstructionUnitOptionsItemsValue"},"CollectionFreeTextWithUnitInstructionUnitOptionsItems":{"type":"object","properties":{"label":{"type":"string","description":"Display text shown to participants"},"value":{"$ref":"#/components/schemas/CollectionFreeTextWithUnitInstructionUnitOptionsItemsValue","description":"Value returned in responses"},"validation":{"$ref":"#/components/schemas/ValidationRule","description":"Optional validation constraints for this unit option"}},"required":["label","value"],"title":"CollectionFreeTextWithUnitInstructionUnitOptionsItems"},"CollectionFreeTextWithUnitInstructionUnitPosition":{"type":"string","enum":["prefix","suffix"],"description":"Position of the unit selector relative to the text input. Use 'prefix' for units before the input (e.g., currency symbols) or 'suffix' for units after the input (e.g., measurements).","title":"CollectionFreeTextWithUnitInstructionUnitPosition"},"CollectionMultipleChoiceWithFreeTextInstructionType":{"type":"string","enum":["multiple_choice_with_free_text"],"title":"CollectionMultipleChoiceWithFreeTextInstructionType"},"CollectionMultipleChoiceWithFreeTextInstructionParentType":{"type":"string","enum":["batch","collection"],"title":"CollectionMultipleChoiceWithFreeTextInstructionParentType"},"CollectionMultipleChoiceWithFreeTextInstructionOptionsItemsValue":{"oneOf":[{"type":"string"},{"type":"number","format":"double"},{"type":"boolean"}],"title":"CollectionMultipleChoiceWithFreeTextInstructionOptionsItemsValue"},"CollectionMultipleChoiceWithFreeTextInstructionOptionsItems":{"type":"object","properties":{"label":{"type":"string"},"value":{"$ref":"#/components/schemas/CollectionMultipleChoiceWithFreeTextInstructionOptionsItemsValue"},"heading":{"type":"string"},"exclusive":{"type":"boolean","description":"When true, selecting this option deselects all other options. Useful for \"None of the above\" style options."}},"required":["label","value","heading"],"title":"CollectionMultipleChoiceWithFreeTextInstructionOptionsItems"},"CollectionFileUploadInstructionType":{"type":"string","enum":["file_upload"],"title":"CollectionFileUploadInstructionType"},"CollectionFileUploadInstructionParentType":{"type":"string","enum":["batch","collection"],"title":"CollectionFileUploadInstructionParentType"},"ImageContentBlockType":{"type":"string","enum":["image"],"title":"ImageContentBlockType"},"ImageContentBlockParentType":{"type":"string","enum":["collection","batch"],"title":"ImageContentBlockParentType"},"ImageContentBlockSchemaVersion":{"type":"string","enum":["1"],"title":"ImageContentBlockSchemaVersion"},"RichTextContentBlockType":{"type":"string","enum":["rich_text"],"title":"RichTextContentBlockType"},"RichTextContentBlockParentType":{"type":"string","enum":["collection","batch"],"title":"RichTextContentBlockParentType"},"RichTextContentBlockSchemaVersion":{"type":"string","enum":["1"],"title":"RichTextContentBlockSchemaVersion"},"PageItem":{"oneOf":[{"type":"object","properties":{"type":{"$ref":"#/components/schemas/CollectionMultipleChoiceInstructionType"},"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"parent_id":{"type":"string","format":"uuid","description":"ID of the parent batch or collection"},"parent_type":{"$ref":"#/components/schemas/CollectionMultipleChoiceInstructionParentType"},"created_by":{"type":"string"},"description":{"type":"string"},"order":{"type":"integer"},"helper_text":{"type":"string","description":"Additional guidance text displayed below the question"},"placeholder_text_input":{"type":"string","description":"Placeholder text displayed in the input field"},"answer_limit":{"type":"integer","minimum":-1},"disable_dropdown":{"type":"boolean","default":false},"options":{"type":"array","items":{"$ref":"#/components/schemas/CollectionMultipleChoiceInstructionOptionsItems"}}},"required":["type","id","created_at","parent_id","parent_type","created_by","description","order","answer_limit","options"],"description":"multiple_choice variant"},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/CollectionFreeTextInstructionType"},"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"parent_id":{"type":"string","format":"uuid","description":"ID of the parent batch or collection"},"parent_type":{"$ref":"#/components/schemas/CollectionFreeTextInstructionParentType"},"created_by":{"type":"string"},"description":{"type":"string"},"order":{"type":"integer"},"helper_text":{"type":"string","description":"Additional guidance text displayed below the question"},"placeholder_text_input":{"type":"string","description":"Placeholder text displayed in the input field"},"validation":{"$ref":"#/components/schemas/ValidationRule","description":"Optional validation constraints for the input value"}},"required":["type","id","created_at","parent_id","parent_type","created_by","description","order"],"description":"free_text variant"},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/CollectionFreeTextWithUnitInstructionType"},"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"parent_id":{"type":"string","format":"uuid","description":"ID of the parent batch or collection"},"parent_type":{"$ref":"#/components/schemas/CollectionFreeTextWithUnitInstructionParentType"},"created_by":{"type":"string"},"description":{"type":"string"},"order":{"type":"integer"},"helper_text":{"type":"string","description":"Additional guidance text displayed below the question"},"placeholder_text_input":{"type":"string","description":"Placeholder text displayed in the input field"},"unit_options":{"type":"array","items":{"$ref":"#/components/schemas/CollectionFreeTextWithUnitInstructionUnitOptionsItems"},"description":"List of available units that participants can select from"},"default_unit":{"type":"string","description":"Default selected unit (must match a value from unit_options)"},"unit_position":{"$ref":"#/components/schemas/CollectionFreeTextWithUnitInstructionUnitPosition","description":"Position of the unit selector relative to the text input. Use 'prefix' for units before the input (e.g., currency symbols) or 'suffix' for units after the input (e.g., measurements)."}},"required":["type","id","created_at","parent_id","parent_type","created_by","description","order","unit_options","unit_position"],"description":"free_text_with_unit variant"},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/CollectionMultipleChoiceWithFreeTextInstructionType"},"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"parent_id":{"type":"string","format":"uuid","description":"ID of the parent batch or collection"},"parent_type":{"$ref":"#/components/schemas/CollectionMultipleChoiceWithFreeTextInstructionParentType"},"created_by":{"type":"string"},"description":{"type":"string"},"order":{"type":"integer"},"helper_text":{"type":"string","description":"Additional guidance text displayed below the question"},"placeholder_text_input":{"type":"string","description":"Placeholder text displayed in the input field"},"answer_limit":{"type":"integer","minimum":-1},"disable_dropdown":{"type":"boolean","default":false},"options":{"type":"array","items":{"$ref":"#/components/schemas/CollectionMultipleChoiceWithFreeTextInstructionOptionsItems"}}},"required":["type","id","created_at","parent_id","parent_type","created_by","description","order","answer_limit","options"],"description":"multiple_choice_with_free_text variant"},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/CollectionFileUploadInstructionType"},"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"parent_id":{"type":"string","format":"uuid","description":"ID of the parent batch or collection"},"parent_type":{"$ref":"#/components/schemas/CollectionFileUploadInstructionParentType"},"created_by":{"type":"string"},"description":{"type":"string"},"order":{"type":"integer"},"helper_text":{"type":"string","description":"Additional guidance text displayed below the question"},"placeholder_text_input":{"type":"string","description":"Placeholder text displayed in the input field"},"accepted_file_types":{"type":"array","items":{"type":"string","pattern":"^\\."},"description":"File extensions to accept (e.g., [\".jpg\", \".png\", \".pdf\"]). Each extension must start with a dot. Defaults to [\".jpg\", \".jpeg\", \".png\", \".heic\", \".heif\"] if not specified."},"max_file_size_mb":{"type":"number","format":"double","exclusiveMinimum":0,"description":"Maximum file size in megabytes per file. Must be a positive number. Defaults to 25."},"min_file_count":{"type":"integer","minimum":1,"description":"Minimum number of files required. Must be at least 1. Defaults to 1."},"max_file_count":{"type":"integer","minimum":1,"description":"Maximum number of files allowed. Must be at least 1 and greater than or equal to min_file_count. Defaults to 10."}},"required":["type","id","created_at","parent_id","parent_type","created_by","description","order"],"description":"file_upload variant"},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ImageContentBlockType"},"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"parent_id":{"type":"string","format":"uuid","description":"ID of the parent collection item (page)"},"parent_type":{"$ref":"#/components/schemas/ImageContentBlockParentType"},"created_by":{"type":"string"},"schema_version":{"$ref":"#/components/schemas/ImageContentBlockSchemaVersion"},"url":{"type":"string","format":"uri","description":"HTTPS URL of the image"},"alt_text":{"type":"string","description":"Alt text for accessibility"},"caption":{"type":"string","description":"Optional caption displayed below the image"}},"required":["type","id","created_at","parent_id","parent_type","created_by","schema_version","url","alt_text"],"description":"image variant"},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/RichTextContentBlockType"},"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"parent_id":{"type":"string","format":"uuid","description":"ID of the parent collection item (page)"},"parent_type":{"$ref":"#/components/schemas/RichTextContentBlockParentType"},"created_by":{"type":"string"},"schema_version":{"$ref":"#/components/schemas/RichTextContentBlockSchemaVersion"},"content":{"type":"string","description":"HTML content. If the original input used Markdown, it has been converted to HTML."}},"required":["type","id","created_at","parent_id","parent_type","created_by","schema_version","content"],"description":"rich_text variant"}],"discriminator":{"propertyName":"type"},"description":"An instruction or content block within a page","title":"PageItem"},"CollectionItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":"string"},"schema_version":{"$ref":"#/components/schemas/CollectionItemSchemaVersion"},"page_items":{"type":"array","items":{"$ref":"#/components/schemas/PageItem"},"description":"Instructions and content blocks on this page"}},"required":["id","created_at","created_by","schema_version","page_items"],"description":"A page within a collection containing instructions and content blocks","title":"CollectionItem"},"Collection":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"schema_version":{"$ref":"#/components/schemas/CollectionSchemaVersion"},"created_at":{"type":"string","format":"date-time","description":"ISO-8601 formatted creation timestamp in UTC"},"created_by":{"type":"string","description":"User ID of the Prolific user that created the collection"},"workspace_id":{"type":"string","description":"The ID of the Prolific workspace"},"name":{"type":"string","description":"The name of the collection"},"task_details":{"$ref":"#/components/schemas/TaskDetails"},"collection_items":{"type":"array","items":{"$ref":"#/components/schemas/CollectionItem"},"description":"Pages within the collection. Each collection item represents a page."},"last_modified_at":{"type":"string","format":"date-time","description":"ISO-8601 formatted last modification timestamp in UTC"},"last_modified_by":{"type":"string","description":"User ID of the Prolific user that last modified the collection"}},"required":["id","schema_version","created_at","created_by","workspace_id","name","task_details","collection_items"],"title":"Collection"},"ApiV1DataCollectionCollectionsGetResponsesContentApplicationJsonSchemaMeta":{"type":"object","properties":{"count":{"type":"integer","description":"Total number of collections"}},"title":"ApiV1DataCollectionCollectionsGetResponsesContentApplicationJsonSchemaMeta"},"AI Task Builder_ListCollections_Response_200":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"meta":{"$ref":"#/components/schemas/ApiV1DataCollectionCollectionsGetResponsesContentApplicationJsonSchemaMeta"}},"title":"AI Task Builder_ListCollections_Response_200"},"CollectionInstructionInputType":{"type":"string","enum":["multiple_choice","free_text","free_text_with_unit","multiple_choice_with_free_text","file_upload"],"title":"CollectionInstructionInputType"},"CollectionInstructionInputOptionsItemsValue":{"oneOf":[{"type":"string"},{"type":"number","format":"double"},{"type":"boolean"}],"title":"CollectionInstructionInputOptionsItemsValue"},"CollectionInstructionInputOptionsItems":{"type":"object","properties":{"label":{"type":"string"},"value":{"$ref":"#/components/schemas/CollectionInstructionInputOptionsItemsValue"},"heading":{"type":"string","description":"Required for multiple_choice_with_free_text"},"exclusive":{"type":"boolean","description":"When true, selecting this option deselects all other options. Useful for \"None of the above\" style options."}},"required":["label","value"],"title":"CollectionInstructionInputOptionsItems"},"CollectionInstructionInputUnitOptionsItemsValue":{"oneOf":[{"type":"string"},{"type":"number","format":"double"},{"type":"boolean"}],"title":"CollectionInstructionInputUnitOptionsItemsValue"},"CollectionInstructionInputUnitOptionsItems":{"type":"object","properties":{"label":{"type":"string"},"value":{"$ref":"#/components/schemas/CollectionInstructionInputUnitOptionsItemsValue"},"validation":{"$ref":"#/components/schemas/ValidationRule","description":"Optional validation constraints for this unit option."}},"required":["label","value"],"title":"CollectionInstructionInputUnitOptionsItems"},"CollectionInstructionInputUnitPosition":{"type":"string","enum":["prefix","suffix"],"description":"Required for free_text_with_unit. Position of the unit selector relative to the text input.","title":"CollectionInstructionInputUnitPosition"},"CollectionInstructionInput":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Include to preserve an existing instruction when updating"},"type":{"$ref":"#/components/schemas/CollectionInstructionInputType"},"description":{"type":"string","description":"The question or prompt displayed to participants"},"order":{"type":"integer","description":"Position of this instruction relative to others"},"helper_text":{"type":"string","description":"Additional guidance text displayed below the question"},"placeholder_text_input":{"type":"string","description":"Placeholder text displayed in the input field"},"answer_limit":{"type":"integer","minimum":-1,"description":"Number of options that can be selected. Use 1 for single-select, -1 for unlimited."},"disable_dropdown":{"type":"boolean","default":false,"description":"When true, always renders checkbox/radio elements instead of a dropdown select."},"options":{"type":"array","items":{"$ref":"#/components/schemas/CollectionInstructionInputOptionsItems"}},"unit_options":{"type":"array","items":{"$ref":"#/components/schemas/CollectionInstructionInputUnitOptionsItems"},"description":"Required for free_text_with_unit. List of available units that participants can select from."},"default_unit":{"type":"string","description":"For free_text_with_unit. Default selected unit (must match a value from unit_options)."},"unit_position":{"$ref":"#/components/schemas/CollectionInstructionInputUnitPosition","description":"Required for free_text_with_unit. Position of the unit selector relative to the text input."},"validation":{"$ref":"#/components/schemas/ValidationRule","description":"Optional validation constraints for the input value (for free_text)."}},"required":["type","description","order"],"description":"Instruction input for a collection page","title":"CollectionInstructionInput"},"ContentBlockInputType":{"type":"string","enum":["image","rich_text"],"title":"ContentBlockInputType"},"ContentBlockInputContentFormat":{"type":"string","enum":["html","markdown"],"default":"html","description":"Format of the content field. When set to \"markdown\", content is converted to HTML server-side before storage. Defaults to \"html\".","title":"ContentBlockInputContentFormat"},"ContentBlockInput":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Include to preserve an existing content block when updating"},"type":{"$ref":"#/components/schemas/ContentBlockInputType"},"url":{"type":"string","format":"uri","description":"HTTPS URL for image content blocks"},"alt_text":{"type":"string","description":"Alt text for image content blocks (required for accessibility)"},"caption":{"type":"string","description":"Optional caption for image content blocks"},"content":{"type":"string","description":"Content for rich_text content blocks. Interpreted as HTML by default, or Markdown if content_format is set to \"markdown\"."},"content_format":{"$ref":"#/components/schemas/ContentBlockInputContentFormat","default":"html","description":"Format of the content field. When set to \"markdown\", content is converted to HTML server-side before storage. Defaults to \"html\"."}},"required":["type"],"description":"Content block input for a collection page","title":"ContentBlockInput"},"PageItemInput":{"oneOf":[{"$ref":"#/components/schemas/CollectionInstructionInput"},{"$ref":"#/components/schemas/ContentBlockInput"}],"description":"An instruction or content block input. Include `id` to preserve an existing item when updating.","title":"PageItemInput"},"CollectionItemInput":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Include to preserve an existing page when updating"},"page_items":{"type":"array","items":{"$ref":"#/components/schemas/PageItemInput"},"description":"Instructions and content blocks on this page"}},"required":["page_items"],"description":"A page within a collection. Include `id` to preserve an existing page when updating.","title":"CollectionItemInput"},"CollectionCreateRequest":{"type":"object","properties":{"name":{"type":"string","description":"The name of the collection"},"workspace_id":{"type":"string","description":"The ID of the Prolific workspace"},"task_details":{"$ref":"#/components/schemas/TaskDetails"},"collection_items":{"type":"array","items":{"$ref":"#/components/schemas/CollectionItemInput"},"description":"Pages within the collection"}},"required":["name","workspace_id","task_details","collection_items"],"title":"CollectionCreateRequest"},"CollectionUpdateRequest":{"type":"object","properties":{"name":{"type":"string","description":"The name of the collection"},"task_details":{"$ref":"#/components/schemas/TaskDetails"},"collection_items":{"type":"array","items":{"$ref":"#/components/schemas/CollectionItemInput"},"description":"Pages within the collection. Include `id` to preserve existing items."}},"required":["name","task_details","collection_items"],"title":"CollectionUpdateRequest"},"CollectionResponseResponseType":{"type":"string","enum":["multiple_choice","free_text","free_text_with_unit","multiple_choice_with_free_text","file_upload"],"title":"CollectionResponseResponseType"},"CollectionResponseResponseAnswerItemsValue":{"oneOf":[{"type":"string"},{"type":"number","format":"double"},{"type":"boolean"}],"title":"CollectionResponseResponseAnswerItemsValue"},"CollectionResponseResponseAnswerItems":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/CollectionResponseResponseAnswerItemsValue"}},"title":"CollectionResponseResponseAnswerItems"},"CollectionResponseResponse":{"type":"object","properties":{"instruction_id":{"type":"string"},"type":{"$ref":"#/components/schemas/CollectionResponseResponseType"},"answer":{"type":"array","items":{"$ref":"#/components/schemas/CollectionResponseResponseAnswerItems"}}},"required":["instruction_id","type","answer"],"title":"CollectionResponseResponse"},"CollectionResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"collection_id":{"type":"string","format":"uuid"},"participant_id":{"type":"string"},"submission_id":{"type":"string"},"response":{"$ref":"#/components/schemas/CollectionResponseResponse"}},"required":["id","created_at","collection_id","participant_id","response"],"description":"A participant's response to a collection","title":"CollectionResponse"},"ApiV1DataCollectionCollectionsCollectionIdResponsesGetResponsesContentApplicationJsonSchemaMeta":{"type":"object","properties":{"count":{"type":"integer","description":"Total number of responses"}},"title":"ApiV1DataCollectionCollectionsCollectionIdResponsesGetResponsesContentApplicationJsonSchemaMeta"},"AI Task Builder_GetCollectionResponses_Response_200":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/CollectionResponse"}},"meta":{"$ref":"#/components/schemas/ApiV1DataCollectionCollectionsCollectionIdResponsesGetResponsesContentApplicationJsonSchemaMeta"}},"title":"AI Task Builder_GetCollectionResponses_Response_200"},"CollectionExportCompleteStatus":{"type":"string","enum":["complete"],"title":"CollectionExportCompleteStatus"},"CollectionExportComplete":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/CollectionExportCompleteStatus"},"url":{"type":"string","format":"uri","description":"Presigned HTTPS URL for downloading the ZIP archive. Valid for 1 hour. Re-poll to get a refreshed URL if expired."},"expires_at":{"type":"string","format":"date-time","description":"ISO 8601 timestamp indicating when the presigned URL expires."}},"required":["status","url","expires_at"],"description":"An export job that has completed successfully. The ZIP archive is ready to download.","title":"CollectionExportComplete"},"CollectionExportStatusOneOf0Status":{"type":"string","enum":["generating"],"title":"CollectionExportStatusOneOf0Status"},"CollectionExportStatus0":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/CollectionExportStatusOneOf0Status"},"export_id":{"type":"string","format":"uuid","description":"The export job ID. Use this with `GET /collections/{collection_id}/export/{export_id}` to poll for status."}},"required":["status","export_id"],"description":"An export job that has been enqueued and is currently being generated.","title":"CollectionExportStatus0"},"CollectionExportStatusOneOf1Status":{"type":"string","enum":["complete"],"title":"CollectionExportStatusOneOf1Status"},"CollectionExportStatus1":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/CollectionExportStatusOneOf1Status"},"url":{"type":"string","format":"uri","description":"Presigned HTTPS URL for downloading the ZIP archive. Valid for 1 hour. Re-poll to get a refreshed URL if expired."},"expires_at":{"type":"string","format":"date-time","description":"ISO 8601 timestamp indicating when the presigned URL expires."}},"required":["status","url","expires_at"],"description":"An export job that has completed successfully. The ZIP archive is ready to download.","title":"CollectionExportStatus1"},"CollectionExportStatusOneOf2Status":{"type":"string","enum":["failed"],"title":"CollectionExportStatusOneOf2Status"},"CollectionExportStatus2":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/CollectionExportStatusOneOf2Status"}},"required":["status"],"description":"An export job that failed to generate, or whose archive has since been deleted. Re-send `POST /collections/{collection_id}/export` to retry.","title":"CollectionExportStatus2"},"CollectionExportStatus":{"oneOf":[{"$ref":"#/components/schemas/CollectionExportStatus0"},{"$ref":"#/components/schemas/CollectionExportStatus1"},{"$ref":"#/components/schemas/CollectionExportStatus2"}],"description":"The current status of a collection export job.","title":"CollectionExportStatus"},"ApiV1StudiesGetParametersState":{"type":"string","enum":["ACTIVE","PAUSED","UNPUBLISHED","PUBLISHING","COMPLETED","AWAITING REVIEW","UNKNOWN","SCHEDULED"],"title":"ApiV1StudiesGetParametersState"},"StudyShortStatus":{"type":"string","enum":["UNPUBLISHED","SCHEDULED","PUBLISHING","ACTIVE","AWAITING REVIEW","PAUSED","COMPLETED"],"description":"Status of the study.","title":"StudyShortStatus"},"StudyShortStudyType":{"type":"string","enum":["SINGLE","UK_REP_SAMPLE","US_REP_SAMPLE"],"description":"Deprecated. Type of study.","title":"StudyShortStudyType"},"StudyShort":{"type":"object","properties":{"id":{"type":"string","description":"Study id. It is created by Prolific."},"name":{"type":"string","description":"Public name or title of the study"},"internal_name":{"type":["string","null"],"description":"Internal name of the study, not shown to participants"},"status":{"$ref":"#/components/schemas/StudyShortStatus","description":"Status of the study."},"study_type":{"$ref":"#/components/schemas/StudyShortStudyType","description":"Deprecated. Type of study."},"estimated_completion_time":{"type":"integer","minimum":1,"description":"Estimated duration in minutes of the experiment or survey"},"total_available_places":{"type":"number","format":"double","description":"How many participants are you looking to recruit"},"places_taken":{"type":"number","format":"double","description":"Places already taken, number of submission started excluding timed out and returned submissions"},"number_of_submissions":{"type":"number","format":"double"},"reward":{"type":"number","format":"double","description":"How much are you going to pay the participants in cents. We use the currency of your account"},"total_cost":{"type":"number","format":"double","description":"Total cost of the study including fees"},"published_at":{"type":["string","null"],"format":"date-time","description":"Date time when the study was published."},"publish_at":{"type":["string","null"],"format":"date-time","description":"Date time when the study was scheduled to be published."},"date_created":{"type":"string","format":"date-time","description":"Date time when the study was created"},"credential_pool_id":{"type":["string","null"],"description":"The ID of the credential pool associated with this study, if any"},"is_ready_to_publish":{"type":"boolean","description":"Whether the study has all required fields completed for publishing. Does not check wallet balance or funding — only study-level field completeness."}},"required":["id","name"],"title":"StudyShort"},"StudiesListResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/StudyShort"},"description":"List of all studies matching the criteria."}},"required":["results"],"title":"StudiesListResponse"},"CreateStudyProlificIdOption":{"type":"string","enum":["question","url_parameters","not_required"],"description":"Use 'question' if you will add a question in your survey or experiment asking the participant ID\n\n**Recommended** Use 'url_parameters' if your survey or experiment can retrieve and store those parameters for your analysis.\n\nUse 'not_required' if you don't need to record them.","title":"CreateStudyProlificIdOption"},"CreateStudyCompletionCodesItemsCodeType":{"type":"string","enum":["COMPLETED","FAILED_ATTENTION_CHECK","FOLLOW_UP_STUDY","GIVE_BONUS","INCOMPATIBLE_DEVICE","NO_CONSENT","OTHER","FIXED_SCREENOUT","SCREENED_IN","SCREENED_OUT"],"description":"A name for your code to make it easier to understand its intention. Either use one of the predefined options or any other free text.\n","title":"CreateStudyCompletionCodesItemsCodeType"},"AutomaticallyApproveAction":{"type":"string","enum":["AUTOMATICALLY_APPROVE"],"description":"Automatically approves submission with payment being processed immediately","title":"AutomaticallyApproveAction"},"AutomaticallyApprove":{"type":"object","properties":{"action":{"$ref":"#/components/schemas/AutomaticallyApproveAction","description":"Automatically approves submission with payment being processed immediately"}},"required":["action"],"title":"AutomaticallyApprove"},"AddToParticipantGroupAction":{"type":"string","enum":["ADD_TO_PARTICIPANT_GROUP"],"description":"Adds participants to a specific group","title":"AddToParticipantGroupAction"},"AddToParticipantGroup":{"type":"object","properties":{"action":{"$ref":"#/components/schemas/AddToParticipantGroupAction","description":"Adds participants to a specific group"},"participant_group":{"type":"string","description":"The participant group to add the participant to."}},"required":["action","participant_group"],"title":"AddToParticipantGroup"},"RemoveFromParticipantGroupAction":{"type":"string","enum":["REMOVE_FROM_PARTICIPANT_GROUP"],"description":"Removes participants from specific groups","title":"RemoveFromParticipantGroupAction"},"RemoveFromParticipantGroup":{"type":"object","properties":{"action":{"$ref":"#/components/schemas/RemoveFromParticipantGroupAction","description":"Removes participants from specific groups"},"participant_group":{"type":"string","description":"The participant group to remove the participant from."}},"required":["action","participant_group"],"title":"RemoveFromParticipantGroup"},"ManuallyReviewAction":{"type":"string","enum":["MANUALLY_REVIEW"],"description":"Moves submission for the data collector to be manually reviewed.","title":"ManuallyReviewAction"},"ManuallyReview":{"type":"object","properties":{"action":{"$ref":"#/components/schemas/ManuallyReviewAction","description":"Moves submission for the data collector to be manually reviewed."}},"required":["action"],"title":"ManuallyReview"},"RequestReturnAction":{"type":"string","enum":["REQUEST_RETURN"],"description":"Requests the participant to return their study","title":"RequestReturnAction"},"RequestReturn":{"type":"object","properties":{"action":{"$ref":"#/components/schemas/RequestReturnAction","description":"Requests the participant to return their study"},"return_reason":{"type":"string","description":"The reason you would like to request a return"}},"required":["action","return_reason"],"title":"RequestReturn"},"DynamicPaymentAction":{"type":"string","enum":["DYNAMIC_PAYMENT"],"description":"Use this action to set up a dynamic payment study. Only certain workspaces have access to this feature. When using this action, the actor must be \"researcher\".","title":"DynamicPaymentAction"},"DynamicPayment":{"type":"object","properties":{"action":{"$ref":"#/components/schemas/DynamicPaymentAction","description":"Use this action to set up a dynamic payment study. Only certain workspaces have access to this feature. When using this action, the actor must be \"researcher\"."}},"required":["action"],"title":"DynamicPayment"},"FixedScreenOutAction":{"type":"string","enum":["FIXED_SCREEN_OUT_PAYMENT"],"description":"Use this action to set up a fixed screen out reward study. This feature is currently available to select workspaces only.\n- A fixed screen out reward study compensates participants with a predetermined amount when they do not qualify for the study.\n- This feature enables researchers to implement more precise participant screening while ensuring fair compensation for participants' time.","title":"FixedScreenOutAction"},"FixedScreenOut":{"type":"object","properties":{"action":{"$ref":"#/components/schemas/FixedScreenOutAction","description":"Use this action to set up a fixed screen out reward study. This feature is currently available to select workspaces only.\n- A fixed screen out reward study compensates participants with a predetermined amount when they do not qualify for the study.\n- This feature enables researchers to implement more precise participant screening while ensuring fair compensation for participants' time."},"fixed_screen_out_reward":{"type":"integer","minimum":10,"description":"The amount that you would like to pay for a screen-out submission (in subcurrency). This must be less that the study reward."},"slots":{"type":"integer","minimum":1,"description":"The slots field controls how many participants can be screened out of your study before it automatically pauses.\n\n#### What are slots?\n - Slots set a limit on screen-outs to help you budget upfront, by setting the limit to the maximum number of screen-outs you're comfortable paying for in your study.\n - When participants don't qualify for your study, they will receive a screen-out payment.\n - The slots limit prevents unexpected high costs created from too many screen-outs.\n - **Example**: If you set `slots: 50`, your study will pause after 50 participants are screened out, even if you still need more qualified participants.\n\n#### How slots work\n 1. **Participants are screened out** - When they enter the completion code linked to this action. They will automatically receive the fixed screen out reward.\n 2. **Study pauses automatically** - When the number of participants screened out reaches the slots limit, and there are still unfilled places in the study, the study will automatically pause.\n 3. **You get notified** - Via email and webhook, notifying you that you’ve reached your slot limit, and that your study has been paused. (Webhook notifications only if they’re enabled for `study.status.change` events)\n\n#### Resuming your study\n *To continue recruiting after hitting the slot limit:*\n\n 1. **Increase the slot limit** using the [update study](#tag/Studies/operation/UpdateStudy) endpoint.\n - Update the initial property to your new slot limit.\n - Refer `update_slots` in the example of the [UpdateStudy](#tag/Studies/operation/UpdateStudy) endpoint.\n - For example, if you started with 50 slots and want to add another 50 slots, set the `slots` property to 100.\n ```json\n {\n \"completion_codes\": [\n {\n \"code\": \"ABC123\",\n \"actions\": [\n {\n \"action\": \"FIXED_SCREEN_OUT_PAYMENT\",\n \"slots\": 100\n }\n ]\n }\n ]\n }\n ```\n 2. **Resume the study** by transitioning it back to `START` state using the [transition study](#tag/Studies/operation/PublishStudy) endpoint.\n\n ```json\n {\n \"action\": \"START\"\n }\n ```"}},"required":["action","fixed_screen_out_reward","slots"],"description":"Use this action to set up a fixed screen out reward study.","title":"FixedScreenOut"},"CreateStudyCompletionCodesItemsActionsItems":{"oneOf":[{"$ref":"#/components/schemas/AutomaticallyApprove"},{"$ref":"#/components/schemas/AddToParticipantGroup"},{"$ref":"#/components/schemas/RemoveFromParticipantGroup"},{"$ref":"#/components/schemas/ManuallyReview"},{"$ref":"#/components/schemas/RequestReturn"},{"$ref":"#/components/schemas/DynamicPayment"},{"$ref":"#/components/schemas/FixedScreenOut"}],"title":"CreateStudyCompletionCodesItemsActionsItems"},"CreateStudyCompletionCodesItemsActor":{"type":"string","enum":["participant","researcher"],"default":"participant","description":"The actor that can provide this completion code.","title":"CreateStudyCompletionCodesItemsActor"},"CreateStudyCompletionCodesItems":{"type":"object","properties":{"code":{"type":["string","null"],"description":"The code the participant will either enter manually at the end of your study or be redirected as part of the return URL.\n\nIf the code is null, then the participant will not be asked to submit a completion code when they return to Prolific.\nNull codes can only be provided when:\n - The actor is \"participant\"\n - There are no other completion codes with the \"participant\" actor\n - The actions array is empty\n\nThe code must be unique within the study.\n"},"code_type":{"$ref":"#/components/schemas/CreateStudyCompletionCodesItemsCodeType","description":"A name for your code to make it easier to understand its intention. Either use one of the predefined options or any other free text.\n"},"actions":{"type":"array","items":{"$ref":"#/components/schemas/CreateStudyCompletionCodesItemsActionsItems"},"description":"The actions that will be completed automatically when the submission is completed with this code by the participant.\n\nYou have the ability to use one or multiple `actions` together - it's up to you and your desired automated journey.\n\nIf you’re looking to keep things simple, we recommend setting the `{\"action\": \"MANUALLY_REVIEW\"}` option only, so all submissions wait for your manual approval."},"actor":{"$ref":"#/components/schemas/CreateStudyCompletionCodesItemsActor","default":"participant","description":"The actor that can provide this completion code."}},"required":["code","code_type","actions"],"title":"CreateStudyCompletionCodesItems"},"CreateStudyDeviceCompatibilityItems":{"type":"string","enum":["desktop","tablet","mobile"],"title":"CreateStudyDeviceCompatibilityItems"},"CreateStudyPeripheralRequirementsItems":{"type":"string","enum":["audio","camera","download","microphone"],"title":"CreateStudyPeripheralRequirementsItems"},"SelectFilter":{"type":"object","properties":{"filter_id":{"type":"string","description":"ID of the \"select\" type filter."},"selected_values":{"type":"array","items":{"type":"string"},"description":"This schema applies for filters of the `select` type, as defined in the [filter list response](\\#tag/Filters/paths/~1api~1v1~1filters~1/get).\n\nArray of IDs matching the response IDs, from the `select` filter's `choices` (see response linked above).\n\nString format should match the `data_type` of the `select` filter's `choices` (see response linked above)."},"weightings":{"type":"object","additionalProperties":{"type":"number","format":"double"},"description":"Ratios to control the distribution of participants across the selected values.\n\nInteger percentages, floats, and exact quantities are valid inputs."}},"required":["filter_id","selected_values"],"title":"SelectFilter"},"RangeFilterSelectedRangeLower":{"oneOf":[{"type":"integer"},{"type":"string"},{"type":"number","format":"double"}],"description":"Your selected lower bound for the range.","title":"RangeFilterSelectedRangeLower"},"RangeFilterSelectedRangeUpper":{"oneOf":[{"type":"integer"},{"type":"string"},{"type":"number","format":"double"}],"description":"Your selected upper bound for the range.","title":"RangeFilterSelectedRangeUpper"},"RangeFilterSelectedRange":{"type":"object","properties":{"lower":{"$ref":"#/components/schemas/RangeFilterSelectedRangeLower","description":"Your selected lower bound for the range."},"upper":{"$ref":"#/components/schemas/RangeFilterSelectedRangeUpper","description":"Your selected upper bound for the range."}},"description":"This schema applies for filters of the `range` type, as defined in the [filter list response](\\#tag/Filters/paths/~1api~1v1~1filters~1/get).\n\nA dictionary with two possible objects, 'lower' and 'upper'. At least one must be present and a non-null value.\n\nThe expected data type for these values is defined by the `range` filter's `data_type` (see response linked above).\n\nIf the data_type is a date, string format should be a parseable ISO8601 date string. Date values should be provided as a string in ISO 8601 format.\n\nLeaving a value as null will result in that bound being set to the lowest or highest possible value, depending on whether it is the upper or lower bound.","title":"RangeFilterSelectedRange"},"RangeFilterWeightingsSelectedRangeLower":{"oneOf":[{"type":"integer"},{"type":"string"},{"type":"number","format":"double"}],"title":"RangeFilterWeightingsSelectedRangeLower"},"RangeFilterWeightingsSelectedRangeUpper":{"oneOf":[{"type":"integer"},{"type":"string"},{"type":"number","format":"double"}],"title":"RangeFilterWeightingsSelectedRangeUpper"},"RangeFilterWeightingsSelectedRange":{"type":"object","properties":{"lower":{"$ref":"#/components/schemas/RangeFilterWeightingsSelectedRangeLower"},"upper":{"$ref":"#/components/schemas/RangeFilterWeightingsSelectedRangeUpper"}},"title":"RangeFilterWeightingsSelectedRange"},"RangeFilterWeightings":{"type":"object","properties":{"selected_range":{"$ref":"#/components/schemas/RangeFilterWeightingsSelectedRange"},"weighting":{"type":"number","format":"double"}},"required":["selected_range","weighting"],"title":"RangeFilterWeightings"},"RangeFilter":{"type":"object","properties":{"filter_id":{"type":"string","description":"ID of the \"range\" type filter."},"selected_range":{"$ref":"#/components/schemas/RangeFilterSelectedRange","description":"This schema applies for filters of the `range` type, as defined in the [filter list response](\\#tag/Filters/paths/~1api~1v1~1filters~1/get).\n\nA dictionary with two possible objects, 'lower' and 'upper'. At least one must be present and a non-null value.\n\nThe expected data type for these values is defined by the `range` filter's `data_type` (see response linked above).\n\nIf the data_type is a date, string format should be a parseable ISO8601 date string. Date values should be provided as a string in ISO 8601 format.\n\nLeaving a value as null will result in that bound being set to the lowest or highest possible value, depending on whether it is the upper or lower bound."},"weightings":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/RangeFilterWeightings"},"description":"Ratios to control the distribution of participants across the selected values.\n\nIntegers and exact quantities are valid inputs."}},"required":["filter_id","selected_range"],"title":"RangeFilter"},"CompositeFilterFilterId":{"type":"string","enum":["and","or"],"description":"Composite filter group operator. Use `and` when every child filter must match, or `or` when at least one child filter must match.","title":"CompositeFilterFilterId"},"CompositeFilterSelectedFiltersItems":{"oneOf":[{"$ref":"#/components/schemas/SelectFilter"},{"$ref":"#/components/schemas/RangeFilter"},{"$ref":"#/components/schemas/CompositeFilter"}],"title":"CompositeFilterSelectedFiltersItems"},"CompositeFilter":{"type":"object","properties":{"filter_id":{"$ref":"#/components/schemas/CompositeFilterFilterId","description":"Composite filter group operator. Use `and` when every child filter must match, or `or` when at least one child filter must match."},"selected_filters":{"type":"array","items":{"$ref":"#/components/schemas/CompositeFilterSelectedFiltersItems"},"description":"Child filters in this group. Children can be select filters, range filters, or supported nested composite groups."}},"required":["filter_id","selected_filters"],"title":"CompositeFilter"},"CreateStudyFiltersItems":{"oneOf":[{"$ref":"#/components/schemas/SelectFilter"},{"$ref":"#/components/schemas/RangeFilter"},{"$ref":"#/components/schemas/CompositeFilter"}],"title":"CreateStudyFiltersItems"},"CreateStudySubmissionsConfigAutoRejectionCategoriesItems":{"type":"string","enum":["EXCEPTIONALLY_FAST"],"title":"CreateStudySubmissionsConfigAutoRejectionCategoriesItems"},"CreateStudySubmissionsConfig":{"type":"object","properties":{"max_submissions_per_participant":{"type":["integer","null"],"default":1,"description":"- **1** is the default Prolific experience. This means one submission, per participant, per study. If you do\n not specify this field, the **default is 1**.\n- **1+** turns your study into a multi-submission study, meaning a participant can create many submissions per study.\n As noted above, your survey system will need to handle providing a\nunique experience each time the participant takes the study.\n- **-1** will allow an indefinite number of submissions from a single participant, up to `total_available_places`."},"max_concurrent_submissions":{"type":["integer","null"],"default":-1,"description":"- **-1** is the default value, meaning unlimited concurrent active/reserved submissions per study.\n- **1+** limits the number of concurrent active/reserved submissions a study can have at one time."},"auto_rejection_categories":{"type":"array","items":{"$ref":"#/components/schemas/CreateStudySubmissionsConfigAutoRejectionCategoriesItems"},"default":[],"description":"List of rejection categories that trigger automatic submission rejections.\n\n**Available Categories:**\n- **EXCEPTIONALLY_FAST**: Automatically reject submissions completed in an exceptionally short time\n\n**Important Notes:**\n- **This feature is currently in an evaluation period and can be activated for your workspace upon request.**\n- Auto-rejections only apply to submissions in \"AWAITING REVIEW\" status\n- Submissions with return requests will not be auto-rejected\n- Auto-rejected submissions do not count towards your rejection limit\n- Set to an empty array `[]` or omit this field to disable auto-rejection"}},"description":"**Advanced**: This helps with faster data collection. Your survey system will need to handle providing a\nunique experience each time the participant takes the study.\n\nConfiguration related to study submissions. The purpose of this field is to capture any configuration options that impact the submissions made by participants in a study.","title":"CreateStudySubmissionsConfig"},"CreateStudyStudyLabelsItems":{"type":"string","enum":["survey","writing_task","annotation","decision_making_task","interview","other","ai_annotation","ai_evaluation","ai_reasoning","ai_fact_checking","ai_safety","ai_data_creation_text","ai_data_creation_audio","ai_data_creation_video","ai_data_creation_images","ai_other"],"title":"CreateStudyStudyLabelsItems"},"CreateStudyContentWarningsItems":{"type":"string","enum":["sensitive","explicit"],"title":"CreateStudyContentWarningsItems"},"CreateStudyDataCollectionMethod":{"type":"string","enum":["AI_TASK_BUILDER_BATCH","AI_TASK_BUILDER_COLLECTION"],"description":"**Optional.** Specifies the data collection method for the study.\n\n- `AI_TASK_BUILDER_BATCH`: Use AI Task Builder for data annotation tasks.\n- `AI_TASK_BUILDER_COLLECTION`: Use AI Task Builder for data collection tasks.\n\n**Note:** This field is mutually exclusive with `external_study_url` and `access_details`. If not provided, you must specify one of those fields instead.","title":"CreateStudyDataCollectionMethod"},"CreateStudyDataCollectionMetadata":{"type":"object","properties":{"annotators_per_task":{"type":"integer","minimum":1,"description":"Number of annotators required per task. Required for AI Task Builder Batch studies to set multiple annotators."}},"description":"**Optional.** Additional metadata for configuring AI Task Builder data annotation behavior. Only used when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH`.\n\n**Properties:**\n\n- `annotators_per_task` (integer): Number of annotators per task. **This field must be provided if you want multiple annotators per task.** Without this field, the default value of 1 will be used.\n - Minimum: 1\n - Default: 1 (if not provided)\n\n**Example:**\n```json\n{\n \"annotators_per_task\": 5\n}\n```\n\n**Important:** You must include `annotators_per_task` to control how many participants annotate each task. After the study is published, this value can only be increased (not decreased), which will increase the total available places on the study.","title":"CreateStudyDataCollectionMetadata"},"AccessDetail":{"type":"object","properties":{"external_url":{"type":"string","description":"URL of the task you want to send the participant to. You can pass URL search parameters as in `external_study_url`."},"total_allocation":{"type":"number","format":"double","description":"The base number of places you want allocated to this URL. This value is set by you and is used to determine the study's total available places.\n\nNote: for studies with custom screening (fixed screen-out reward), participants who are screened out generate additional capacity on top of this base value. The `allocated` count in progress responses may therefore exceed `total_allocation` — this is expected behaviour. See `capacity_increments` in the progress response for details."}},"required":["external_url","total_allocation"],"title":"AccessDetail"},"CreateStudyAccessDetailsItems":{"oneOf":[{"$ref":"#/components/schemas/AccessDetail"}],"title":"CreateStudyAccessDetailsItems"},"CreateStudy":{"type":"object","properties":{"name":{"type":"string","description":"Public name or title of the study"},"internal_name":{"type":["string","null"],"description":"Internal name of the study, not shown to participants"},"description":{"type":"string","description":"Description of the study for the participants to read before\nstarting the study\n\n**Supported HTML in `description`**\n\nThe `description` field supports the following HTML tags for formatting participant instructions:\n\n* `` - bold\n* `` - italic\n* `` - emphasized text\n* `` - strong importance\n* `` - strikethrough\n* `` - underline\n* `

` - heading level 1\n* `

` - heading level 2\n* `
    ` - ordered list\n* `
      ` - unordered list\n* `
    • ` - list item\n* `

      ` - paragraph\n\nOther HTML tags will be stripped or escaped. Please ensure that you only use supported tags for formatting to avoid rendering issues."},"external_study_url":{"type":"string","description":"URL of the survey or experiment you want participant to access. You can pass URL search parameters to your survey or experiment\n\n* Participant id {{%PROLIFIC_PID%}}\n* Study id {{%STUDY_ID%}}\n* Session id {{%SESSION_ID%}}\n\nFor example `https://eggs-experriment.com?participant={{%PROLIFIC_PID%}}`"},"prolific_id_option":{"$ref":"#/components/schemas/CreateStudyProlificIdOption","description":"Use 'question' if you will add a question in your survey or experiment asking the participant ID\n\n**Recommended** Use 'url_parameters' if your survey or experiment can retrieve and store those parameters for your analysis.\n\nUse 'not_required' if you don't need to record them."},"completion_codes":{"type":"array","items":{"$ref":"#/components/schemas/CreateStudyCompletionCodesItems"},"description":"Specify at least one completion code for your study. A participant will enter one of these codes when they complete your study.\n\nEach code must be unique within a study.\n\nYou can specify as many actions as you like per code. However, some actions can't be used together (e.g. AutomaticallyApprove and ManuallyReview).\n\n**Note:** This field is optional when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH` or `AI_TASK_BUILDER_COLLECTION`. When omitted, a default COMPLETED code with a `MANUALLY_REVIEW` action is auto-generated. When provided, AITB studies must include exactly one code with `code_type` of `COMPLETED` and an action of `MANUALLY_REVIEW` or `AUTOMATICALLY_APPROVE`."},"total_available_places":{"type":"number","format":"double","minimum":1,"description":"How many participants are you looking to recruit.\n\n**Note:** This field is optional when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH`, as the total available places are automatically calculated from the batch configuration."},"estimated_completion_time":{"type":"integer","minimum":1,"description":"Estimated duration in minutes of the experiment or survey"},"maximum_allowed_time":{"type":"number","format":"double","description":"Max time in minutes for a participant to finish the submission. Submissions are timed out if it takes longer.\n\nIf it is not provided the default value is set to the max value.\n\nThe min value is calculated as two minutes plus two times the estimated time plus two times the square root of the estimated time"},"reward":{"type":"number","format":"double","description":"How much are you going to pay the participants in cents. We\nuse the currency of your account."},"device_compatibility":{"type":"array","items":{"$ref":"#/components/schemas/CreateStudyDeviceCompatibilityItems"},"description":"Add all devices that participants can use.\nYou can include one or more options.\n\nAn empty array indicates that all options are available."},"peripheral_requirements":{"type":"array","items":{"$ref":"#/components/schemas/CreateStudyPeripheralRequirementsItems"},"description":"Add all requirements that participants have to meet.\n\nAn empty array indicates that there are no extra peripheral requirements."},"filters":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateStudyFiltersItems"},"description":"Array of filters.\n\nFor advanced participant targeting with `and` / `or` groups, see [Advanced filtering](/api-reference/filters/advanced-filtering).\n\nUse empty array for \"Everyone\""},"filter_set_id":{"type":["string","null"],"description":"The ID of a filter set, from which filters for the study will be taken.\n\nFor more information, see [Filter Sets](/api-reference/filter-sets).\n\nNote, this cannot be used in combination with additional filters via the `filters` field."},"filter_set_version":{"type":["integer","null"],"description":"The version of the filter set to be used.\n\nIf not provided, this will default to the latest available version at the time of applying the filter set."},"naivety_distribution_rate":{"type":["number","null"],"format":"double","minimum":0,"maximum":1,"description":"Control the balance between speed of your studies and the naivety of the participants.\n\nIf not defined, by default Prolific calculates the best rate for most studies\ntaking into account the `filters` and the `total_available_places` needed for this study.\n\nUse 0 if your priority is speed. When this property is set to 0 all eligible participants will have access\nto your study at the same time, without any prioritization.\n\nYou can also set this at a workspace and project level.","deprecated":true},"project":{"type":"string","description":"Project ID. When you don't specify a project in your request, Prolific automatically uses your first created project as the default. For clarity, we recommend explicitly including the project ID in your requests."},"submissions_config":{"$ref":"#/components/schemas/CreateStudySubmissionsConfig","description":"**Advanced**: This helps with faster data collection. Your survey system will need to handle providing a\nunique experience each time the participant takes the study.\n\nConfiguration related to study submissions. The purpose of this field is to capture any configuration options that impact the submissions made by participants in a study."},"study_labels":{"type":"array","items":{"$ref":"#/components/schemas/CreateStudyStudyLabelsItems"},"description":"This field allows you to tag studies with information about the type/topic of the study and the kind of work involved in completing it.\n\nWe plan to make this information available to participants for easier self-selection. At present these options are mutually exclusive and only a single option can be selected, however in the future available categories will expand."},"content_warnings":{"type":"array","items":{"$ref":"#/components/schemas/CreateStudyContentWarningsItems"},"description":"Allow researchers to define content warnings for their study.\n\nAt present these options are mutually exclusive and only a single option can be selected, however in the future available warnings will expand."},"content_warning_details":{"type":"string","maxLength":1000,"description":"Allow researchers to add further details about their content warning."},"metadata":{"type":["string","null"],"description":"This field can be used to store extra information required for a system integration.\nFor example, it could be some JSON, XML, an integer, or a string.\n\nExamples could include:\n\n - `123345` - An ID from your system, that helps with linkage when returning the study.\n - `{ \\\"id\\\": \\\"45\\\", \\\"type\\\": \\\"finance\\\"}` - Some JSON that you want to store."},"credential_pool_id":{"type":["string","null"],"description":"The ID of the credential pool to associate with this study. Credential pools contain\nusername/password pairs that are distributed to participants when they start the study.\n\nWhen provided, participants will be assigned unique credentials from the pool. Each\ncredential can only be used once and is tracked throughout the study lifecycle.\n\n**Note:** The credential pool must:\n- Exist and belong to the study's workspace\n- Have available (unredeemed) credentials\n\nSee the [Credentials endpoints](#tag/Credentials) for managing credential pools."},"has_credentials":{"type":"boolean","description":"Indicates whether this study requires participants to use credentials. This field is\nautomatically set to `true` when a `credential_pool_id` is provided, and `false` when\nthe credential pool is removed.\n\n**Note:** This field is automatically managed based on the `credential_pool_id` field\nand does not need to be set manually."},"data_collection_method":{"oneOf":[{"$ref":"#/components/schemas/CreateStudyDataCollectionMethod"},{"type":"null"}],"description":"**Optional.** Specifies the data collection method for the study.\n\n- `AI_TASK_BUILDER_BATCH`: Use AI Task Builder for data annotation tasks.\n- `AI_TASK_BUILDER_COLLECTION`: Use AI Task Builder for data collection tasks.\n\n**Note:** This field is mutually exclusive with `external_study_url` and `access_details`. If not provided, you must specify one of those fields instead."},"data_collection_id":{"type":["string","null"],"description":"The ID of the data collection batch or project from the Task Builder API.\n\n**Required when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH` or `AI_TASK_BUILDER_COLLECTION`.**"},"data_collection_metadata":{"oneOf":[{"$ref":"#/components/schemas/CreateStudyDataCollectionMetadata"},{"type":"null"}],"description":"**Optional.** Additional metadata for configuring AI Task Builder data annotation behavior. Only used when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH`.\n\n**Properties:**\n\n- `annotators_per_task` (integer): Number of annotators per task. **This field must be provided if you want multiple annotators per task.** Without this field, the default value of 1 will be used.\n - Minimum: 1\n - Default: 1 (if not provided)\n\n**Example:**\n```json\n{\n \"annotators_per_task\": 5\n}\n```\n\n**Important:** You must include `annotators_per_task` to control how many participants annotate each task. After the study is published, this value can only be increased (not decreased), which will increase the total available places on the study."},"access_details":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateStudyAccessDetailsItems"},"description":"Array of access_details, which integrates with taskflow.\n\nWhile this field is nullable, you must provide one of `access_details` or `external_study_url`.\n\nThe sum of all access_details must add to the `total_available_places` field, however the values can be different for an individual access_detail."},"is_external_study_url_secure":{"type":"boolean","description":"When set to true, any query parameters in the external study url will be signed with a JSON Web Token. The token will be added to the URL as a query parameter named `prolific_token`.\n\nThis feature is only available to certain workspaces.\n\n**The JWT payload**\n\nHeader:\n\n```json\n{\n \"alg\": \"RS256\",\n \"kid\": \"\",\n \"typ\": \"JWT\"\n}\n```\n\nWhere\n- alg is always RS256.\n- kid indicates the key ID that was used to secure the JWT.\n- typ is always JWT.\n\nPayload:\n\n```json\n{\n \"iss\": \"https://www.prolific.com\",\n \"iat\": ,\n \"exp\": ,\n \"aud\": \"\",\n \"sub\": \"\",\n \"prolific\":{\n \"\": \"\",\n \"\": \"\",\n ...\n \"workspace_id\": \"\",\n \"organisation_id\": \"\"\n }\n}\n```\n\n`` appears only when the workspace is linked to an\norganisation; otherwise omit that key from `prolific`.\n\nThe `prolific` object always includes the fixed keys `PROLIFIC_PID`,\n`STUDY_ID`, and `SESSION_ID` with the participant, study, and session\nidentifiers. When the workspace is linked to an organisation, \n`organisation_id` (string) is also present.\n\nFor example (the sample below includes `organisation_id`; that key\nis omitted when the workspace has no linked organisation):\n\n```json\n{\n \"iss\": \"https://www.prolific.com\",\n \"iat\": 1740496135,\n \"exp\": 1740496255,\n \"aud\": \"https://x.com?STUDY_ID=1&...\",\n \"sub\": \"1234\",\n \"prolific\":{\n \"STUDY_ID\": \"abcd\",\n \"SESSION_ID\": \"1234\",\n \"PROLIFIC_PID\": \"xyz\",\n \"workspace_id\": \"507f1f77bcf86cd799439011\",\n \"organisation_id\": \"507f191e810c19729de860ea\"\n }\n}\n```\n\n**Verify the payload**\n\nWhen you receive the JWT, you must verify the following:\n- The JWT signature is authentic by verifying it with the public key from Prolific that correlates with the KID. The public keys can be retrieved from [/.well-known/study/jwks.json](#tag/Well-Known-Endpoints/paths/~1.well-known~1study~1jwks.json/get).\n- The JWT hasn't expired, by checking the `exp` claim.\n- The `aud` claim is the correct domain for your tool.\n- The `prolific` claim matches your expected payload as set in the `external_study_url` property. It always includes `PROLIFIC_PID`, `STUDY_ID`, `SESSION_ID`, and `workspace_id`. When the workspace is linked to an organisation, it also includes `organisation_id` (validate all of these against what your integration expects)."}},"required":["name","description","external_study_url","prolific_id_option","total_available_places","estimated_completion_time","reward"],"title":"CreateStudy"},"StudyStatus":{"type":"string","enum":["UNPUBLISHED","SCHEDULED","PUBLISHING","ACTIVE","AWAITING REVIEW","PAUSED","COMPLETED"],"description":"Status of the study. **Read only**.\n\nTo change the status you can use `/api/v1/studies/{id}/transition/`","title":"StudyStatus"},"Study":{"type":"object","properties":{"name":{"type":"string","description":"Public name or title of the study"},"internal_name":{"type":["string","null"],"description":"Internal name of the study, not shown to participants"},"description":{"type":"string","description":"Description of the study for the participants to read before\nstarting the study\n\n**Supported HTML in `description`**\n\nThe `description` field supports the following HTML tags for formatting participant instructions:\n\n* `` - bold\n* `` - italic\n* `` - emphasized text\n* `` - strong importance\n* `` - strikethrough\n* `` - underline\n* `

      ` - heading level 1\n* `

      ` - heading level 2\n* `
        ` - ordered list\n* `
          ` - unordered list\n* `
        • ` - list item\n* `

          ` - paragraph\n\nOther HTML tags will be stripped or escaped. Please ensure that you only use supported tags for formatting to avoid rendering issues."},"external_study_url":{"type":"string","description":"URL of the survey or experiment you want participant to access. You can pass URL search parameters to your survey or experiment\n\n* Participant id {{%PROLIFIC_PID%}}\n* Study id {{%STUDY_ID%}}\n* Session id {{%SESSION_ID%}}\n\nFor example `https://eggs-experriment.com?participant={{%PROLIFIC_PID%}}`"},"prolific_id_option":{"$ref":"#/components/schemas/CreateStudyProlificIdOption","description":"Use 'question' if you will add a question in your survey or experiment asking the participant ID\n\n**Recommended** Use 'url_parameters' if your survey or experiment can retrieve and store those parameters for your analysis.\n\nUse 'not_required' if you don't need to record them."},"completion_codes":{"type":"array","items":{"$ref":"#/components/schemas/CreateStudyCompletionCodesItems"},"description":"Specify at least one completion code for your study. A participant will enter one of these codes when they complete your study.\n\nEach code must be unique within a study.\n\nYou can specify as many actions as you like per code. However, some actions can't be used together (e.g. AutomaticallyApprove and ManuallyReview).\n\n**Note:** This field is optional when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH` or `AI_TASK_BUILDER_COLLECTION`. When omitted, a default COMPLETED code with a `MANUALLY_REVIEW` action is auto-generated. When provided, AITB studies must include exactly one code with `code_type` of `COMPLETED` and an action of `MANUALLY_REVIEW` or `AUTOMATICALLY_APPROVE`."},"total_available_places":{"type":"number","format":"double","minimum":1,"description":"How many participants are you looking to recruit.\n\n**Note:** This field is optional when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH`, as the total available places are automatically calculated from the batch configuration."},"estimated_completion_time":{"type":"integer","minimum":1,"description":"Estimated duration in minutes of the experiment or survey"},"maximum_allowed_time":{"type":"number","format":"double","description":"Max time in minutes for a participant to finish the submission. Submissions are timed out if it takes longer.\n\nIf it is not provided the default value is set to the max value.\n\nThe min value is calculated as two minutes plus two times the estimated time plus two times the square root of the estimated time"},"reward":{"type":"number","format":"double","description":"How much are you going to pay the participants in cents. We\nuse the currency of your account."},"device_compatibility":{"type":"array","items":{"$ref":"#/components/schemas/CreateStudyDeviceCompatibilityItems"},"description":"Add all devices that participants can use.\nYou can include one or more options.\n\nAn empty array indicates that all options are available."},"peripheral_requirements":{"type":"array","items":{"$ref":"#/components/schemas/CreateStudyPeripheralRequirementsItems"},"description":"Add all requirements that participants have to meet.\n\nAn empty array indicates that there are no extra peripheral requirements."},"filters":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateStudyFiltersItems"},"description":"Array of filters.\n\nFor advanced participant targeting with `and` / `or` groups, see [Advanced filtering](/api-reference/filters/advanced-filtering).\n\nUse empty array for \"Everyone\""},"filter_set_id":{"type":["string","null"],"description":"The ID of a filter set, from which filters for the study will be taken.\n\nFor more information, see [Filter Sets](/api-reference/filter-sets).\n\nNote, this cannot be used in combination with additional filters via the `filters` field."},"filter_set_version":{"type":["integer","null"],"description":"The version of the filter set to be used.\n\nIf not provided, this will default to the latest available version at the time of applying the filter set."},"naivety_distribution_rate":{"type":["number","null"],"format":"double","minimum":0,"maximum":1,"description":"Control the balance between speed of your studies and the naivety of the participants.\n\nIf not defined, by default Prolific calculates the best rate for most studies\ntaking into account the `filters` and the `total_available_places` needed for this study.\n\nUse 0 if your priority is speed. When this property is set to 0 all eligible participants will have access\nto your study at the same time, without any prioritization.\n\nYou can also set this at a workspace and project level.","deprecated":true},"project":{"type":"string","description":"Project ID. When you don't specify a project in your request, Prolific automatically uses your first created project as the default. For clarity, we recommend explicitly including the project ID in your requests."},"submissions_config":{"$ref":"#/components/schemas/CreateStudySubmissionsConfig","description":"**Advanced**: This helps with faster data collection. Your survey system will need to handle providing a\nunique experience each time the participant takes the study.\n\nConfiguration related to study submissions. The purpose of this field is to capture any configuration options that impact the submissions made by participants in a study."},"study_labels":{"type":"array","items":{"$ref":"#/components/schemas/CreateStudyStudyLabelsItems"},"description":"This field allows you to tag studies with information about the type/topic of the study and the kind of work involved in completing it.\n\nWe plan to make this information available to participants for easier self-selection. At present these options are mutually exclusive and only a single option can be selected, however in the future available categories will expand."},"content_warnings":{"type":"array","items":{"$ref":"#/components/schemas/CreateStudyContentWarningsItems"},"description":"Allow researchers to define content warnings for their study.\n\nAt present these options are mutually exclusive and only a single option can be selected, however in the future available warnings will expand."},"content_warning_details":{"type":"string","maxLength":1000,"description":"Allow researchers to add further details about their content warning."},"metadata":{"type":["string","null"],"description":"This field can be used to store extra information required for a system integration.\nFor example, it could be some JSON, XML, an integer, or a string.\n\nExamples could include:\n\n - `123345` - An ID from your system, that helps with linkage when returning the study.\n - `{ \\\"id\\\": \\\"45\\\", \\\"type\\\": \\\"finance\\\"}` - Some JSON that you want to store."},"credential_pool_id":{"type":["string","null"],"description":"The ID of the credential pool to associate with this study. Credential pools contain\nusername/password pairs that are distributed to participants when they start the study.\n\nWhen provided, participants will be assigned unique credentials from the pool. Each\ncredential can only be used once and is tracked throughout the study lifecycle.\n\n**Note:** The credential pool must:\n- Exist and belong to the study's workspace\n- Have available (unredeemed) credentials\n\nSee the [Credentials endpoints](#tag/Credentials) for managing credential pools."},"has_credentials":{"type":"boolean","description":"Indicates whether this study requires participants to use credentials. This field is\nautomatically set to `true` when a `credential_pool_id` is provided, and `false` when\nthe credential pool is removed.\n\n**Note:** This field is automatically managed based on the `credential_pool_id` field\nand does not need to be set manually."},"data_collection_method":{"oneOf":[{"$ref":"#/components/schemas/CreateStudyDataCollectionMethod"},{"type":"null"}],"description":"**Optional.** Specifies the data collection method for the study.\n\n- `AI_TASK_BUILDER_BATCH`: Use AI Task Builder for data annotation tasks.\n- `AI_TASK_BUILDER_COLLECTION`: Use AI Task Builder for data collection tasks.\n\n**Note:** This field is mutually exclusive with `external_study_url` and `access_details`. If not provided, you must specify one of those fields instead."},"data_collection_id":{"type":["string","null"],"description":"The ID of the data collection batch or project from the Task Builder API.\n\n**Required when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH` or `AI_TASK_BUILDER_COLLECTION`.**"},"data_collection_metadata":{"oneOf":[{"$ref":"#/components/schemas/CreateStudyDataCollectionMetadata"},{"type":"null"}],"description":"**Optional.** Additional metadata for configuring AI Task Builder data annotation behavior. Only used when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH`.\n\n**Properties:**\n\n- `annotators_per_task` (integer): Number of annotators per task. **This field must be provided if you want multiple annotators per task.** Without this field, the default value of 1 will be used.\n - Minimum: 1\n - Default: 1 (if not provided)\n\n**Example:**\n```json\n{\n \"annotators_per_task\": 5\n}\n```\n\n**Important:** You must include `annotators_per_task` to control how many participants annotate each task. After the study is published, this value can only be increased (not decreased), which will increase the total available places on the study."},"access_details":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateStudyAccessDetailsItems"},"description":"Array of access_details, which integrates with taskflow.\n\nWhile this field is nullable, you must provide one of `access_details` or `external_study_url`.\n\nThe sum of all access_details must add to the `total_available_places` field, however the values can be different for an individual access_detail."},"is_external_study_url_secure":{"type":"boolean","description":"When set to true, any query parameters in the external study url will be signed with a JSON Web Token. The token will be added to the URL as a query parameter named `prolific_token`.\n\nThis feature is only available to certain workspaces.\n\n**The JWT payload**\n\nHeader:\n\n```json\n{\n \"alg\": \"RS256\",\n \"kid\": \"\",\n \"typ\": \"JWT\"\n}\n```\n\nWhere\n- alg is always RS256.\n- kid indicates the key ID that was used to secure the JWT.\n- typ is always JWT.\n\nPayload:\n\n```json\n{\n \"iss\": \"https://www.prolific.com\",\n \"iat\": ,\n \"exp\": ,\n \"aud\": \"\",\n \"sub\": \"\",\n \"prolific\":{\n \"\": \"\",\n \"\": \"\",\n ...\n \"workspace_id\": \"\",\n \"organisation_id\": \"\"\n }\n}\n```\n\n`` appears only when the workspace is linked to an\norganisation; otherwise omit that key from `prolific`.\n\nThe `prolific` object always includes the fixed keys `PROLIFIC_PID`,\n`STUDY_ID`, and `SESSION_ID` with the participant, study, and session\nidentifiers. When the workspace is linked to an organisation, \n`organisation_id` (string) is also present.\n\nFor example (the sample below includes `organisation_id`; that key\nis omitted when the workspace has no linked organisation):\n\n```json\n{\n \"iss\": \"https://www.prolific.com\",\n \"iat\": 1740496135,\n \"exp\": 1740496255,\n \"aud\": \"https://x.com?STUDY_ID=1&...\",\n \"sub\": \"1234\",\n \"prolific\":{\n \"STUDY_ID\": \"abcd\",\n \"SESSION_ID\": \"1234\",\n \"PROLIFIC_PID\": \"xyz\",\n \"workspace_id\": \"507f1f77bcf86cd799439011\",\n \"organisation_id\": \"507f191e810c19729de860ea\"\n }\n}\n```\n\n**Verify the payload**\n\nWhen you receive the JWT, you must verify the following:\n- The JWT signature is authentic by verifying it with the public key from Prolific that correlates with the KID. The public keys can be retrieved from [/.well-known/study/jwks.json](#tag/Well-Known-Endpoints/paths/~1.well-known~1study~1jwks.json/get).\n- The JWT hasn't expired, by checking the `exp` claim.\n- The `aud` claim is the correct domain for your tool.\n- The `prolific` claim matches your expected payload as set in the `external_study_url` property. It always includes `PROLIFIC_PID`, `STUDY_ID`, `SESSION_ID`, and `workspace_id`. When the workspace is linked to an organisation, it also includes `organisation_id` (validate all of these against what your integration expects)."},"id":{"type":"string","description":"Study id. It is created by Prolific. **Read only**."},"status":{"$ref":"#/components/schemas/StudyStatus","description":"Status of the study. **Read only**.\n\nTo change the status you can use `/api/v1/studies/{id}/transition/`"},"is_ready_to_publish":{"type":"boolean","description":"Whether the study has all required fields completed for publishing. Does not check wallet balance or funding — only study-level field completeness."}},"required":["name","description","external_study_url","prolific_id_option","total_available_places","estimated_completion_time","reward"],"title":"Study"},"Studies_DeleteStudy_Response_200":{"type":"object","properties":{},"description":"Empty response body","title":"Studies_DeleteStudy_Response_200"},"BaseStudyProlificIdOption":{"type":"string","enum":["question","url_parameters","not_required"],"description":"Use 'question' if you will add a question in your survey or experiment asking the participant ID\n\n**Recommended** Use 'url_parameters' if your survey or experiment can retrieve and store those parameters for your analysis.\n\nUse 'not_required' if you don't need to record them.","title":"BaseStudyProlificIdOption"},"BaseStudyCompletionCodesItemsCodeType":{"type":"string","enum":["COMPLETED","FAILED_ATTENTION_CHECK","FOLLOW_UP_STUDY","GIVE_BONUS","INCOMPATIBLE_DEVICE","NO_CONSENT","OTHER","FIXED_SCREENOUT","SCREENED_IN","SCREENED_OUT"],"description":"A name for your code to make it easier to understand its intention. Either use one of the predefined options or any other free text.\n","title":"BaseStudyCompletionCodesItemsCodeType"},"BaseStudyCompletionCodesItemsActionsItems":{"oneOf":[{"$ref":"#/components/schemas/AutomaticallyApprove"},{"$ref":"#/components/schemas/AddToParticipantGroup"},{"$ref":"#/components/schemas/RemoveFromParticipantGroup"},{"$ref":"#/components/schemas/ManuallyReview"},{"$ref":"#/components/schemas/RequestReturn"},{"$ref":"#/components/schemas/DynamicPayment"},{"$ref":"#/components/schemas/FixedScreenOut"}],"title":"BaseStudyCompletionCodesItemsActionsItems"},"BaseStudyCompletionCodesItemsActor":{"type":"string","enum":["participant","researcher"],"default":"participant","description":"The actor that can provide this completion code.","title":"BaseStudyCompletionCodesItemsActor"},"BaseStudyCompletionCodesItems":{"type":"object","properties":{"code":{"type":["string","null"],"description":"The code the participant will either enter manually at the end of your study or be redirected as part of the return URL.\n\nIf the code is null, then the participant will not be asked to submit a completion code when they return to Prolific.\nNull codes can only be provided when:\n - The actor is \"participant\"\n - There are no other completion codes with the \"participant\" actor\n - The actions array is empty\n\nThe code must be unique within the study.\n"},"code_type":{"$ref":"#/components/schemas/BaseStudyCompletionCodesItemsCodeType","description":"A name for your code to make it easier to understand its intention. Either use one of the predefined options or any other free text.\n"},"actions":{"type":"array","items":{"$ref":"#/components/schemas/BaseStudyCompletionCodesItemsActionsItems"},"description":"The actions that will be completed automatically when the submission is completed with this code by the participant.\n\nYou have the ability to use one or multiple `actions` together - it's up to you and your desired automated journey.\n\nIf you’re looking to keep things simple, we recommend setting the `{\"action\": \"MANUALLY_REVIEW\"}` option only, so all submissions wait for your manual approval."},"actor":{"$ref":"#/components/schemas/BaseStudyCompletionCodesItemsActor","default":"participant","description":"The actor that can provide this completion code."}},"required":["code","code_type","actions"],"title":"BaseStudyCompletionCodesItems"},"BaseStudyDeviceCompatibilityItems":{"type":"string","enum":["desktop","tablet","mobile"],"title":"BaseStudyDeviceCompatibilityItems"},"BaseStudyPeripheralRequirementsItems":{"type":"string","enum":["audio","camera","download","microphone"],"title":"BaseStudyPeripheralRequirementsItems"},"BaseStudyFiltersItems":{"oneOf":[{"$ref":"#/components/schemas/SelectFilter"},{"$ref":"#/components/schemas/RangeFilter"},{"$ref":"#/components/schemas/CompositeFilter"}],"title":"BaseStudyFiltersItems"},"BaseStudySubmissionsConfigAutoRejectionCategoriesItems":{"type":"string","enum":["EXCEPTIONALLY_FAST"],"title":"BaseStudySubmissionsConfigAutoRejectionCategoriesItems"},"BaseStudySubmissionsConfig":{"type":"object","properties":{"max_submissions_per_participant":{"type":["integer","null"],"default":1,"description":"- **1** is the default Prolific experience. This means one submission, per participant, per study. If you do\n not specify this field, the **default is 1**.\n- **1+** turns your study into a multi-submission study, meaning a participant can create many submissions per study.\n As noted above, your survey system will need to handle providing a\nunique experience each time the participant takes the study.\n- **-1** will allow an indefinite number of submissions from a single participant, up to `total_available_places`."},"max_concurrent_submissions":{"type":["integer","null"],"default":-1,"description":"- **-1** is the default value, meaning unlimited concurrent active/reserved submissions per study.\n- **1+** limits the number of concurrent active/reserved submissions a study can have at one time."},"auto_rejection_categories":{"type":"array","items":{"$ref":"#/components/schemas/BaseStudySubmissionsConfigAutoRejectionCategoriesItems"},"default":[],"description":"List of rejection categories that trigger automatic submission rejections.\n\n**Available Categories:**\n- **EXCEPTIONALLY_FAST**: Automatically reject submissions completed in an exceptionally short time\n\n**Important Notes:**\n- **This feature is currently in an evaluation period and can be activated for your workspace upon request.**\n- Auto-rejections only apply to submissions in \"AWAITING REVIEW\" status\n- Submissions with return requests will not be auto-rejected\n- Auto-rejected submissions do not count towards your rejection limit\n- Set to an empty array `[]` or omit this field to disable auto-rejection"}},"description":"**Advanced**: This helps with faster data collection. Your survey system will need to handle providing a\nunique experience each time the participant takes the study.\n\nConfiguration related to study submissions. The purpose of this field is to capture any configuration options that impact the submissions made by participants in a study.","title":"BaseStudySubmissionsConfig"},"BaseStudyStudyLabelsItems":{"type":"string","enum":["survey","writing_task","annotation","decision_making_task","interview","other","ai_annotation","ai_evaluation","ai_reasoning","ai_fact_checking","ai_safety","ai_data_creation_text","ai_data_creation_audio","ai_data_creation_video","ai_data_creation_images","ai_other"],"title":"BaseStudyStudyLabelsItems"},"BaseStudyContentWarningsItems":{"type":"string","enum":["sensitive","explicit"],"title":"BaseStudyContentWarningsItems"},"BaseStudyDataCollectionMethod":{"type":"string","enum":["AI_TASK_BUILDER_BATCH","AI_TASK_BUILDER_COLLECTION"],"description":"**Optional.** Specifies the data collection method for the study.\n\n- `AI_TASK_BUILDER_BATCH`: Use AI Task Builder for data annotation tasks.\n- `AI_TASK_BUILDER_COLLECTION`: Use AI Task Builder for data collection tasks.\n\n**Note:** This field is mutually exclusive with `external_study_url` and `access_details`. If not provided, you must specify one of those fields instead.","title":"BaseStudyDataCollectionMethod"},"BaseStudyDataCollectionMetadata":{"type":"object","properties":{"annotators_per_task":{"type":"integer","minimum":1,"description":"Number of annotators required per task. Required for AI Task Builder Batch studies to set multiple annotators."}},"description":"**Optional.** Additional metadata for configuring AI Task Builder data annotation behavior. Only used when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH`.\n\n**Properties:**\n\n- `annotators_per_task` (integer): Number of annotators per task. **This field must be provided if you want multiple annotators per task.** Without this field, the default value of 1 will be used.\n - Minimum: 1\n - Default: 1 (if not provided)\n\n**Example:**\n```json\n{\n \"annotators_per_task\": 5\n}\n```\n\n**Important:** You must include `annotators_per_task` to control how many participants annotate each task. After the study is published, this value can only be increased (not decreased), which will increase the total available places on the study.","title":"BaseStudyDataCollectionMetadata"},"BaseStudyAccessDetailsItems":{"oneOf":[{"$ref":"#/components/schemas/AccessDetail"}],"title":"BaseStudyAccessDetailsItems"},"BaseStudy":{"type":"object","properties":{"name":{"type":"string","description":"Public name or title of the study"},"internal_name":{"type":["string","null"],"description":"Internal name of the study, not shown to participants"},"description":{"type":"string","description":"Description of the study for the participants to read before\nstarting the study\n\n**Supported HTML in `description`**\n\nThe `description` field supports the following HTML tags for formatting participant instructions:\n\n* `` - bold\n* `` - italic\n* `` - emphasized text\n* `` - strong importance\n* `` - strikethrough\n* `` - underline\n* `

          ` - heading level 1\n* `

          ` - heading level 2\n* `
            ` - ordered list\n* `
              ` - unordered list\n* `
            • ` - list item\n* `

              ` - paragraph\n\nOther HTML tags will be stripped or escaped. Please ensure that you only use supported tags for formatting to avoid rendering issues."},"external_study_url":{"type":"string","description":"URL of the survey or experiment you want participant to access. You can pass URL search parameters to your survey or experiment\n\n* Participant id {{%PROLIFIC_PID%}}\n* Study id {{%STUDY_ID%}}\n* Session id {{%SESSION_ID%}}\n\nFor example `https://eggs-experriment.com?participant={{%PROLIFIC_PID%}}`"},"prolific_id_option":{"$ref":"#/components/schemas/BaseStudyProlificIdOption","description":"Use 'question' if you will add a question in your survey or experiment asking the participant ID\n\n**Recommended** Use 'url_parameters' if your survey or experiment can retrieve and store those parameters for your analysis.\n\nUse 'not_required' if you don't need to record them."},"completion_codes":{"type":"array","items":{"$ref":"#/components/schemas/BaseStudyCompletionCodesItems"},"description":"Specify at least one completion code for your study. A participant will enter one of these codes when they complete your study.\n\nEach code must be unique within a study.\n\nYou can specify as many actions as you like per code. However, some actions can't be used together (e.g. AutomaticallyApprove and ManuallyReview).\n\n**Note:** This field is optional when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH` or `AI_TASK_BUILDER_COLLECTION`. When omitted, a default COMPLETED code with a `MANUALLY_REVIEW` action is auto-generated. When provided, AITB studies must include exactly one code with `code_type` of `COMPLETED` and an action of `MANUALLY_REVIEW` or `AUTOMATICALLY_APPROVE`."},"total_available_places":{"type":"number","format":"double","minimum":1,"description":"How many participants are you looking to recruit.\n\n**Note:** This field is optional when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH`, as the total available places are automatically calculated from the batch configuration."},"estimated_completion_time":{"type":"integer","minimum":1,"description":"Estimated duration in minutes of the experiment or survey"},"maximum_allowed_time":{"type":"number","format":"double","description":"Max time in minutes for a participant to finish the submission. Submissions are timed out if it takes longer.\n\nIf it is not provided the default value is set to the max value.\n\nThe min value is calculated as two minutes plus two times the estimated time plus two times the square root of the estimated time"},"reward":{"type":"number","format":"double","description":"How much are you going to pay the participants in cents. We\nuse the currency of your account."},"device_compatibility":{"type":"array","items":{"$ref":"#/components/schemas/BaseStudyDeviceCompatibilityItems"},"description":"Add all devices that participants can use.\nYou can include one or more options.\n\nAn empty array indicates that all options are available."},"peripheral_requirements":{"type":"array","items":{"$ref":"#/components/schemas/BaseStudyPeripheralRequirementsItems"},"description":"Add all requirements that participants have to meet.\n\nAn empty array indicates that there are no extra peripheral requirements."},"filters":{"type":["array","null"],"items":{"$ref":"#/components/schemas/BaseStudyFiltersItems"},"description":"Array of filters.\n\nFor advanced participant targeting with `and` / `or` groups, see [Advanced filtering](/api-reference/filters/advanced-filtering).\n\nUse empty array for \"Everyone\""},"filter_set_id":{"type":["string","null"],"description":"The ID of a filter set, from which filters for the study will be taken.\n\nFor more information, see [Filter Sets](/api-reference/filter-sets).\n\nNote, this cannot be used in combination with additional filters via the `filters` field."},"filter_set_version":{"type":["integer","null"],"description":"The version of the filter set to be used.\n\nIf not provided, this will default to the latest available version at the time of applying the filter set."},"naivety_distribution_rate":{"type":["number","null"],"format":"double","minimum":0,"maximum":1,"description":"Control the balance between speed of your studies and the naivety of the participants.\n\nIf not defined, by default Prolific calculates the best rate for most studies\ntaking into account the `filters` and the `total_available_places` needed for this study.\n\nUse 0 if your priority is speed. When this property is set to 0 all eligible participants will have access\nto your study at the same time, without any prioritization.\n\nYou can also set this at a workspace and project level.","deprecated":true},"project":{"type":"string","description":"Project ID. When you don't specify a project in your request, Prolific automatically uses your first created project as the default. For clarity, we recommend explicitly including the project ID in your requests."},"submissions_config":{"$ref":"#/components/schemas/BaseStudySubmissionsConfig","description":"**Advanced**: This helps with faster data collection. Your survey system will need to handle providing a\nunique experience each time the participant takes the study.\n\nConfiguration related to study submissions. The purpose of this field is to capture any configuration options that impact the submissions made by participants in a study."},"study_labels":{"type":"array","items":{"$ref":"#/components/schemas/BaseStudyStudyLabelsItems"},"description":"This field allows you to tag studies with information about the type/topic of the study and the kind of work involved in completing it.\n\nWe plan to make this information available to participants for easier self-selection. At present these options are mutually exclusive and only a single option can be selected, however in the future available categories will expand."},"content_warnings":{"type":"array","items":{"$ref":"#/components/schemas/BaseStudyContentWarningsItems"},"description":"Allow researchers to define content warnings for their study.\n\nAt present these options are mutually exclusive and only a single option can be selected, however in the future available warnings will expand."},"content_warning_details":{"type":"string","maxLength":1000,"description":"Allow researchers to add further details about their content warning."},"metadata":{"type":["string","null"],"description":"This field can be used to store extra information required for a system integration.\nFor example, it could be some JSON, XML, an integer, or a string.\n\nExamples could include:\n\n - `123345` - An ID from your system, that helps with linkage when returning the study.\n - `{ \\\"id\\\": \\\"45\\\", \\\"type\\\": \\\"finance\\\"}` - Some JSON that you want to store."},"credential_pool_id":{"type":["string","null"],"description":"The ID of the credential pool to associate with this study. Credential pools contain\nusername/password pairs that are distributed to participants when they start the study.\n\nWhen provided, participants will be assigned unique credentials from the pool. Each\ncredential can only be used once and is tracked throughout the study lifecycle.\n\n**Note:** The credential pool must:\n- Exist and belong to the study's workspace\n- Have available (unredeemed) credentials\n\nSee the [Credentials endpoints](#tag/Credentials) for managing credential pools."},"has_credentials":{"type":"boolean","description":"Indicates whether this study requires participants to use credentials. This field is\nautomatically set to `true` when a `credential_pool_id` is provided, and `false` when\nthe credential pool is removed.\n\n**Note:** This field is automatically managed based on the `credential_pool_id` field\nand does not need to be set manually."},"data_collection_method":{"oneOf":[{"$ref":"#/components/schemas/BaseStudyDataCollectionMethod"},{"type":"null"}],"description":"**Optional.** Specifies the data collection method for the study.\n\n- `AI_TASK_BUILDER_BATCH`: Use AI Task Builder for data annotation tasks.\n- `AI_TASK_BUILDER_COLLECTION`: Use AI Task Builder for data collection tasks.\n\n**Note:** This field is mutually exclusive with `external_study_url` and `access_details`. If not provided, you must specify one of those fields instead."},"data_collection_id":{"type":["string","null"],"description":"The ID of the data collection batch or project from the Task Builder API.\n\n**Required when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH` or `AI_TASK_BUILDER_COLLECTION`.**"},"data_collection_metadata":{"oneOf":[{"$ref":"#/components/schemas/BaseStudyDataCollectionMetadata"},{"type":"null"}],"description":"**Optional.** Additional metadata for configuring AI Task Builder data annotation behavior. Only used when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH`.\n\n**Properties:**\n\n- `annotators_per_task` (integer): Number of annotators per task. **This field must be provided if you want multiple annotators per task.** Without this field, the default value of 1 will be used.\n - Minimum: 1\n - Default: 1 (if not provided)\n\n**Example:**\n```json\n{\n \"annotators_per_task\": 5\n}\n```\n\n**Important:** You must include `annotators_per_task` to control how many participants annotate each task. After the study is published, this value can only be increased (not decreased), which will increase the total available places on the study."},"access_details":{"type":["array","null"],"items":{"$ref":"#/components/schemas/BaseStudyAccessDetailsItems"},"description":"Array of access_details, which integrates with taskflow.\n\nWhile this field is nullable, you must provide one of `access_details` or `external_study_url`.\n\nThe sum of all access_details must add to the `total_available_places` field, however the values can be different for an individual access_detail."},"is_external_study_url_secure":{"type":"boolean","description":"When set to true, any query parameters in the external study url will be signed with a JSON Web Token. The token will be added to the URL as a query parameter named `prolific_token`.\n\nThis feature is only available to certain workspaces.\n\n**The JWT payload**\n\nHeader:\n\n```json\n{\n \"alg\": \"RS256\",\n \"kid\": \"\",\n \"typ\": \"JWT\"\n}\n```\n\nWhere\n- alg is always RS256.\n- kid indicates the key ID that was used to secure the JWT.\n- typ is always JWT.\n\nPayload:\n\n```json\n{\n \"iss\": \"https://www.prolific.com\",\n \"iat\": ,\n \"exp\": ,\n \"aud\": \"\",\n \"sub\": \"\",\n \"prolific\":{\n \"\": \"\",\n \"\": \"\",\n ...\n \"workspace_id\": \"\",\n \"organisation_id\": \"\"\n }\n}\n```\n\n`` appears only when the workspace is linked to an\norganisation; otherwise omit that key from `prolific`.\n\nThe `prolific` object always includes the fixed keys `PROLIFIC_PID`,\n`STUDY_ID`, and `SESSION_ID` with the participant, study, and session\nidentifiers. When the workspace is linked to an organisation, \n`organisation_id` (string) is also present.\n\nFor example (the sample below includes `organisation_id`; that key\nis omitted when the workspace has no linked organisation):\n\n```json\n{\n \"iss\": \"https://www.prolific.com\",\n \"iat\": 1740496135,\n \"exp\": 1740496255,\n \"aud\": \"https://x.com?STUDY_ID=1&...\",\n \"sub\": \"1234\",\n \"prolific\":{\n \"STUDY_ID\": \"abcd\",\n \"SESSION_ID\": \"1234\",\n \"PROLIFIC_PID\": \"xyz\",\n \"workspace_id\": \"507f1f77bcf86cd799439011\",\n \"organisation_id\": \"507f191e810c19729de860ea\"\n }\n}\n```\n\n**Verify the payload**\n\nWhen you receive the JWT, you must verify the following:\n- The JWT signature is authentic by verifying it with the public key from Prolific that correlates with the KID. The public keys can be retrieved from [/.well-known/study/jwks.json](#tag/Well-Known-Endpoints/paths/~1.well-known~1study~1jwks.json/get).\n- The JWT hasn't expired, by checking the `exp` claim.\n- The `aud` claim is the correct domain for your tool.\n- The `prolific` claim matches your expected payload as set in the `external_study_url` property. It always includes `PROLIFIC_PID`, `STUDY_ID`, `SESSION_ID`, and `workspace_id`. When the workspace is linked to an organisation, it also includes `organisation_id` (validate all of these against what your integration expects)."}},"title":"BaseStudy"},"StudyTransitionAction":{"type":"string","enum":["PUBLISH","SCHEDULE_PUBLISH","CANCEL_PUBLISH","PAUSE","START","STOP"],"description":"The transition action to execute on the study.","title":"StudyTransitionAction"},"StudyTransition":{"type":"object","properties":{"action":{"$ref":"#/components/schemas/StudyTransitionAction","description":"The transition action to execute on the study."},"publish_at":{"type":"string","format":"date-time","description":"ISO 8601 datetime for when the study should be published. Required in the request when action is SCHEDULE_PUBLISH and the study does not already have a publish_at set."}},"required":["action"],"title":"StudyTransition"},"TestStudySetUpResponse":{"type":"object","properties":{"study_id":{"type":"string","format":"objectId","description":"The ID of the study that was created for the test."},"study_url":{"type":"string","format":"uri","description":"The URL of the study that was created for the test."}},"title":"TestStudySetUpResponse"},"AccessDetailProgress":{"type":"object","properties":{"external_url":{"type":"string","description":"URL of the task you want to send the participant to. You can pass URL search parameters as in `external_study_url`."},"total_allocation":{"type":"number","format":"double","description":"The base number of places set by the researcher for this URL. This is the value used to determine the study's total available places and will match what was submitted when creating or updating the study.\n\nThis value does not include screenout-driven capacity. For studies with custom screening (fixed screen-out reward), `allocated` may exceed `total_allocation` — use `capacity_increments` to understand why."},"allocated":{"type":"number","format":"double","description":"The number of participants currently allocated to this URL.\n\nFor studies with custom screening (fixed screen-out reward), this value may exceed `total_allocation`. This occurs when participants have been screened out — each screenout adds 1 to `capacity_increments`, allowing a replacement participant to be allocated. The relationship is always: `allocated ≤ total_allocation + capacity_increments`."},"capacity_increments":{"type":"number","format":"double","description":"The cumulative number of additional capacity slots added to this URL by screenout events. Each time a participant is screened out, this value increases by 1, allowing a replacement participant to be allocated in their place.\n\nThis field is read-only and system-managed — it cannot be set when creating or updating a study. It will be absent (or 0) for URLs where no screenouts have occurred.\n\n**Example:** If `total_allocation` is 10, `capacity_increments` is 3, and `allocated` is 11, it means 3 participants were screened out, creating 3 extra slots, and 11 participants have been allocated in total — 2 slots remain."}},"required":["external_url","total_allocation"],"title":"AccessDetailProgress"},"StudyAccessDetailsProgress":{"type":"object","properties":{"id":{"type":"string","description":"The access details collection ID for this study's Taskflow configuration."},"progress":{"type":"array","items":{"$ref":"#/components/schemas/AccessDetailProgress"},"description":"One row per `external_url` configured on the study."},"_links":{"type":"object","additionalProperties":{"description":"Any type"},"description":"HAL-style links; typically includes `self` pointing at this endpoint."}},"required":["id","progress"],"title":"StudyAccessDetailsProgress"},"AmountAndCurrency":{"type":"object","properties":{"amount":{"type":"number","format":"double","description":"Amount in subcurrency. £1 will return 100"},"currency":{"type":"string","description":"Currency Code"}},"title":"AmountAndCurrency"},"StudyCostBreakdown":{"type":"object","properties":{"rewards":{"$ref":"#/components/schemas/AmountAndCurrency"},"fees":{"$ref":"#/components/schemas/AmountAndCurrency"},"tax":{"$ref":"#/components/schemas/AmountAndCurrency"}},"title":"StudyCostBreakdown"},"StudyTotalCost":{"type":"object","properties":{"rewards":{"$ref":"#/components/schemas/StudyCostBreakdown"},"bonuses":{"$ref":"#/components/schemas/StudyCostBreakdown"},"_links":{"type":"object","additionalProperties":{"description":"Any type"}}},"title":"StudyTotalCost"},"SubmissionShortStatus":{"type":"string","enum":["RESERVED","ACTIVE","TIMED-OUT","AWAITING REVIEW","APPROVED","RETURNED","REJECTED","SCREENED OUT"],"description":"Status of the submission.","title":"SubmissionShortStatus"},"SubmissionShort":{"type":"object","properties":{"id":{"type":"string","description":"Submission id."},"participant_id":{"type":"string","description":"Participant id."},"status":{"$ref":"#/components/schemas/SubmissionShortStatus","description":"Status of the submission."},"started_at":{"type":"string","format":"date-time","description":"Date started"},"completed_at":{"type":["string","null"],"format":"date-time","description":"Date completed"},"has_siblings":{"type":"boolean","description":"Whether or not the submission has sibling submissions (sharing the same study)."},"study_code":{"type":["string","null"],"description":"The completion code used by the participant to complete the study."},"return_requested":{"type":["string","null"],"format":"date-time","description":"The date and time when a return request for the submission was made."}},"required":["id","participant_id","status","started_at","has_siblings"],"title":"SubmissionShort"},"SubmissionListResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SubmissionShort"},"description":"List of all submissions matching the criteria."}},"required":["results"],"title":"SubmissionListResponse"},"SubmissionsCountResponse":{"type":"object","properties":{"ACTIVE":{"type":"number","format":"double"},"APPROVED":{"type":"number","format":"double"},"AWAITING REVIEW":{"type":"number","format":"double"},"REJECTED":{"type":"number","format":"double"},"RESERVED":{"type":"number","format":"double"},"RETURNED":{"type":"number","format":"double"},"TIMED-OUT":{"type":"number","format":"double"},"PARTIALLY APPROVED":{"type":"number","format":"double"},"SCREENED OUT":{"type":"number","format":"double"},"TOTAL":{"type":"number","format":"double","description":"The total number of submissions in the study."}},"title":"SubmissionsCountResponse"},"DemographicExportRequestFiltersItems":{"oneOf":[{"$ref":"#/components/schemas/SelectFilter"},{"$ref":"#/components/schemas/RangeFilter"},{"$ref":"#/components/schemas/CompositeFilter"}],"title":"DemographicExportRequestFiltersItems"},"DemographicExportRequest":{"type":"object","properties":{"filters":{"type":"array","items":{"$ref":"#/components/schemas/DemographicExportRequestFiltersItems"},"description":"List of filters to apply to the demographic export.\n\nWhen filters are provided, the export includes both base demographic data and responses to the specified filters which were applied to the study.\n\nWhen empty, only base demographic data (age, sex, country, etc.) for all participants who took the study is exported, excluding study-specific filter responses."}},"title":"DemographicExportRequest"},"DemographicExportHistoryResponseFiltersItems":{"oneOf":[{"$ref":"#/components/schemas/SelectFilter"},{"$ref":"#/components/schemas/RangeFilter"},{"$ref":"#/components/schemas/CompositeFilter"}],"title":"DemographicExportHistoryResponseFiltersItems"},"DemographicExportHistoryResponse":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":2,"description":"Total number of different filter combinations that have been requested for demographic export"},"filters":{"type":"array","items":{"$ref":"#/components/schemas/DemographicExportHistoryResponseFiltersItems"},"description":"The filters used in the most recent export request. Returns an empty array if no exports have been requested yet.\n\nThis shows you exactly what filter combination was used in your latest request, helping you track your export usage."}},"required":["count","filters"],"description":"Response containing the latest demographic export request history for a study","title":"DemographicExportHistoryResponse"},"StudyCostRequest":{"type":"object","properties":{"reward":{"type":"number","format":"double","description":"How much are you going to pay the participants in cents. We use the currency of your account"},"total_available_places":{"type":"number","format":"double","description":"How many participants are you looking to recruit"}},"required":["reward","total_available_places"],"title":"StudyCostRequest"},"StudyCostResponse":{"type":"object","properties":{"total_cost":{"type":"number","format":"double","description":"Total cost of the study including VAT and fees in cents. We use your account VAT and Fee percentage. The amount is in your account's currency."}},"required":["total_cost"],"title":"StudyCostResponse"},"SelectFilterListResponseType":{"type":"string","enum":["select","range"],"description":"The filter type.","title":"SelectFilterListResponseType"},"SelectFilterListResponseLifecycleState":{"type":"string","enum":["ACTIVE","DEPRECATED"],"description":"The lifecycle state of this filter. Active filters are visible in filter discovery. Deprecated filters are hidden from discovery but continue to work for existing studies.","title":"SelectFilterListResponseLifecycleState"},"SelectFilterListResponseDataType":{"type":"string","enum":["ChoiceID","ParticipantID","StudyID","ParticipantGroupID"],"description":"The format of the keys in the choices object. If the keys are strings representing sequential integers,\nthe data format is integer. If the keys are database ObjectIDs, the type of ID is specified.","title":"SelectFilterListResponseDataType"},"SelectFilterListResponse":{"type":"object","properties":{"filter_id":{"type":"string","description":"The ID of the filter, based on a slugified version of the title at the time the filter was created."},"title":{"type":"string","description":"The title of the filter."},"description":{"type":"string","description":"A description of the filter."},"type":{"$ref":"#/components/schemas/SelectFilterListResponseType","description":"The filter type."},"question":{"type":"string","description":"The question asked of participants to generate this filter."},"lifecycle_state":{"$ref":"#/components/schemas/SelectFilterListResponseLifecycleState","description":"The lifecycle state of this filter. Active filters are visible in filter discovery. Deprecated filters are hidden from discovery but continue to work for existing studies."},"choices":{"type":"object","additionalProperties":{"description":"Any type"},"description":"An object containing all the filter's possible responses as key-value pairs, with sequential integer IDs or database ObjectIDs as the keys and the text of the response as the values."},"data_type":{"$ref":"#/components/schemas/SelectFilterListResponseDataType","description":"The format of the keys in the choices object. If the keys are strings representing sequential integers,\nthe data format is integer. If the keys are database ObjectIDs, the type of ID is specified."}},"title":"SelectFilterListResponse"},"SelectFilterListDetailedResponseType":{"type":"string","enum":["select","range"],"description":"The filter type.","title":"SelectFilterListDetailedResponseType"},"SelectFilterListDetailedResponseLifecycleState":{"type":"string","enum":["ACTIVE","DEPRECATED"],"description":"The lifecycle state of this filter. Active filters are visible in filter discovery. Deprecated filters are hidden from discovery but continue to work for existing studies.","title":"SelectFilterListDetailedResponseLifecycleState"},"SelectFilterListDetailedResponseDataType":{"type":"string","enum":["ChoiceID","ParticipantID","StudyID","ParticipantGroupID"],"description":"The format of the keys in the choices object. If the keys are strings representing sequential integers,\nthe data format is integer. If the keys are database ObjectIDs, the type of ID is specified.","title":"SelectFilterListDetailedResponseDataType"},"SelectFilterListDetailedResponse":{"type":"object","properties":{"filter_id":{"type":"string","description":"The ID of the filter, based on a slugified version of the title at the time the filter was created."},"title":{"type":"string","description":"The title of the filter."},"description":{"type":"string","description":"A description of the filter."},"type":{"$ref":"#/components/schemas/SelectFilterListDetailedResponseType","description":"The filter type."},"question":{"type":"string","description":"The question asked of participants to generate this filter."},"lifecycle_state":{"$ref":"#/components/schemas/SelectFilterListDetailedResponseLifecycleState","description":"The lifecycle state of this filter. Active filters are visible in filter discovery. Deprecated filters are hidden from discovery but continue to work for existing studies."},"choices":{"type":"object","additionalProperties":{"description":"Any type"},"description":"An object containing all the filter's possible responses as key-value pairs, with sequential integer IDs or database ObjectIDs as the keys and the text of the response as the values."},"data_type":{"$ref":"#/components/schemas/SelectFilterListDetailedResponseDataType","description":"The format of the keys in the choices object. If the keys are strings representing sequential integers,\nthe data format is integer. If the keys are database ObjectIDs, the type of ID is specified."},"researcher_help_text":{"type":["string","null"],"description":"Some help text to be displayed to researchers in the filter selection modal."},"participant_help_text":{"type":["string","null"],"description":"Some help text to be displayed to participants in the About You section."},"category":{"type":["string","null"],"description":"The category the filter is displayed in About You and the filter selection modal."},"subcategory":{"type":["string","null"],"description":"The sub-category the filter is displayed in the filter selection modal."},"display_order":{"type":["integer","null"],"description":"The order in which the filter is displayed within its sub-category in the filter selection modal."},"tags":{"type":["array","null"],"items":{"type":"string"},"description":"Some additional tags that can be used to display the filter in a specific way, e.g. recommended, new, expiring."}},"title":"SelectFilterListDetailedResponse"},"RangeFilterListResponseType":{"type":"string","enum":["select","range"],"description":"The filter type.","title":"RangeFilterListResponseType"},"RangeFilterListResponseLifecycleState":{"type":"string","enum":["ACTIVE","DEPRECATED"],"description":"The lifecycle state of this filter. Active filters are visible in filter discovery. Deprecated filters are hidden from discovery but continue to work for existing studies.","title":"RangeFilterListResponseLifecycleState"},"RangeFilterListResponseMin":{"oneOf":[{"type":"integer"},{"type":"number","format":"double"},{"type":"string"}],"description":"The minimum valid value of the range.","title":"RangeFilterListResponseMin"},"RangeFilterListResponseMax":{"oneOf":[{"type":"integer"},{"type":"number","format":"double"},{"type":"string"}],"description":"The maximum valid value of the range.","title":"RangeFilterListResponseMax"},"RangeFilterListResponseDataType":{"type":"string","enum":["date","integer","float"],"description":"The data type of the range.\n- If the data type is integer, the lower and upper values must be integers. Example: `70`.\n- If the data type is date, the lower and upper values must be ISO8601 dates. Example: `2025-07-11`.\n- If the data type is float, the lower and upper values can be provided as floats or integers. Returned values will be floats. Example: `70.5` or `80.0`.","title":"RangeFilterListResponseDataType"},"RangeFilterListResponseMinMax":{"oneOf":[{"type":"integer"},{"type":"number","format":"double"},{"type":"string"}],"description":"Optional maximum allowed value for the selected_range lower bound.","title":"RangeFilterListResponseMinMax"},"RangeFilterListResponseMaxMin":{"oneOf":[{"type":"integer"},{"type":"number","format":"double"},{"type":"string"}],"description":"Optional minimum allowed value for the selected_range upper bound.","title":"RangeFilterListResponseMaxMin"},"RangeFilterListResponse":{"type":"object","properties":{"filter_id":{"type":"string","description":"The ID of the filter, based on a slugified version of the title at the time the filter was created."},"title":{"type":"string","description":"The title of the filter."},"description":{"type":"string","description":"A description of the filter."},"type":{"$ref":"#/components/schemas/RangeFilterListResponseType","description":"The filter type."},"question":{"type":"string","description":"The question asked of participants to generate this filter."},"lifecycle_state":{"$ref":"#/components/schemas/RangeFilterListResponseLifecycleState","description":"The lifecycle state of this filter. Active filters are visible in filter discovery. Deprecated filters are hidden from discovery but continue to work for existing studies."},"min":{"$ref":"#/components/schemas/RangeFilterListResponseMin","description":"The minimum valid value of the range."},"max":{"$ref":"#/components/schemas/RangeFilterListResponseMax","description":"The maximum valid value of the range."},"data_type":{"$ref":"#/components/schemas/RangeFilterListResponseDataType","description":"The data type of the range.\n- If the data type is integer, the lower and upper values must be integers. Example: `70`.\n- If the data type is date, the lower and upper values must be ISO8601 dates. Example: `2025-07-11`.\n- If the data type is float, the lower and upper values can be provided as floats or integers. Returned values will be floats. Example: `70.5` or `80.0`."},"min_max":{"$ref":"#/components/schemas/RangeFilterListResponseMinMax","description":"Optional maximum allowed value for the selected_range lower bound."},"max_min":{"$ref":"#/components/schemas/RangeFilterListResponseMaxMin","description":"Optional minimum allowed value for the selected_range upper bound."}},"title":"RangeFilterListResponse"},"RangeFilterListDetailedResponseType":{"type":"string","enum":["select","range"],"description":"The filter type.","title":"RangeFilterListDetailedResponseType"},"RangeFilterListDetailedResponseLifecycleState":{"type":"string","enum":["ACTIVE","DEPRECATED"],"description":"The lifecycle state of this filter. Active filters are visible in filter discovery. Deprecated filters are hidden from discovery but continue to work for existing studies.","title":"RangeFilterListDetailedResponseLifecycleState"},"RangeFilterListDetailedResponseMin":{"oneOf":[{"type":"integer"},{"type":"number","format":"double"},{"type":"string"}],"description":"The minimum valid value of the range.","title":"RangeFilterListDetailedResponseMin"},"RangeFilterListDetailedResponseMax":{"oneOf":[{"type":"integer"},{"type":"number","format":"double"},{"type":"string"}],"description":"The maximum valid value of the range.","title":"RangeFilterListDetailedResponseMax"},"RangeFilterListDetailedResponseDataType":{"type":"string","enum":["date","integer","float"],"description":"The data type of the range.\n- If the data type is integer, the lower and upper values must be integers. Example: `70`.\n- If the data type is date, the lower and upper values must be ISO8601 dates. Example: `2025-07-11`.\n- If the data type is float, the lower and upper values can be provided as floats or integers. Returned values will be floats. Example: `70.5` or `80.0`.","title":"RangeFilterListDetailedResponseDataType"},"RangeFilterListDetailedResponseMinMax":{"oneOf":[{"type":"integer"},{"type":"number","format":"double"},{"type":"string"}],"description":"Optional maximum allowed value for the selected_range lower bound.","title":"RangeFilterListDetailedResponseMinMax"},"RangeFilterListDetailedResponseMaxMin":{"oneOf":[{"type":"integer"},{"type":"number","format":"double"},{"type":"string"}],"description":"Optional minimum allowed value for the selected_range upper bound.","title":"RangeFilterListDetailedResponseMaxMin"},"RangeFilterListDetailedResponse":{"type":"object","properties":{"filter_id":{"type":"string","description":"The ID of the filter, based on a slugified version of the title at the time the filter was created."},"title":{"type":"string","description":"The title of the filter."},"description":{"type":"string","description":"A description of the filter."},"type":{"$ref":"#/components/schemas/RangeFilterListDetailedResponseType","description":"The filter type."},"question":{"type":"string","description":"The question asked of participants to generate this filter."},"lifecycle_state":{"$ref":"#/components/schemas/RangeFilterListDetailedResponseLifecycleState","description":"The lifecycle state of this filter. Active filters are visible in filter discovery. Deprecated filters are hidden from discovery but continue to work for existing studies."},"min":{"$ref":"#/components/schemas/RangeFilterListDetailedResponseMin","description":"The minimum valid value of the range."},"max":{"$ref":"#/components/schemas/RangeFilterListDetailedResponseMax","description":"The maximum valid value of the range."},"data_type":{"$ref":"#/components/schemas/RangeFilterListDetailedResponseDataType","description":"The data type of the range.\n- If the data type is integer, the lower and upper values must be integers. Example: `70`.\n- If the data type is date, the lower and upper values must be ISO8601 dates. Example: `2025-07-11`.\n- If the data type is float, the lower and upper values can be provided as floats or integers. Returned values will be floats. Example: `70.5` or `80.0`."},"min_max":{"$ref":"#/components/schemas/RangeFilterListDetailedResponseMinMax","description":"Optional maximum allowed value for the selected_range lower bound."},"max_min":{"$ref":"#/components/schemas/RangeFilterListDetailedResponseMaxMin","description":"Optional minimum allowed value for the selected_range upper bound."},"researcher_help_text":{"type":["string","null"],"description":"Some help text to be displayed to researchers in the filter selection modal."},"participant_help_text":{"type":["string","null"],"description":"Some help text to be displayed to participants in the About You section."},"category":{"type":["string","null"],"description":"The category the filter is displayed in About You and the filter selection modal."},"subcategory":{"type":["string","null"],"description":"The sub-category the filter is displayed in the filter selection modal."},"display_order":{"type":["integer","null"],"description":"The order in which the filter is displayed within its sub-category in the filter selection modal."},"tags":{"type":["array","null"],"items":{"type":"string"},"description":"Some additional tags that can be used to display the filter in a specific way, e.g. recommended, new, expiring."}},"title":"RangeFilterListDetailedResponse"},"FilterListResultsItems":{"oneOf":[{"$ref":"#/components/schemas/SelectFilterListResponse"},{"$ref":"#/components/schemas/SelectFilterListDetailedResponse"},{"$ref":"#/components/schemas/RangeFilterListResponse"},{"$ref":"#/components/schemas/RangeFilterListDetailedResponse"}],"title":"FilterListResultsItems"},"FilterList":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/FilterListResultsItems"}},"_links":{"type":"object","additionalProperties":{"description":"Any type"}},"meta":{"type":"object","additionalProperties":{"description":"Any type"}}},"title":"FilterList"},"FilterDistributionDistribution":{"oneOf":[{"type":"object","additionalProperties":{"type":"integer"}},{"type":"object","additionalProperties":{"type":"integer"}}],"title":"FilterDistributionDistribution"},"FilterDistribution":{"type":"object","properties":{"distribution":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/FilterDistributionDistribution"},"description":"Distribution data for the specified `distribution_filters`"}},"title":"FilterDistribution"},"RequirementsCountRequestFiltersItems":{"oneOf":[{"$ref":"#/components/schemas/SelectFilter"},{"$ref":"#/components/schemas/RangeFilter"},{"$ref":"#/components/schemas/CompositeFilter"}],"title":"RequirementsCountRequestFiltersItems"},"RequirementsCountRequest":{"type":"object","properties":{"filters":{"type":"array","items":{"$ref":"#/components/schemas/RequirementsCountRequestFiltersItems"},"description":"List of filters to apply to the count. This parameter uses the new, simplified\nfilters schema for interacting with eligibility."},"workspace_id":{"type":"string","description":"The ID of the workspace you will be creating a study in.\n\nDue to US tax laws, non US residents may not participate in studies created by US researchers.\nFor this reason, we use the country specified in the workspace to determine eligibility.\n\nIf you do not specify a workspace ID, we will use the current workspace ID of the user making the request.\nYour eligibility count may not be accurate if you do not specify a workspace ID."},"organisation_id":{"type":"string","description":"The ID of the workspace you will be creating a filterset in."}},"required":["filters"],"title":"RequirementsCountRequest"},"RequirementsCount":{"type":"object","properties":{"count":{"type":"number","format":"double","description":"Number of participants passing all the requirements"}},"required":["count"],"title":"RequirementsCount"},"FilterSetFiltersItems":{"oneOf":[{"$ref":"#/components/schemas/SelectFilter"},{"$ref":"#/components/schemas/RangeFilter"},{"$ref":"#/components/schemas/CompositeFilter"}],"title":"FilterSetFiltersItems"},"FilterSet":{"type":"object","properties":{"id":{"type":"string","description":"ID of the filter set."},"version":{"type":"integer","description":"An incrementing integer indicating the version of the filter set."},"is_deleted":{"type":"boolean","description":"Whether the filter set has been deleted."},"is_locked":{"type":"boolean","description":"Whether the filter set has been locked."},"workspace_id":{"type":["string","null"],"description":"ID of the workspace where the filter set can be used."},"organisation_id":{"type":["string","null"],"description":"ID of the workspace where the filter set can be used."},"name":{"type":"string","description":"Name of the filter set."},"description":{"type":["string","null"],"maxLength":2048,"description":"Description of the filter set."},"filters":{"type":"array","items":{"$ref":"#/components/schemas/FilterSetFiltersItems"},"description":"List of all filters contained in the filter set."}},"title":"FilterSet"},"FilterSetList":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/FilterSet"},"description":"List of filter sets."}},"title":"FilterSetList"},"CreateFilterSetFiltersItems":{"oneOf":[{"$ref":"#/components/schemas/SelectFilter"},{"$ref":"#/components/schemas/RangeFilter"},{"$ref":"#/components/schemas/CompositeFilter"}],"title":"CreateFilterSetFiltersItems"},"CreateFilterSet":{"type":"object","properties":{"workspace_id":{"type":"string","description":"ID of the workspace where the filter set can be used."},"organisation_id":{"type":"string","description":"ID of the organisation where the filter set can be used."},"name":{"type":"string","description":"Name of the filter set."},"description":{"type":["string","null"],"maxLength":2048,"description":"Description of the filter set."},"filters":{"type":"array","items":{"$ref":"#/components/schemas/CreateFilterSetFiltersItems"},"description":"List of all filters contained in the filter set."}},"title":"CreateFilterSet"},"ApiV1FilterSetsPostResponsesContentApplicationJsonSchemaFiltersItems":{"oneOf":[{"$ref":"#/components/schemas/SelectFilter"},{"$ref":"#/components/schemas/RangeFilter"},{"$ref":"#/components/schemas/CompositeFilter"}],"title":"ApiV1FilterSetsPostResponsesContentApplicationJsonSchemaFiltersItems"},"Filter Sets_CreateFilterSet_Response_201":{"type":"object","properties":{"id":{"type":"string","description":"ID of the filter set."},"version":{"type":"integer","description":"An incrementing integer indicating the version of the filter set."},"is_deleted":{"type":"boolean","description":"Whether the filter set has been deleted."},"is_locked":{"type":"boolean","description":"Whether the filter set has been locked."},"workspace_id":{"type":["string","null"],"description":"ID of the workspace where the filter set can be used."},"organisation_id":{"type":["string","null"],"description":"ID of the workspace where the filter set can be used."},"name":{"type":"string","description":"Name of the filter set."},"description":{"type":["string","null"],"maxLength":2048,"description":"Description of the filter set."},"filters":{"type":"array","items":{"$ref":"#/components/schemas/ApiV1FilterSetsPostResponsesContentApplicationJsonSchemaFiltersItems"},"description":"List of all filters contained in the filter set."},"eligible_participant_count":{"type":"integer","description":"The number of participants who match the filter sets filters. Please note that if the number is\nlower than 5 the count will be obscured to prevent identification of participants."}},"title":"Filter Sets_CreateFilterSet_Response_201"},"ApiV1FilterSetsIdGetResponsesContentApplicationJsonSchemaFiltersItems":{"oneOf":[{"$ref":"#/components/schemas/SelectFilter"},{"$ref":"#/components/schemas/RangeFilter"},{"$ref":"#/components/schemas/CompositeFilter"}],"title":"ApiV1FilterSetsIdGetResponsesContentApplicationJsonSchemaFiltersItems"},"Filter Sets_GetFilterSet_Response_200":{"type":"object","properties":{"id":{"type":"string","description":"ID of the filter set."},"version":{"type":"integer","description":"An incrementing integer indicating the version of the filter set."},"is_deleted":{"type":"boolean","description":"Whether the filter set has been deleted."},"is_locked":{"type":"boolean","description":"Whether the filter set has been locked."},"workspace_id":{"type":["string","null"],"description":"ID of the workspace where the filter set can be used."},"organisation_id":{"type":["string","null"],"description":"ID of the workspace where the filter set can be used."},"name":{"type":"string","description":"Name of the filter set."},"description":{"type":["string","null"],"maxLength":2048,"description":"Description of the filter set."},"filters":{"type":"array","items":{"$ref":"#/components/schemas/ApiV1FilterSetsIdGetResponsesContentApplicationJsonSchemaFiltersItems"},"description":"List of all filters contained in the filter set."},"eligible_participant_count":{"type":"integer","description":"The number of participants who match the filter sets filters. Please note that if the number is\nlower than 5 the count will be obscured to prevent identification of participants."}},"title":"Filter Sets_GetFilterSet_Response_200"},"UpdateFilterSetFiltersItems":{"oneOf":[{"$ref":"#/components/schemas/SelectFilter"},{"$ref":"#/components/schemas/RangeFilter"},{"$ref":"#/components/schemas/CompositeFilter"}],"title":"UpdateFilterSetFiltersItems"},"UpdateFilterSet":{"type":"object","properties":{"name":{"type":"string","description":"Name of the filter set."},"description":{"type":["string","null"],"maxLength":2048,"description":"Description of the filter set."},"filters":{"type":"array","items":{"$ref":"#/components/schemas/UpdateFilterSetFiltersItems"},"description":"List of all filters contained in the filter set."}},"title":"UpdateFilterSet"},"ApiV1FilterSetsIdPatchResponsesContentApplicationJsonSchemaFiltersItems":{"oneOf":[{"$ref":"#/components/schemas/SelectFilter"},{"$ref":"#/components/schemas/RangeFilter"},{"$ref":"#/components/schemas/CompositeFilter"}],"title":"ApiV1FilterSetsIdPatchResponsesContentApplicationJsonSchemaFiltersItems"},"Filter Sets_UpdateFilterSet_Response_200":{"type":"object","properties":{"id":{"type":"string","description":"ID of the filter set."},"version":{"type":"integer","description":"An incrementing integer indicating the version of the filter set."},"is_deleted":{"type":"boolean","description":"Whether the filter set has been deleted."},"is_locked":{"type":"boolean","description":"Whether the filter set has been locked."},"workspace_id":{"type":["string","null"],"description":"ID of the workspace where the filter set can be used."},"organisation_id":{"type":["string","null"],"description":"ID of the workspace where the filter set can be used."},"name":{"type":"string","description":"Name of the filter set."},"description":{"type":["string","null"],"maxLength":2048,"description":"Description of the filter set."},"filters":{"type":"array","items":{"$ref":"#/components/schemas/ApiV1FilterSetsIdPatchResponsesContentApplicationJsonSchemaFiltersItems"},"description":"List of all filters contained in the filter set."},"eligible_participant_count":{"type":"integer","description":"The number of participants who match the filter sets filters. Please note that if the number is\nlower than 5 the count will be obscured to prevent identification of participants."}},"title":"Filter Sets_UpdateFilterSet_Response_200"},"ApiV1FilterSetsIdClonePostResponsesContentApplicationJsonSchemaFiltersItems":{"oneOf":[{"$ref":"#/components/schemas/SelectFilter"},{"$ref":"#/components/schemas/RangeFilter"},{"$ref":"#/components/schemas/CompositeFilter"}],"title":"ApiV1FilterSetsIdClonePostResponsesContentApplicationJsonSchemaFiltersItems"},"Filter Sets_CloneFilterSet_Response_201":{"type":"object","properties":{"id":{"type":"string","description":"ID of the filter set."},"version":{"type":"integer","description":"An incrementing integer indicating the version of the filter set."},"is_deleted":{"type":"boolean","description":"Whether the filter set has been deleted."},"is_locked":{"type":"boolean","description":"Whether the filter set has been locked."},"workspace_id":{"type":["string","null"],"description":"ID of the workspace where the filter set can be used."},"organisation_id":{"type":["string","null"],"description":"ID of the workspace where the filter set can be used."},"name":{"type":"string","description":"Name of the filter set."},"description":{"type":["string","null"],"maxLength":2048,"description":"Description of the filter set."},"filters":{"type":"array","items":{"$ref":"#/components/schemas/ApiV1FilterSetsIdClonePostResponsesContentApplicationJsonSchemaFiltersItems"},"description":"List of all filters contained in the filter set."},"eligible_participant_count":{"type":"integer","description":"The number of participants who match the filter sets filters. Please note that if the number is\nlower than 5 the count will be obscured to prevent identification of participants."}},"title":"Filter Sets_CloneFilterSet_Response_201"},"ApiV1FilterSetsIdLockPostResponsesContentApplicationJsonSchemaFiltersItems":{"oneOf":[{"$ref":"#/components/schemas/SelectFilter"},{"$ref":"#/components/schemas/RangeFilter"},{"$ref":"#/components/schemas/CompositeFilter"}],"title":"ApiV1FilterSetsIdLockPostResponsesContentApplicationJsonSchemaFiltersItems"},"Filter Sets_LockFilterSet_Response_200":{"type":"object","properties":{"id":{"type":"string","description":"ID of the filter set."},"version":{"type":"integer","description":"An incrementing integer indicating the version of the filter set."},"is_deleted":{"type":"boolean","description":"Whether the filter set has been deleted."},"is_locked":{"type":"boolean","description":"Whether the filter set has been locked."},"workspace_id":{"type":["string","null"],"description":"ID of the workspace where the filter set can be used."},"organisation_id":{"type":["string","null"],"description":"ID of the workspace where the filter set can be used."},"name":{"type":"string","description":"Name of the filter set."},"description":{"type":["string","null"],"maxLength":2048,"description":"Description of the filter set."},"filters":{"type":"array","items":{"$ref":"#/components/schemas/ApiV1FilterSetsIdLockPostResponsesContentApplicationJsonSchemaFiltersItems"},"description":"List of all filters contained in the filter set."},"eligible_participant_count":{"type":"integer","description":"The number of participants who match the filter sets filters. Please note that if the number is\nlower than 5 the count will be obscured to prevent identification of participants."}},"title":"Filter Sets_LockFilterSet_Response_200"},"ApiV1FilterSetsIdUnlockPostResponsesContentApplicationJsonSchemaFiltersItems":{"oneOf":[{"$ref":"#/components/schemas/SelectFilter"},{"$ref":"#/components/schemas/RangeFilter"},{"$ref":"#/components/schemas/CompositeFilter"}],"title":"ApiV1FilterSetsIdUnlockPostResponsesContentApplicationJsonSchemaFiltersItems"},"Filter Sets_UnlockFilterSet_Response_200":{"type":"object","properties":{"id":{"type":"string","description":"ID of the filter set."},"version":{"type":"integer","description":"An incrementing integer indicating the version of the filter set."},"is_deleted":{"type":"boolean","description":"Whether the filter set has been deleted."},"is_locked":{"type":"boolean","description":"Whether the filter set has been locked."},"workspace_id":{"type":["string","null"],"description":"ID of the workspace where the filter set can be used."},"organisation_id":{"type":["string","null"],"description":"ID of the workspace where the filter set can be used."},"name":{"type":"string","description":"Name of the filter set."},"description":{"type":["string","null"],"maxLength":2048,"description":"Description of the filter set."},"filters":{"type":"array","items":{"$ref":"#/components/schemas/ApiV1FilterSetsIdUnlockPostResponsesContentApplicationJsonSchemaFiltersItems"},"description":"List of all filters contained in the filter set."},"eligible_participant_count":{"type":"integer","description":"The number of participants who match the filter sets filters. Please note that if the number is\nlower than 5 the count will be obscured to prevent identification of participants."}},"title":"Filter Sets_UnlockFilterSet_Response_200"},"ApiV1ParticipantGroupsGetParametersActive":{"type":"string","enum":["true","false"],"title":"ApiV1ParticipantGroupsGetParametersActive"},"ApiV1ParticipantGroupsGetParametersFilter0":{"type":"object","properties":{"workspace_id":{"type":"string","description":"The id of the workspace to get participant groups for"}},"required":["workspace_id"],"title":"ApiV1ParticipantGroupsGetParametersFilter0"},"ApiV1ParticipantGroupsGetParametersFilter1":{"type":"object","properties":{"project_id":{"type":"string","description":"The id of the project to get participant groups for","deprecated":true}},"required":["project_id"],"title":"ApiV1ParticipantGroupsGetParametersFilter1"},"ApiV1ParticipantGroupsGetParametersFilter":{"oneOf":[{"$ref":"#/components/schemas/ApiV1ParticipantGroupsGetParametersFilter0"},{"$ref":"#/components/schemas/ApiV1ParticipantGroupsGetParametersFilter1"}],"title":"ApiV1ParticipantGroupsGetParametersFilter"},"ParticipantGroupFeederStudiesItemsFeederCompletionCodesItemsAction":{"type":"string","enum":["ADD_TO_PARTICIPANT_GROUP","REMOVE_FROM_PARTICIPANT_GROUP"],"description":"The action that will be taken when this code is used.","title":"ParticipantGroupFeederStudiesItemsFeederCompletionCodesItemsAction"},"ParticipantGroupFeederStudiesItemsFeederCompletionCodesItems":{"type":"object","properties":{"code":{"type":"string","description":"The code that will modify the participants in this group."},"code_type":{"type":"string","description":"The label or code type given to this code within the context of the study."},"action":{"$ref":"#/components/schemas/ParticipantGroupFeederStudiesItemsFeederCompletionCodesItemsAction","description":"The action that will be taken when this code is used."}},"description":"The code within this study that interacts with the participant group.","title":"ParticipantGroupFeederStudiesItemsFeederCompletionCodesItems"},"ParticipantGroupFeederStudiesItems":{"type":"object","properties":{"id":{"type":"string","description":"The id of the study."},"name":{"type":"string","description":"The name of the study."},"internal_name":{"type":"string","description":"The internal name of the study."},"status":{"type":"string","description":"The current status of the study."},"feeder_completion_codes":{"type":"array","items":{"$ref":"#/components/schemas/ParticipantGroupFeederStudiesItemsFeederCompletionCodesItems"},"description":"The completion codes which will modify the participants in this group."}},"title":"ParticipantGroupFeederStudiesItems"},"ParticipantGroup":{"type":"object","properties":{"id":{"type":"string","description":"The id of the participant group"},"name":{"type":"string","description":"The name of the participant group"},"project_id":{"type":["string","null"],"description":"The id of the project the participant group belongs to","deprecated":true},"workspace_id":{"type":["string","null"],"description":"The id of the workspace the participant group belongs to. A participant group can only belong to either a workspace or an organisation."},"organisation_id":{"type":["string","null"],"description":"The id of the organisation the participant group belongs to. A participant group can only belong to either a workspace or an organisation."},"description":{"type":["string","null"],"description":"The user-provided description of the participant group"},"participant_count":{"type":"integer","description":"The number of participants in the participant group"},"is_deleted":{"type":"boolean","description":"Whether the participant group has been deleted"},"feeder_studies":{"type":"array","items":{"$ref":"#/components/schemas/ParticipantGroupFeederStudiesItems"},"description":"Details of all studies which are configured to modify the participants in this group through completion codes."}},"title":"ParticipantGroup"},"ParticipantGroupListResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ParticipantGroup"}}},"title":"ParticipantGroupListResponse"},"ParticipantGroupResponse":{"type":"object","properties":{"id":{"type":"string","description":"The id of the participant group"},"name":{"type":"string","description":"The name of the participant group"},"project_id":{"type":["string","null"],"description":"The id of the project the participant group belongs to","deprecated":true},"workspace_id":{"type":["string","null"],"description":"The id of the workspace the participant group belongs to. A participant group can only belong to either a workspace or an organisation."},"organisation_id":{"type":["string","null"],"description":"The id of the organisation the participant group belongs to. A participant group can only belong to either a workspace or an organisation."},"description":{"type":["string","null"],"description":"The user-provided description of the participant group"},"participant_count":{"type":"integer","description":"The number of participants in the participant group"},"is_deleted":{"type":"boolean","description":"Whether the participant group has been deleted"},"feeder_studies":{"type":"array","items":{"$ref":"#/components/schemas/ParticipantGroupFeederStudiesItems"},"description":"Details of all studies which are configured to modify the participants in this group through completion codes."}},"title":"ParticipantGroupResponse"},"ParticipantGroupUpdate":{"type":"object","properties":{"name":{"type":"string","description":"The name of the participant group"},"participant_ids":{"type":"array","items":{"type":"string"},"description":"The ids of participants to be included in the group.\n\nNote, this overwrites any existing participants in the group; use the participant group membership endpoints to [append](#tag/Participant-Groups/operation/AddToParticipantGroup) or [remove](#tag/Participant-Groups/operation/RemoveFromParticipantGroup) participants from the group."}},"title":"ParticipantGroupUpdate"},"ParticipantGroupMembership":{"type":"object","properties":{"participant_id":{"type":"string","description":"The id of the participant"},"datetime_created":{"type":"string","description":"The date and time the participant was added to the Participant Group"}},"title":"ParticipantGroupMembership"},"ParticipantGroupMembershipListResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ParticipantGroupMembership"}}},"title":"ParticipantGroupMembershipListResponse"},"ParticipantIDList":{"type":"object","properties":{"participant_ids":{"type":"array","items":{"type":"string"}}},"title":"ParticipantIDList"},"ApiV1SubmissionsGetParametersStatus":{"type":"string","enum":["ACTIVE","AWAITING_REVIEW","APPROVED","PARTIALLY_APPROVED","REJECTED","RETURNED","SCREENED_OUT","TIMED-OUT","UNKNOWN"],"title":"ApiV1SubmissionsGetParametersStatus"},"ApiV1SubmissionsGetParametersCompleted":{"type":"string","enum":["0","1","true","false","yes","no","t","f"],"title":"ApiV1SubmissionsGetParametersCompleted"},"ApiV1SubmissionsGetParametersReturned":{"type":"string","enum":["0","1","true","false","yes","no","t","f"],"title":"ApiV1SubmissionsGetParametersReturned"},"ApiV1SubmissionsGetParametersAwaitingReview":{"type":"string","enum":["0","1","true","false","yes","no","t","f"],"title":"ApiV1SubmissionsGetParametersAwaitingReview"},"ApiV1SubmissionsGetParametersApproved":{"type":"string","enum":["0","1","true","false","yes","no","t","f"],"title":"ApiV1SubmissionsGetParametersApproved"},"ApiV1SubmissionsGetParametersActive":{"type":"string","enum":["0","1","true","false","yes","no","t","f"],"title":"ApiV1SubmissionsGetParametersActive"},"ApiV1SubmissionsGetParametersTimeout":{"type":"string","enum":["0","1","true","false","yes","no","t","f"],"title":"ApiV1SubmissionsGetParametersTimeout"},"ApiV1SubmissionsGetParametersRejected":{"type":"string","enum":["0","1","true","false","yes","no","t","f"],"title":"ApiV1SubmissionsGetParametersRejected"},"ApiV1SubmissionsGetParametersScreenedOut":{"type":"string","enum":["0","1","true","false","yes","no","t","f"],"title":"ApiV1SubmissionsGetParametersScreenedOut"},"ApiV1SubmissionsGetParametersCompleteoractive":{"type":"string","enum":["0","1","true","false","yes","no","t","f"],"title":"ApiV1SubmissionsGetParametersCompleteoractive"},"ApiV1SubmissionsGetParametersOrdering":{"type":"string","enum":["started_at","-started_at","submission_reward","-submission_reward","study_name","-study_name"],"title":"ApiV1SubmissionsGetParametersOrdering"},"SubmissionDetailStatus":{"type":"string","enum":["ACTIVE","APPROVED","PARTIALLY APPROVED","AWAITING REVIEW","REJECTED","RESERVED","RETURNED","TIMED-OUT","SCREENED OUT","UNKNOWN"],"description":"The current status of the submission","title":"SubmissionDetailStatus"},"SubmissionDetail":{"type":"object","properties":{"id":{"type":"string","description":"The id of the submission"},"completed_at":{"type":["string","null"],"description":"The time the submission was completed at."},"entered_code":{"type":["string","null"],"description":"The completion code used by the participant to complete the study."},"participant":{"type":"string","description":"Participant id."},"started_at":{"type":"string","description":"The date and time that the user started the submission (UTC)"},"status":{"$ref":"#/components/schemas/SubmissionDetailStatus","description":"The current status of the submission"},"study_id":{"type":"string","description":"Study id."},"parent_study_id":{"type":["string","null"],"description":"ID of the study's parent, if any. (This applies to representative sample and quota studies.)"},"bonus_payments":{"type":"array","items":{"type":"number","format":"double"},"description":"Bonus payments that have been paid on the submission. Returned in pence / cents."},"return_requested":{"type":["string","null"],"format":"date-time","description":"The date and time when a return request for the submission was made."}},"required":["id","started_at","status","study_id"],"title":"SubmissionDetail"},"SubmissionTransitionAction":{"type":"string","enum":["APPROVE","COMPLETE","REJECT","RETURN","START","SCREEN_OUT","UNREJECT","UNRETURN"],"description":"The action that should be performed on the submission.","title":"SubmissionTransitionAction"},"SubmissionTransitionRejectionCategory":{"type":"string","enum":["TOO_QUICKLY","TOO_SLOWLY","FAILED_INSTRUCTIONS","INCOMP_LONGITUDINAL","FAILED_CHECK","LOW_EFFORT","MALINGERING","NO_CODE","BAD_CODE","NO_DATA","UNSUPP_DEVICE","OTHER"],"description":"Required if action is 'REJECT', it sums as the category of\nthe rejection.","title":"SubmissionTransitionRejectionCategory"},"SubmissionTransitionCompletionCodeData":{"type":"object","properties":{"percentage_of_reward":{"type":"number","format":"double","description":"Required if the code is for a DYNAMIC_PAYMENT action. Must be between 8 - 99 (inclusive)."},"message_to_participant":{"type":"string","description":"Optional message to the participant to be sent alongside a dynamic payment."}},"description":"Required if the action is 'COMPLETE' and the code has the action \"DYNAMIC_PAYMENT\" associated with it.","title":"SubmissionTransitionCompletionCodeData"},"SubmissionTransition":{"type":"object","properties":{"action":{"$ref":"#/components/schemas/SubmissionTransitionAction","description":"The action that should be performed on the submission."},"message":{"type":"string","description":"Required if action is 'REJECT'. Message sent to the participant\nexplaining the reason for the rejection.\nIt must be at least 100 chars long."},"rejection_category":{"$ref":"#/components/schemas/SubmissionTransitionRejectionCategory","description":"Required if action is 'REJECT', it sums as the category of\nthe rejection."},"completion_code":{"type":"string","description":"Required if the action is 'COMPLETE'. The completion code must match a value provided when creating the study, and the actor must have been set to `researcher`. Any actions that were provided during the set up of the completion code (e.g. automatically approve) will then be carried out."},"completion_code_data":{"$ref":"#/components/schemas/SubmissionTransitionCompletionCodeData","description":"Required if the action is 'COMPLETE' and the code has the action \"DYNAMIC_PAYMENT\" associated with it."}},"required":["action"],"title":"SubmissionTransition"},"SubmissionStatus":{"type":"string","enum":["ACTIVE","APPROVED","AWAITING REVIEW","REJECTED","RESERVED","RETURNED","TIMED-OUT","SCREENED OUT","UNKNOWN"],"description":"The current status of the submission","title":"SubmissionStatus"},"Submission":{"type":"object","properties":{"id":{"type":"string","description":"The id of the submission"},"completed_at":{"type":["string","null"],"description":"The time the submission was completed at."},"entered_code":{"type":["string","null"],"description":"The completion code used by the participant to complete the study."},"participant":{"type":"string","description":"Participant id."},"started_at":{"type":"string","description":"The date and time that the user started the submission (UTC)"},"status":{"$ref":"#/components/schemas/SubmissionStatus","description":"The current status of the submission"},"study_id":{"type":"string","description":"Study id."}},"required":["id","started_at","status","study_id"],"title":"Submission"},"ReturnRequestedResponseStatus":{"type":"string","enum":["ACTIVE","APPROVED","AWAITING REVIEW","SCREENED OUT","REJECTED","RESERVED","RETURNED","TIMED-OUT","UNKNOWN"],"description":"The current status of the submission","title":"ReturnRequestedResponseStatus"},"ReturnRequestedResponse":{"type":"object","properties":{"id":{"type":"string","description":"the database id of the submission instance"},"status":{"$ref":"#/components/schemas/ReturnRequestedResponseStatus","description":"The current status of the submission"},"participant":{"type":"string","description":"The participant who took part in the study."},"return_requested":{"type":["string","null"],"format":"date-time","description":"The date and time when a return request for the submission was made."}},"title":"ReturnRequestedResponse"},"SubmissionsBulkApproveSubmissionsRequest0":{"type":"object","properties":{"study_id":{"type":"string"},"participant_ids":{"type":"array","items":{"type":"string"}}},"required":["study_id","participant_ids"],"title":"SubmissionsBulkApproveSubmissionsRequest0"},"SubmissionsBulkApproveSubmissionsRequest1":{"type":"object","properties":{"submission_ids":{"type":"array","items":{"type":"string"}}},"required":["submission_ids"],"title":"SubmissionsBulkApproveSubmissionsRequest1"},"Submissions_BulkApproveSubmissions_Request":{"oneOf":[{"$ref":"#/components/schemas/SubmissionsBulkApproveSubmissionsRequest0"},{"$ref":"#/components/schemas/SubmissionsBulkApproveSubmissionsRequest1"}],"title":"Submissions_BulkApproveSubmissions_Request"},"ApiV1SubmissionsSignalsUploadUrlFilenameGetResponsesContentApplicationJsonSchemaHttpMethod":{"type":"string","enum":["PUT"],"description":"The HTTP method to use when uploading to `upload_url`.","title":"ApiV1SubmissionsSignalsUploadUrlFilenameGetResponsesContentApplicationJsonSchemaHttpMethod"},"Submission Feedback Upload_GetSubmissionFeedbackUploadUrl_Response_201":{"type":"object","properties":{"upload_url":{"type":"string","description":"The temporary, pre-signed URL to upload your file to with an HTTP `PUT` request."},"http_method":{"$ref":"#/components/schemas/ApiV1SubmissionsSignalsUploadUrlFilenameGetResponsesContentApplicationJsonSchemaHttpMethod","description":"The HTTP method to use when uploading to `upload_url`."},"expires_at":{"type":"string","format":"date-time","description":"The time at which the pre-signed `upload_url` expires."}},"title":"Submission Feedback Upload_GetSubmissionFeedbackUploadUrl_Response_201"},"BulkBonus":{"type":"object","properties":{"id":{"type":"string","description":"Bonus ID. It is the ID to be used when paying the bonus"},"study":{"type":"string","description":"Study ID"},"amount":{"type":"number","format":"double","description":"The amount the participant will receive in cents"},"fees":{"type":"number","format":"double","description":"The fees Prolific will charge for this bonus in cents"},"vat":{"type":"number","format":"double","description":"The VAT cost for this bonus in cents"},"total_amount":{"type":"number","format":"double","description":"Total amount that will be deducted from your balance in cents"}},"required":["id","total_amount"],"title":"BulkBonus"},"MessageDataCategory":{"type":"string","enum":["payment-timing","payment-issues","technical-issues","feedback","rejections","other"],"description":"Participants can self-categorise their message before sending it.","title":"MessageDataCategory"},"MessageData":{"type":"object","properties":{"study_id":{"type":"string","description":"What study the message relates to. In case this is not automatically filled for the participant, they can choose which study their message relates to."},"category":{"$ref":"#/components/schemas/MessageDataCategory","description":"Participants can self-categorise their message before sending it."}},"description":"Metadata for a message","title":"MessageData"},"Message":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID of the message"},"sender_id":{"type":"string","description":"Id of the user who sent the message"},"body":{"type":"string","description":"Body of the message."},"sent_at":{"type":"string","format":"date-time","description":"Date time when message was sent"},"type":{"type":"string","description":"Will only me message for now"},"channel_id":{"type":"string","description":"The channel ID, for linking back to a thread in the Prolific app."},"data":{"$ref":"#/components/schemas/MessageData","description":"Metadata for a message"}},"required":["id","sender_id","body","sent_at","channel_id"],"title":"Message"},"Messages":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Message"}}},"title":"Messages"},"SendMessage":{"type":"object","properties":{"recipient_id":{"type":"string","description":"Recipient user's id"},"body":{"type":"string","description":"Message Body. Text is sanitised for safe storage and display."},"study_id":{"type":"string","description":"This study is the reason for this message"}},"required":["recipient_id","body","study_id"],"title":"SendMessage"},"SendBulkMessage":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"},"description":"A list of participant ID's"},"body":{"type":"string","description":"Message Body. Text is sanitised for safe storage and display."},"study_id":{"type":"string","description":"A study ID"}},"required":["ids","body","study_id"],"title":"SendBulkMessage"},"MessageParticipantGroup":{"type":"object","properties":{"participant_group_id":{"type":"string","description":"A participant group ID"},"body":{"type":"string","description":"Message Body. Text is sanitised for safe storage and display."},"study_id":{"type":"string","description":"A study ID"}},"required":["participant_group_id","body"],"title":"MessageParticipantGroup"},"WorkspaceUser":{"type":"object","properties":{"id":{"type":"string","description":"Id of user"},"name":{"type":"string","description":"Name of user"},"email":{"type":"string","description":"email of user"},"roles":{"type":"array","items":{"type":"string"},"description":"User roles in workspace"}},"required":["id"],"title":"WorkspaceUser"},"WorkspaceShort":{"type":"object","properties":{"id":{"type":"string","description":"Workspace id. It is created by Prolific."},"title":{"type":"string","description":"Name of workspace"},"description":{"type":"string","description":"What is this workspace used for"},"owner":{"type":"string","description":"User id of the creator of the workspace. It is created by Prolific."},"users":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceUser"},"description":"Data for all users who have access to this workspace"},"naivety_distribution_rate":{"type":["number","null"],"format":"double","minimum":0,"maximum":1,"description":"The rate at which the studies within this project are distributed.","deprecated":true}},"required":["id","title"],"title":"WorkspaceShort"},"WorkspacesListResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceShort"},"description":"List of all workspaces for user"}},"required":["results"],"title":"WorkspacesListResponse"},"CreateWorkspace":{"type":"object","properties":{"title":{"type":"string","description":"Name of workspace"},"naivety_distribution_rate":{"type":["number","null"],"format":"double","minimum":0,"maximum":1,"description":"Control the balance between speed of your studies and the naivety of the participants.\n\nIf not defined, by default Prolific calculates the best rate for most studies\ntaking into account the `filters` and the `total_available_places` needed for this study.\n\nUse 0 if your priority is speed. When this property is set to 0 all eligible participants will have access\nto your study at the same time, without any prioritization.\n\nYou can also set this at a project and study level.","deprecated":true},"currency_code":{"type":"string","description":"Currency used for all transactions within the workspace. Must be GBP or USD."}},"required":["title"],"title":"CreateWorkspace"},"ProjectType":{"type":"string","enum":["PRIVATE","PUBLIC"],"description":"Project visibility type.","title":"ProjectType"},"PublicProjectStatus":{"type":"string","enum":["ENABLED","DISABLED"],"description":"Participant-facing publication status for a public project.","title":"PublicProjectStatus"},"PublicDetails":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/PublicProjectStatus","description":"Status of the public project metadata. Defaults to `ENABLED`."},"title":{"type":"string","maxLength":120,"description":"Participant-facing title for the public project."},"short_description":{"type":"string","maxLength":500,"description":"Short participant-facing summary shown to participants for the public project."},"description":{"type":"string","maxLength":3000,"description":"Additional participant-facing information shown to participants for the public project."}},"title":"PublicDetails"},"ProjectShort":{"type":"object","properties":{"id":{"type":"string","description":"Project id. It is created by Prolific."},"title":{"type":"string","description":"Name of project"},"description":{"type":"string","description":"What is this project used for"},"owner":{"type":"string","description":"User id of the creator of the project. It is created by Prolific."},"type":{"$ref":"#/components/schemas/ProjectType"},"public_details":{"oneOf":[{"$ref":"#/components/schemas/PublicDetails"},{"type":"null"}],"description":"Public metadata for `PUBLIC` projects. `null` for `PRIVATE` projects."},"users":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceUser"},"description":"Data for all users who have access to this project"},"naivety_distribution_rate":{"type":["number","null"],"format":"double","minimum":0,"maximum":1,"description":"The rate at which the studies within this project are distributed.","deprecated":true}},"required":["id","title","type"],"title":"ProjectShort"},"Workspace":{"type":"object","properties":{"id":{"type":"string","description":"Workspace id. It is created by Prolific."},"title":{"type":"string","description":"Name of workspace"},"description":{"type":"string","description":"What is this workspace used for"},"owner":{"type":"string","description":"Workspace id. It is created by Prolific."},"users":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceUser"},"description":"Data for a user related to a workspace"},"projects":{"type":"array","items":{"$ref":"#/components/schemas/ProjectShort"},"description":"Data for a project related to a workspace"},"wallet":{"type":"string","description":"Wallet tied to workspace"},"naivety_distribution_rate":{"type":["number","null"],"format":"double","minimum":0,"maximum":1,"description":"The rate at which the studies within this workspace are distributed.","deprecated":true}},"required":["id","title"],"title":"Workspace"},"WorkspaceBalanceBalanceBreakdown":{"type":"object","properties":{},"description":"A breakdown of the total balance of the workspace into:\n- Funds available to pay to participants\n- Funds pre-paid to Prolific for our services\n- Funds for any VAT applied to our Platform fees","title":"WorkspaceBalanceBalanceBreakdown"},"WorkspaceBalanceAvailableBalanceBreakdown":{"type":"object","properties":{},"description":"A breakdown of the available balance of the workspace into:\n- Funds available to pay to participants\n- Funds pre-paid to Prolific for our services\n- Funds for any VAT applied to our Platform fees","title":"WorkspaceBalanceAvailableBalanceBreakdown"},"WorkspaceBalance":{"type":"object","properties":{"currency_code":{"type":"string","description":"The currency used for all financial transactions within the workspace."},"total_balance":{"type":"integer","description":"The total balance of the workspace, including funds which have already been assigned to active studies.\n\nAll monetary values are shown in the sub-currency of your workspace currency (e.g. pence, cents)."},"balance_breakdown":{"$ref":"#/components/schemas/WorkspaceBalanceBalanceBreakdown","description":"A breakdown of the total balance of the workspace into:\n- Funds available to pay to participants\n- Funds pre-paid to Prolific for our services\n- Funds for any VAT applied to our Platform fees"},"available_balance":{"type":"integer","description":"The remaining balance of your workspace which is available to spend, after removing funds assigned to already active studies, etc."},"available_balance_breakdown":{"$ref":"#/components/schemas/WorkspaceBalanceAvailableBalanceBreakdown","description":"A breakdown of the available balance of the workspace into:\n- Funds available to pay to participants\n- Funds pre-paid to Prolific for our services\n- Funds for any VAT applied to our Platform fees"}},"title":"WorkspaceBalance"},"ProjectShortListResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ProjectShort"},"description":"List of all projects for a user"}},"required":["results"],"title":"ProjectShortListResponse"},"LongitudinalConfigFiltersItems":{"oneOf":[{"$ref":"#/components/schemas/SelectFilter"},{"$ref":"#/components/schemas/RangeFilter"},{"$ref":"#/components/schemas/CompositeFilter"}],"title":"LongitudinalConfigFiltersItems"},"LongitudinalConfig":{"type":"object","properties":{"target_completions":{"type":"integer","minimum":1,"maximum":1000000,"description":"Target number of completions for the final wave."},"retention_rate":{"type":"number","format":"double","minimum":0.01,"maximum":1,"description":"Expected retention rate between waves."},"filters":{"type":"array","items":{"$ref":"#/components/schemas/LongitudinalConfigFiltersItems"},"description":"Recruitment filters applied to participants entering the first wave.\nUses the same filter shapes as study creation."}},"required":["target_completions","retention_rate"],"title":"LongitudinalConfig"},"CreateProjectLongitudinal":{"type":"object","properties":{"config":{"$ref":"#/components/schemas/LongitudinalConfig"}},"description":"Longitudinal configuration. Only used when `is_longitudinal` is true.\n`waves` may not be set at creation — add studies via\n`POST /api/v1/projects/{project_id}/studies/` after creation.","title":"CreateProjectLongitudinal"},"CreateProject":{"type":"object","properties":{"title":{"type":"string","description":"Name of project"},"description":{"type":"string","description":"What is this project used for"},"type":{"$ref":"#/components/schemas/ProjectType","default":"PRIVATE","description":"Project visibility type.\nSet to `PUBLIC` to enable participant-facing public project metadata."},"public_details":{"oneOf":[{"$ref":"#/components/schemas/PublicDetails"},{"type":"null"}],"description":"Public metadata exposed for `PUBLIC` projects.\nOmit for `PRIVATE` projects.\nWhen creating a public project, `status` defaults to `ENABLED`."},"naivety_distribution_rate":{"type":["number","null"],"format":"double","minimum":0,"maximum":1,"description":"Control the balance between speed of your studies and the naivety of the participants.\n\nIf not defined, by default Prolific calculates the best rate for most studies\ntaking into account the `filters` and the `total_available_places` needed for this study.\n\nUse 0 if your priority is speed. When this property is set to 0 all eligible participants will have access\nto your study at the same time, without any prioritization.\n\nYou can also set this at a workspace and study level.","deprecated":true},"is_longitudinal":{"type":"boolean","default":false,"description":"Whether this is a longitudinal (multi-wave) project."},"longitudinal":{"oneOf":[{"$ref":"#/components/schemas/CreateProjectLongitudinal"},{"type":"null"}],"description":"Longitudinal configuration. Only used when `is_longitudinal` is true.\n`waves` may not be set at creation — add studies via\n`POST /api/v1/projects/{project_id}/studies/` after creation."}},"required":["title"],"title":"CreateProject"},"ProjectLongitudinalRetention":{"type":"object","properties":{},"description":"Computed retention projections and actuals, keyed by wave study id.","title":"ProjectLongitudinalRetention"},"ProjectLongitudinal":{"type":"object","properties":{"config":{"oneOf":[{"$ref":"#/components/schemas/LongitudinalConfig"},{"type":"null"}]},"retention":{"$ref":"#/components/schemas/ProjectLongitudinalRetention","description":"Computed retention projections and actuals, keyed by wave study id."},"waves":{"type":"array","items":{"type":"string"},"description":"Ordered list of study IDs defining the project's current wave\nsequence. Empty if the project has no waves yet. Set via\n`longitudinal.waves` on `PATCH` (see `UpdateProject`)."}},"description":"Only present when `is_longitudinal` is true.","title":"ProjectLongitudinal"},"Project":{"type":"object","properties":{"id":{"type":"string","description":"Project id. It is created by Prolific."},"title":{"type":"string","description":"Name of project"},"description":{"type":"string","description":"What is this project used for"},"owner":{"type":"string","description":"User id of the creator of the project. It is created by Prolific."},"type":{"$ref":"#/components/schemas/ProjectType"},"public_details":{"oneOf":[{"$ref":"#/components/schemas/PublicDetails"},{"type":"null"}],"description":"Public metadata for `PUBLIC` projects. `null` for `PRIVATE` projects."},"users":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceUser"},"description":"Data for all users who have access to this project"},"workspace":{"type":"string","description":"Id of the workspace this project is in. This is created by Prolific."},"naivety_distribution_rate":{"type":["number","null"],"format":"double","minimum":0,"maximum":1,"description":"The rate at which the studies within this project are distributed.","deprecated":true},"is_longitudinal":{"type":"boolean","description":"Whether this is a longitudinal (multi-wave) project."},"longitudinal":{"oneOf":[{"$ref":"#/components/schemas/ProjectLongitudinal"},{"type":"null"}],"description":"Only present when `is_longitudinal` is true."}},"required":["id","title","type"],"title":"Project"},"UpdateProject":{"type":"object","properties":{"title":{"type":"string","description":"Name of project"},"description":{"type":"string","description":"What is this project used for"},"owner":{"type":"string","description":"User id of the creator of the project."},"position":{"type":"integer","description":"Position of the project within a workspace."},"hidden":{"type":"boolean","description":"Whether the project is hidden in workspace listings."},"type":{"$ref":"#/components/schemas/ProjectType"},"public_details":{"$ref":"#/components/schemas/PublicDetails","description":"Public metadata for `PUBLIC` projects. Omit to leave unchanged."},"is_sequential":{"type":"boolean","description":"Whether the project is configured as sequential."}},"description":"Partial update payload for a project. All fields are optional.","title":"UpdateProject"},"SurveyAnswerOption":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"value":{"type":"string","maxLength":140,"description":"The answer option value that can be selected."}},"required":["value"],"description":"Responsible for defining an answer model for a given question","title":"SurveyAnswerOption"},"SurveyQuestionType":{"type":"string","enum":["single","multiple"],"description":"Responsible for articulating the question type. At the moment we have:\n\n- single answer\n- multiple answer\n\nArgs:\n str (_type_): The type of question.\n Enum (_type_): The class to define an enum.","title":"SurveyQuestionType"},"SurveyQuestion":{"type":"object","properties":{"answers":{"type":"array","items":{"$ref":"#/components/schemas/SurveyAnswerOption"},"description":"An array of answer options for a question."},"id":{"type":"string","format":"uuid"},"title":{"type":"string","maxLength":200,"description":"The question title."},"type":{"$ref":"#/components/schemas/SurveyQuestionType","description":"The type of question being asked."}},"required":["answers","title","type"],"description":"Responsible for defining a question within a survey.","title":"SurveyQuestion"},"SurveySection":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Auto generated by the system."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/SurveyQuestion"},"description":"An array of questions a section within a Survey."},"title":{"type":"string","description":"The section title."}},"required":["questions","title"],"description":"Responsible for providing a section to the survey.\n\nThis is more of a long term thing, but helps if we add now.","title":"SurveySection"},"SurveyOut":{"type":"object","properties":{"_id":{"type":"string","description":"Auto generated by the system."},"date_created":{"type":"string","format":"date-time","description":"The date/time the survey was created (UTC)."},"date_modified":{"type":"string","format":"date-time","description":"The date/time the survey was modified (UTC)."},"researcher_id":{"type":"string","description":"The Prolific researcher ID."},"sections":{"type":"array","items":{"$ref":"#/components/schemas/SurveySection"},"description":"Optional: An array of sections in the survey, otherwise `questions` will be defined."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/SurveyQuestion"},"description":"Optional: An array of questions in the survey, otherwise `sections` will be defined."},"title":{"type":"string","description":"The survey title."}},"required":["researcher_id","title"],"description":"The model used to create a serialised representation a `Survey`.","title":"SurveyOut"},"GetAllSurveysResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SurveyOut"},"description":"List of all surveys matching the criteria."}},"required":["results"],"title":"GetAllSurveysResponse"},"SurveyIn":{"type":"object","properties":{"researcher_id":{"type":"string","description":"The Prolific researcher ID."},"sections":{"type":"array","items":{"$ref":"#/components/schemas/SurveySection"},"description":"An array of sections in the survey, or use `questions`."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/SurveyQuestion"},"description":"An array of questions in the survey, or use `sections`."},"title":{"type":"string","description":"The survey title."}},"required":["researcher_id","title"],"description":"The model used to create a `Survey`.","title":"SurveyIn"},"SurveyResponseAnswer":{"type":"object","properties":{"answer_id":{"type":"string","format":"uuid","description":"The answer ID."},"value":{"type":"string","description":"The answer option value selected."}},"required":["answer_id","value"],"description":"Responsible for defining a response to a question","title":"SurveyResponseAnswer"},"SurveyQuestionResponse":{"type":"object","properties":{"answers":{"type":"array","items":{"$ref":"#/components/schemas/SurveyResponseAnswer"},"description":"The answers selected."},"question_id":{"type":"string","format":"uuid","description":"The question ID."},"question_title":{"type":"string","description":"The title of the survey question."}},"required":["answers","question_id","question_title"],"description":"Responsible for defining an answer to a survey question","title":"SurveyQuestionResponse"},"SurveyResponseSection":{"type":"object","properties":{"questions":{"type":"array","items":{"$ref":"#/components/schemas/SurveyQuestionResponse"},"description":"The questions for a given section."},"section_id":{"type":"string","format":"uuid","description":"The section ID."}},"required":["questions","section_id"],"description":"Responsible for linking question/answers to a response for a survey.\n\nThis is more of a long term thing, but helps if we add now.","title":"SurveyResponseSection"},"SurveyResponseIn":{"type":"object","properties":{"participant_id":{"type":"string","description":"The Prolific participant ID."},"sections":{"type":"array","items":{"$ref":"#/components/schemas/SurveyResponseSection"},"description":"An array of sections from the survey, otherwise use `questions`."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/SurveyQuestionResponse"},"description":"An array of questions from the survey, otherwise use `sections`."},"submission_id":{"type":"string","description":"The Prolific submission ID."}},"required":["participant_id","submission_id"],"description":"The model used to create a `Response`.","title":"SurveyResponseIn"},"SurveyResponseOut":{"type":"object","properties":{"_id":{"type":"string"},"date_created":{"type":"string","format":"date-time","description":"The date/time the response was created (UTC)."},"date_modified":{"type":"string","format":"date-time","description":"The date/time the response was modified (UTC)."},"participant_id":{"type":"string","description":"The Prolific participant ID."},"sections":{"type":"array","items":{"$ref":"#/components/schemas/SurveyResponseSection"},"description":"An array of sections from the survey, otherwise `questions`."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/SurveyQuestionResponse"},"description":"An array of questions from the survey, otherwise `sections`."},"submission_id":{"type":"string","description":"The Prolific submission ID."}},"required":["participant_id","submission_id"],"description":"The model used to create a serialised representation a `Response`.","title":"SurveyResponseOut"},"SurveySummaryAnswer":{"type":"object","properties":{"answer_id":{"type":"string","format":"uuid","description":"The answer ID."},"answer":{"type":"string","description":"The answer selected."},"count":{"type":"integer","default":0,"description":"The count of how many times this answer was used in a response."}},"required":["answer"],"description":"Responsible for housing the aggregation for a specific answer.","title":"SurveySummaryAnswer"},"SurveySummaryQuestion":{"type":"object","properties":{"question_id":{"type":"string","format":"uuid","description":"The question ID."},"question":{"type":"string","description":"The title of the question."},"total_answers":{"type":"integer","default":0,"description":"The total number of answered responses for a given question."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/SurveySummaryAnswer"},"description":"A list of aggregated answer information."}},"required":["question"],"description":"Responsible for housing the questions we want to aggregate for the summary.","title":"SurveySummaryQuestion"},"SurveySummary":{"type":"object","properties":{"survey_id":{"type":"string","description":"The survey ID."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/SurveySummaryQuestion"},"description":"A list of questions for the given survey."}},"required":["survey_id"],"description":"Responsible for providing a base for all the aggregated answers for a survey.","title":"SurveySummary"},"EventType":{"type":"object","properties":{"event_type":{"type":"string"},"description":{"type":"string"}},"title":"EventType"},"EventTypeList":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/EventType"}}},"title":"EventTypeList"},"SecretDetail":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the secret."},"value":{"type":"string","description":"The secret value."},"workspace_id":{"type":"string","description":"The ID of the workspace that the secret belongs to."}},"title":"SecretDetail"},"SecretList":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SecretDetail"},"description":"A list of secrets."}},"title":"SecretList"},"CreateSecret":{"type":"object","properties":{"workspace_id":{"type":"string","description":"The ID of the workspace you are creating the secret in"}},"title":"CreateSecret"},"SubscriptionDetail":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the subscription."},"event_type":{"type":"string","description":"The name of the event type associated to the subscription."},"target_url":{"type":"string","description":"The URL that the subscription will notify when your event type is triggered."},"is_enabled":{"type":"boolean","description":"Whether the subscription is enabled or not."},"workspace_id":{"type":"string","description":"The ID of the workspace we will create the subscription in."}},"required":["event_type","target_url","workspace_id"],"title":"SubscriptionDetail"},"SubscriptionList":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionDetail"},"description":"List of all subscriptions."}},"required":["results"],"title":"SubscriptionList"},"SubscriptionConfirmation":{"type":"object","properties":{"secret":{"type":"string","description":"The secret that was generated when the subscription was created and returned as the `X-Hook-Secret` header."}},"required":["secret"],"title":"SubscriptionConfirmation"},"SubscriptionUpdateDetail":{"type":"object","properties":{"event_type":{"type":"string","description":"The name of the event type associated to the subscription."},"target_url":{"type":"string","description":"The URL that the subscription will notify when your event type is triggered."},"is_enabled":{"type":"boolean","description":"Whether the subscription is enabled or not."}},"title":"SubscriptionUpdateDetail"},"SubscriptionEventStatus":{"type":"string","enum":["PENDING","SUCCEEDED","FAILED"],"description":"The status of the event. Will be `FAILED` if the `target_url` response is not 2xx.","title":"SubscriptionEventStatus"},"SubscriptionEventPayload":{"type":"object","properties":{},"description":"The event payload that was sent to the target url.","title":"SubscriptionEventPayload"},"SubscriptionEvent":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the subscription event."},"datetime_created":{"type":"string","description":"The time the event was created."},"datetime_updated":{"type":"string","description":"The last time the event was updated."},"event_type":{"type":"string","description":"The event type that was triggered."},"resource_id":{"type":"string","description":"The Prolific Resource ID that the event is linked to."},"status":{"$ref":"#/components/schemas/SubscriptionEventStatus","description":"The status of the event. Will be `FAILED` if the `target_url` response is not 2xx."},"target_url":{"type":"string","description":"The URL where the event payload is sent."},"payload":{"oneOf":[{"$ref":"#/components/schemas/SubscriptionEventPayload"},{"type":"null"}],"description":"The event payload that was sent to the target url."}},"title":"SubscriptionEvent"},"SubscriptionEventList":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionEvent"},"description":"All the events triggered for the subscription"}},"required":["results"],"title":"SubscriptionEventList"},"CreateInvitationRequestRole":{"type":"string","enum":["WORKSPACE_ADMIN","WORKSPACE_COLLABORATOR"],"description":"The role that the invited users will have in the workspace. This can be one of the following:\n- \"WORKSPACE_ADMIN\": The user will have administrative rights in the workspace. They can manage settings, invite users, and oversee all projects.\n- \"WORKSPACE_COLLABORATOR\": The user will be a regular collaborator in the workspace. They can contribute to projects but don't have administrative rights.\n","title":"CreateInvitationRequestRole"},"CreateInvitationRequest":{"type":"object","properties":{"association":{"type":"string","format":"objectId","description":"The ID of the workspace to which the users are being invited."},"emails":{"type":"array","items":{"type":"string","format":"email"},"description":"An array of email addresses of the users to invite."},"role":{"$ref":"#/components/schemas/CreateInvitationRequestRole","description":"The role that the invited users will have in the workspace. This can be one of the following:\n- \"WORKSPACE_ADMIN\": The user will have administrative rights in the workspace. They can manage settings, invite users, and oversee all projects.\n- \"WORKSPACE_COLLABORATOR\": The user will be a regular collaborator in the workspace. They can contribute to projects but don't have administrative rights.\n"}},"title":"CreateInvitationRequest"},"InvitationInvitee":{"type":"object","properties":{"id":{"type":["string","null"],"format":"objectId","description":"The unique ID of the invitee."},"name":{"type":["string","null"],"description":"The name of the invitee."},"email":{"type":"string","format":"email","description":"The email address of the invitee."}},"title":"InvitationInvitee"},"InvitationStatus":{"type":"string","enum":["INVITED","ACCEPTED"],"description":"The current status of the invitation.","title":"InvitationStatus"},"InvitationRole":{"type":"string","enum":["WORKSPACE_ADMIN","WORKSPACE_COLLABORATOR"],"description":"Assigned role for the user in this workspace.","title":"InvitationRole"},"Invitation":{"type":"object","properties":{"association":{"type":"string","format":"objectId","description":"The ID of the workspace to which the invitee was invited."},"invitee":{"$ref":"#/components/schemas/InvitationInvitee"},"invited_by":{"type":"string","format":"objectId","description":"The ID of the user who sent the invitation."},"status":{"$ref":"#/components/schemas/InvitationStatus","description":"The current status of the invitation."},"invite_link":{"type":"string","format":"uri","description":"The link that the invitee can use to accept the invitation."},"role":{"$ref":"#/components/schemas/InvitationRole","description":"Assigned role for the user in this workspace."}},"title":"Invitation"},"CreateInvitationResponse":{"type":"object","properties":{"invitations":{"type":"array","items":{"$ref":"#/components/schemas/Invitation"}}},"title":"CreateInvitationResponse"},"ApiV1RewardRecommendationsGetParametersCurrency":{"type":"string","enum":["USD","GBP"],"title":"ApiV1RewardRecommendationsGetParametersCurrency"},"RewardRecommendationsResponseItemsCurrency":{"type":"string","enum":["USD","GBP"],"description":"An ISO 4217 currency code. Note that we only support a selection of currency codes as per the enum values.","title":"RewardRecommendationsResponseItemsCurrency"},"RewardRecommendationsResponseItems":{"type":"object","properties":{"currency":{"$ref":"#/components/schemas/RewardRecommendationsResponseItemsCurrency","description":"An ISO 4217 currency code. Note that we only support a selection of currency codes as per the enum values."},"min_reward_per_hour":{"type":"integer","description":"The **minimum** hourly reward rate that we recommend you pay to your study's participants.\n\n**Note that** this is returned as the hundredth subunit of the given currency i.e:\n\n* for USD, this will be the value in cents\n* for GBP, this will be the value in pence\n\nTo display this as USD or GBP respectively, you'll need to divide this value by 100 and use an appropriate number formatting API e.g:\n\nJavaScript:\n\n```js\nnew Intl.NumberFormat(\"en-US\", { style: \"currency\", currency: \"USD\" }).format(2000/ 100); // \"$20.00\"\n```\n"},"recommended_reward_per_hour":{"type":"integer","description":"The **good** hourly reward rate that we recommend you pay to your study's participants.\n\n**Note that** this is returned as the hundredth subunit of the given currency i.e:\n\n* for USD, this will be the value in cents\n* for GBP, this will be the value in pence\n\nTo display this as USD or GBP respectively, you'll need to divide this value by 100 and use an appropriate number formatting API e.g:\n\nJavaScript:\n\n```js\nnew Intl.NumberFormat(\"en-US\", { style: \"currency\", currency: \"USD\" }).format(2000/ 100); // \"$20.00\"\n```\n"}},"title":"RewardRecommendationsResponseItems"},"RewardRecommendationsResponse":{"type":"array","items":{"$ref":"#/components/schemas/RewardRecommendationsResponseItems"},"title":"RewardRecommendationsResponse"},"JwkKty":{"type":"string","enum":["RSA"],"description":"Key type, always \"RSA\".","title":"JwkKty"},"JwkAlg":{"type":"string","enum":["RS256"],"description":"Algorithm used, always \"RS256\".","title":"JwkAlg"},"JwkUse":{"type":"string","enum":["sig"],"description":"The intended use of the public key.","title":"JwkUse"},"JwkKeyOpsItems":{"type":"string","enum":["verify"],"title":"JwkKeyOpsItems"},"JWK":{"type":"object","properties":{"kty":{"$ref":"#/components/schemas/JwkKty","description":"Key type, always \"RSA\"."},"kid":{"type":"string","description":"Key ID used to match the key to the JWT header."},"alg":{"$ref":"#/components/schemas/JwkAlg","description":"Algorithm used, always \"RS256\"."},"n":{"type":"string","description":"The modulus of the RSA public key."},"e":{"type":"string","description":"The exponent of the RSA public key."},"use":{"$ref":"#/components/schemas/JwkUse","description":"The intended use of the public key."},"key_ops":{"type":"array","items":{"$ref":"#/components/schemas/JwkKeyOpsItems"},"description":"The operations that the key is intended to be used for."}},"required":["kty","kid","alg","n","e","use","key_ops"],"title":"JWK"},"JWKSResponse":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/JWK"}}},"title":"JWKSResponse"},"ApiV1CredentialsGetResponsesContentApplicationJsonSchemaCredentialPoolsItems":{"type":"object","properties":{"credential_pool_id":{"type":"string","description":"The unique identifier for the credential pool"},"total_credentials":{"type":"integer","description":"Total number of credentials in the pool"},"available_credentials":{"type":"integer","description":"Number of unredeemed credentials available"}},"title":"ApiV1CredentialsGetResponsesContentApplicationJsonSchemaCredentialPoolsItems"},"Credentials_ListCredentialPools_Response_200":{"type":"object","properties":{"credential_pools":{"type":"array","items":{"$ref":"#/components/schemas/ApiV1CredentialsGetResponsesContentApplicationJsonSchemaCredentialPoolsItems"}}},"title":"Credentials_ListCredentialPools_Response_200"},"Credentials_CreateCredentialPool_Response_201":{"type":"object","properties":{"credential_pool_id":{"type":"string","description":"The unique identifier for the created credential pool"}},"title":"Credentials_CreateCredentialPool_Response_201"},"Credentials_UpdateCredentialPool_Response_200":{"type":"object","properties":{"credential_pool_id":{"type":"string","description":"The unique identifier for the updated credential pool"}},"title":"Credentials_UpdateCredentialPool_Response_200"}},"securitySchemes":{"token":{"type":"apiKey","in":"header","name":"Authorization","description":"The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.\n\nYour API token does not have an expiry date and carries full permission, so be sure to keep them secure.\n\nIf your token is leaked, delete it and create a new one directly in the app.\n\nIn your requests add `Authorization` header with the value `Token `."}}}}