Skip to main content
POST
Create a custom sample field
Create a definition before assigning its values with Update a sample.
A successful request returns 201 with the new definition, including its id, key, label, valueType, origin, storage, writable, options, and nullable description. The same definition appears in List sample fields.
  • Omit key to derive it from the label: Study cohort becomes study_cohort. Explicit keys use 1 to 50 lowercase letters, digits, or _, starting with a letter. Reserved system keys cannot be created.
  • Types: text, number, date, checkbox, single_select, multi_select. type is an alias for valueType. If both are supplied they must agree.
  • Select types require 1 to 100 options, each 1 to 80 characters and unique ignoring case. Other types cannot specify options.
  • Descriptions are optional, trimmed, and limited to 1,000 characters. Empty or whitespace-only descriptions become null. NUL characters are rejected.
  • Invalid input returns 400. Duplicate keys, case-insensitive duplicate labels, or exceeding 100 custom fields per organization returns 409. Built-in fields do not count toward the cap.
In the dashboard, Manage Fields lets you create and edit descriptions. Descriptions appear in field-chip tooltips and the field value popover.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
label
string
required
Required string length: 1 - 80
valueType
enum<string>
required
Available options:
text,
number,
date,
checkbox,
single_select,
multi_select
type
enum<string>

Alias for valueType; must agree if both are supplied.

Available options:
text,
number,
date,
checkbox,
single_select,
multi_select
key
string

Reserved system keys are rejected.

Pattern: ^[a-z][a-z0-9_]{0,49}$
options
string[]

Required only for select types. Case-insensitively unique.

Required array length: 1 - 100 elements
Required string length: 1 - 80
description
string | null

Trimmed; blank becomes null. NUL characters are rejected.

Maximum string length: 1000

Response

Created definition