Queries
A query is a question raised against a participant's data — a value that looks wrong, a missing field, a discrepancy with source — assigned to someone to resolve, with a comment thread. Automatic queries raise them for you when a rule matches a submission.
Reading queries needs trial.readQueries; raising, editing and closing them needs trial.writeQueries; an assignee can always read and comment on the queries assigned to them. trial.read, trial.write and trial.admin imply these. Automatic queries need trial.readAutomaticQueries and trial.writeAutomaticQueries.
Endpoints
| Method | Path | Description |
|---|---|---|
GET |
/trials/<trialId>/queries |
The trial's queries, as {"queries": [...]}. |
POST |
/trials/<trialId>/queries |
Raise a query. |
GET |
/queries/<queryId> |
One query. |
PUT |
/queries/<queryId> |
Reassign, close or reopen a query, or change its notes. |
DELETE |
/queries/<queryId> |
Delete a query. Body: {"reason": "…"} (required). |
GET |
/queries/<queryId>/comments?page=1&page_size=50 |
The comment thread. |
POST |
/queries/<queryId>/comments |
Add a comment. 30 requests per minute. |
PUT |
/queries/<queryId>/comments/<commentId> |
Edit your comment's text. |
DELETE |
/queries/<queryId>/comments/<commentId> |
Delete a comment — yours, or any as a trial admin. |
GET |
/trials/<trialId>/automatic-queries |
Automatic query rules, as {"automaticQueries": [...]}. |
POST |
/trials/<trialId>/automatic-queries |
Create a rule. |
PUT DELETE |
/automatic-queries/<automaticQueryId> |
Update or delete a rule. |
Queries also come back alongside the responses they are about — see Reading responses.
Raising a query
POST /trials/<trialId>/queries:
| Field | Type | Notes |
|---|---|---|
title |
string | |
description |
string | |
participant |
participant _id |
Who the query is about. |
response |
response _id |
The submission it concerns. |
dataType |
data type _id |
The field it concerns, if one. |
assignees |
list of user _ids |
Who should resolve it. They are notified. |
Updating a query
PUT /queries/<queryId> takes assignees, status (open or closed) and notes. Closing a query is how it is resolved; it can be reopened by setting status back to open.
Comments
POST /queries/<queryId>/comments takes a comment (up to 5000 characters) and optional attachments — stored file names from an upload with forType=query and the query's _id. Mention a user by writing @[Their Name](user:<userId>) in the text; they are notified. Editing a comment changes its text only; attachments stay as they were.
Automatic queries
An automatic query is a rule that raises a query whenever a submission matches it. POST /trials/<trialId>/automatic-queries and PUT /automatic-queries/<automaticQueryId>:
| Field | Type | Notes |
|---|---|---|
name |
string | 2–100 characters. |
description |
string | |
dataType |
data type _id |
The field the rules test. Leave empty ("") for rules about the submission as a whole. |
rules |
list | Every rule must match. Each has a ruleType and, depending on it, operator, value, stage, stageRecurrence, group or site. |
query |
object | The query to raise: {"title", "description", "assignees": [...]}. |
Rule types: value tests the field's answer with an operator (exists, notExists, equals, notEquals, greaterThan, lessThan, and for choices includes, notIncludes) and value; fieldScore tests what the field scored and score what the whole submission scored, with the same operators; promisTScore and promisPropr test a PROMIS field's scores; stage (with stage and optional stageRecurrence), group and site restrict the rule to submissions of that stage, or by participants in that group or site.