Data types
A data type is a variable — the field a form asks, and the column an export produces. Every data type belongs to a trial and has a name, a type (its format) and settings that depend on the format. The Data types article explains the formats and their settings; this one describes the endpoints.
Reading data types needs access to the trial; creating, updating and deleting them needs trial.write. A locked trial refuses changes.
Endpoints
| Method | Path | Description |
|---|---|---|
GET |
/trials/<trialId>/dataTypes |
The trial's data types, as {"dataTypes": [...]}. |
POST |
/trials/<trialId>/dataTypes |
Create one data type, or several. |
GET |
/dataTypes/<dataTypeId> |
One data type. |
PUT |
/dataTypes/<dataTypeId> |
Update a data type. 50 requests per minute. |
DELETE |
/dataTypes/<dataTypeId> |
Delete a data type. |
POST |
/dataTypes/delete |
Delete several: {"ids": ["…", "…"]}. |
PUT |
/dataTypes?ids=<id>,<id> |
Add tags to several at once: {"addTags": ["Baseline"]}. |
GET |
/trials/<trialId>/data-type-tags |
The trial's tags, as {"dataTypeTags": [...]}. |
POST |
/trials/<trialId>/data-type-tags |
Create a tag: {"name": "…", "colour": "…"}. |
PUT DELETE |
/data-type-tags/<tagId> |
Rename, recolour or delete a tag. |
Creating data types
POST /trials/<trialId>/dataTypes creates one data type from the fields below and returns it. To create many in one request, send {"dataTypes": [{...}, {...}]} instead; the response is {"dataTypes": [...]}. copyFrom with another data type's _id copies its settings.
Fields common to every format
| Field | Type | Notes |
|---|---|---|
name |
string | 2–60 characters. The variable name used in exports. Unique within the trial. |
type |
string | The format — one of the keys below. |
nickname |
string | Up to 100 characters. A friendlier label for the admin interface. |
tags |
list of strings | Tag names. |
isRestricted |
boolean | Responses visible only to holders of trial.readParticipantStudyDataRestricted. |
isPii |
boolean | Responses visible only to holders of trial.readParticipantStudyDataPii. |
enableLookback |
boolean | Show participants their previous answer. Numeric formats only. |
Formats
type |
Format | Settings |
|---|---|---|
text |
Short text | minimumLength, maximumLength (0–3000). |
paragraph |
Long text | minimumLength, maximumLength. |
choice |
Single or multiple choice | options (up to 30), multiple, showAsDropdown, includeNone. |
integer |
Whole number | minimumValue, maximumValue. |
float |
Decimal number | minimumValue, maximumValue. |
slider |
Slider | minimum, maximum. |
rating |
Rating scale | points (3–6), symbol (stars, numeric, smileys), labels (one per point). |
likert |
Likert matrix | scalePoints (2–11 of {"label", "value"}), statements (1–30 of {"key", "label"}), includeNotApplicable. |
date |
Date | earliestDate, latestDate. |
datetime |
Date and time | earliestDate, latestDate. |
time |
Time of day | earliestTime, latestTime. |
temperature, weight, height |
Measurements | — |
bmi |
Body mass index | hideBmiIndication. |
table |
Rows and columns | columns (1–20 of {"id", "name", "type", "isOptional"}, type one of text, integer, float, date), maximumRows (1–50). |
calculation |
Calculated from a formula | formula. See Calculated fields. |
file, image, video |
Uploads | — |
food |
Nutrition lookup | foodSource, requiredFoodFields. |
stroop, pal, ravlt |
Cognition tests | wordPairs, pairTimeout, answerTimeout, displayAnswerTimer, displayCorrectResult, testSet, interruptionSet, preInterruptionTests, postInterruptionTests, timeLimit as applicable. |
promisForm, promisBattery |
PROMIS instruments | promisFormOid, promisShowTScore, promisBatteryOid. |
teethChart |
Teeth chart | — |
Formats from file down depend on features enabled for your team; a request for a format your team does not have is refused with 403.
The _id of a data type is what a stage component's dataType refers to, and what a response's fields are keyed by — see Stages and Responses and exports.