Atoms
In the portal: Settings, then Atoms.
What it is
An atom is one thing on a screen: a paragraph to read, a question to answer, a picture, a button. A sequence is a list of them.
There are exactly thirteen types, and the type is what decides three things at once: what the participant sees, which settings you are offered, and what shape the answer is stored in. A type cannot be changed after the atom is created, so choosing it is the one decision on this page worth slowing down for.
The rest of this page is one section per type. Read the chooser first and skip to the one you need.
Which one you want
| You want the participant to | Use | Called this in the portal | Answer it stores |
|---|---|---|---|
| Read something | content | Text | none |
| Watch, look at or listen to something | asset | Asset | none |
| Tap through to somewhere else | button | Button | true once tapped |
| Write something in their own words | text | Text input | a string |
| Type a figure | number | Number input | a number |
| Rate something on a scale | slider | Slider | a number |
| Pick one of several | single_select | Single select | the chosen value |
| Pick any number of several | multi_select | Multi-select | a list of values |
| Answer yes or no | boolean | Yes / No | true or false |
| Give a date or a time | datetime | Date & time | a string |
| Give a blood pressure reading | blood_pressure | Blood pressure | systolic and diastolic in mmHg |
| Do a paced breathing practice | breathing | Breathing exercise | rounds and seconds |
Nothing. Use asset instead | embed | Embed | none |
Read the middle column before you go looking for anything. The portal does not use these names. It uses the ones in that column, and two of them are close enough to swap by accident.
The one to watch: the portal calls a content atom "Text", and it calls a text
atom "Text input". So the thing that only shows words is called Text, and the thing
that takes words from the participant is called Text input. Pick the wrong one and you
get a screen that reads back at somebody when you wanted it to ask them something.
What it looks like
Every atom draws the same way: the prompt on top, the control underneath, with the atoms of one page stacked down the screen.
Two rules about the words are worth knowing before you write anything.
An atom's name never appears on a participant's screen. It is the name in your
library, so you can find it. The participant-facing prompt is label, and it is a
separate field. Put the question in label: an atom whose question went into
name shows a control with no question above it.
Only a content atom puts prose on a card. Every other type gets its prompt from
label and nothing else. label is one field of rich text sitting above a control,
so it will not work as a paragraph. If you want a paragraph of explanation above a
question, it is a content atom sitting above that question on the same page, not a
longer label.
The portal does not offer a label field on content, asset, button or embed,
because each of those carries its own text elsewhere.
The fields every atom has
| Field | What it accepts | Default | Notes |
|---|---|---|---|
code | capitals, numbers and underscores, starting with a letter, up to 128 | none, required | Unique in your tenancy and fixed once created. A repeat returns atom_code_exists. It is also what a merge token names, so an atom with no code cannot be quoted back in copy. |
name | 1 to 200 characters | none, required | Your library name for it. Never shown to a participant. |
label | up to 500 characters of rich text | empty | The prompt the participant reads. |
type | one of the thirteen | none, required | Fixed once created. |
config | the per-type settings below | {} | Checked strictly on write. An unknown key is rejected with invalid_config rather than ignored, so a typo fails at the point you make it. |
weight | a number | 1 | Multiplies this atom's contribution to a sequence score. |
required | true or false | not set | Whether an answer is needed to move on. Only means anything on a type that captures an answer. |
condition | a condition clause | none | Shows or hides this one atom. This is how one card says different things to different people. |
status | active, archived | active | Archived atoms drop out of the picker. |
defaultRevisable | true or false | true | Copied onto a delivery, and decides whether the answer can be changed later. |
An unknown config key is refused, not saved. Strict checking means a typo fails at the point you make it, rather than sitting in the editor looking correct.
What the portal shows you
The type decides which fields you are allowed to see. Understand this before anything else on this page, because it explains why the form looks different every time you change the type.
Every atom, whatever its type, has four things.
| On screen | Notes |
|---|---|
| Name | Required. The code is derived from it and shown beside it. |
| Type | Required, and greyed out once the atom exists. Changing the type is creating a different atom: make a new one and swap it into the page. The old answers stay attached to the old atom, which is what you want, because a chart should not mix two different questions. |
| Status | Required. Active or archived. |
| Condition | A panel at the bottom, closed by default, reading "Always show this atom". |
Then, only if the type captures an answer, five more appear.
| On screen | Notes |
|---|---|
| Question | The words above the control. Rich text, up to 500 characters. |
| Required | Whether the participant can move on without answering. |
| Score weight | What this answer contributes when the sequence is scored. |
| Progress | Tracking for the answer. It is set on the sequence, which is where it takes effect. |
| Revisable | Whether the answer can be changed later. Defaults to yes. |
The types that capture an answer are text, number, slider, single_select,
multi_select, boolean, datetime and blood_pressure. The four that do not are content, asset,
button and embed, and they have no Question field at all, because their content is
the question: the body, the picture, the button's own text, the embedded page.
So if you are looking for a field and cannot find it, check the type first. The type is what decides which fields appear.
Tracking is set on the sequence, not on the atom. An atom's answers reach the Progress page because the sequence carrying it is tracked. See Tracked and untracked.
content
What it renders as. A block of formatted text. Markdown, so headings, bold, lists and links all work. There is no control and nothing to answer.
On screen it asks for Body (required) and Heading colour.
Config.
| Key | What it accepts | Default | What changes |
|---|---|---|---|
body | markdown text | empty | The words. Give every content atom a body: the portal requires one, and an atom that arrives through an import with an empty body draws as a blank space. |
headingColor | primary, brand, accent, error, success, warning | none | The colour of markdown headings in this block. Anything outside that list, a colour code included, is rejected with invalid_config. There is no green in the theme, which is why success exists as a name. |
Stores. Nothing.
Reach for it when you need words on a screen. It is the only type that puts prose in front of a participant, so it is the most used of the thirteen, and it is what sits above a question to explain why the question is being asked.
asset
What it renders as. Whatever the file is. The file's own type decides, not a setting.
- An image draws inline, and tapping it opens it full screen.
- Audio shows a Listen row that opens a player.
- Video shows a row that opens a player.
- A link to a video hosting site opens as an embedded player instead.
On screen it asks for an asset picker, then Alt text.
Config.
| Key | What it accepts | Default | What changes |
|---|---|---|---|
assetId | the id of an asset in your library | none | The file. It must be public and its upload must have finished, or the write is refused with asset_not_public or asset_not_ready. |
url | a web address | none | An external file instead of a library one. It is set through the interface rather than in the atom editor. |
alt | text | none | What a screen reader says in place of the picture, and its description when it opens full screen. With none, a screen reader says only "Image". |
Stores. Nothing.
Reach for it when the content is a picture, a recording or a video. See Assets for what you can upload and how large it can be.
Every asset takes alt text, and it reaches both places a participant meets the
picture: what a screen reader says in place of it, and its description when it opens
full screen. Write it whenever you add an asset, because there is no sensible default the
platform could write for you. Where the picture carries meaning everybody needs, and not
only somebody using a screen reader, put that meaning in a content atom beside it too.
button
What it renders as. A full width button. Filled by default, outlined if you ask. Once tapped it turns green and its icon becomes a tick.
On screen it asks for Button text (required), then Link, then Icon and Style side by side.
Config.
| Key | What it accepts | Default | What changes |
|---|---|---|---|
text | text | none, required | The words on the button. |
url | a web address, or an in-app address beginning app:// | none | Where it goes. A web address opens the browser and leaves the sequence open behind it. An in-app address moves to that tab and closes the sequence, keeping whatever has been answered so far. |
icon | one of calendar, cloud, eye, cart, checklist, book, heart, star, chat, phone | a tap glyph | The icon to the left of the words. An unrecognised name falls back to the default rather than failing. |
variant | primary, secondary | primary | Filled or outlined. |
Stores. true, the moment it is tapped. It is worth knowing that a button
records an answer, because a button on a required page satisfies that page.
Reach for it when the next thing happens somewhere else: booking a session, opening a resource, jumping to the chat tab.
text
What it renders as. A single line box, or a taller box for a paragraph.
On screen it asks for Placeholder, then Default value, then Format, Multi-line and Max length in one row.
Config.
| Key | What it accepts | Default | What changes |
|---|---|---|---|
placeholder | text | empty | Grey hint text inside an empty single line box. |
multiline | true or false | false | False gives one line. True gives a box about four lines tall. |
Stores. The text, trimmed. An empty box stores nothing rather than an empty string.
Reach for it when you want the participant's own words. Their words can then be quoted back to them later in the same sequence or in a later one, which is the cheapest way to make a programme feel like it is paying attention.
Ask for the format and the length in the prompt. The box opens empty and takes whatever the participant types, so a question that needs a particular shape or a limit has to say so in the words.
number
What it renders as. A wide box with large digits and a number pad, with the unit in smaller grey type beside the figure.
On screen it asks for Min, Max and Unit in one row, then Step and Default in another.
Config.
| Key | What it accepts | Default | What changes |
|---|---|---|---|
min | a number | none | The lowest allowed. Typing below it shows "Must be at least" under the field when the participant tries to move on. When the field loses focus, the figure is pulled up into range and the display is rewritten to match. |
max | a number | none | The same at the top end. |
unit | text | none | The unit beside the figure. Purely a label: nothing converts. |
Stores. A number.
Reach for it when the figure is the point: minutes walked, a weight, a reading from a device. If this is the only question on its page, the number pad comes up on its own.
Set min and max even where the range is obvious. They pin the axis of this
atom's chart on the Progress tab. Without them the axis fits itself to whatever has
been answered so far, so a small wobble in a narrow range draws as a cliff.
Use a slider where the answer should move in fixed notches. step is a slider
setting. A number atom gives the participant an empty box and a number pad.
slider
What it renders as. A slider with the lowest number under the left end, the
highest under the right end, and the current value large in the middle. The thumb
starts where default puts it, and at the lowest number when no default is set.
On screen it asks for Min, Max, Step and Default in one row, then Min label and Max label in another. Min and Max are required, and they arrive seeded at 0 and 10.
Config.
| Key | What it accepts | Default | What changes |
|---|---|---|---|
min | a number | required, 0 if it somehow arrives missing | The left end. |
max | a number | required, 10 if missing | The right end. |
step | a number above zero | 1 | How far one notch moves. |
default | a number | none | Where the thumb sits before the participant touches it. A value outside the scale is pulled back into it. It is a starting position and never an answer. |
Stores. A number, written the moment the participant lets go of the thumb. A slider nobody has touched stores nothing at all.
Reach for it when the answer is a rating with no natural unit, and the ends need
to be visible at a glance. Where the scale has named points rather than numbers, use
single_select instead, because a slider shows only numbers.
Set required on any slider whose answer has to be given. The figure in the
middle is where the thumb is sitting, and the answer goes on file when the
participant moves it. So a slider seeded at the value somebody already agrees with
records nothing, and a scored questionnaire is short by that atom. With required
set to true, an untouched slider is stopped with Required on both phones.
If the ends of the scale need words, put them in the prompt, or use
single_select. The participant sees the two numbers, one under each end.
single_select
What it renders as. A stack of full width rows, one per option. The chosen one tints, gains an outline and shows a tick.
On screen it asks for an Options list, each row carrying Label, Value and Score and draggable to reorder, then Default value.
Config.
| Key | What it accepts | Default | What changes |
|---|---|---|---|
options | a list of { label, value, score } | none, required | The rows, in the order you write them. label is what is read, value is what is stored, and score is optional and is what makes the atom count towards a sequence score. |
Stores. The chosen option's value.
Reach for it when there is one answer from a fixed list. It is also the right choice for a rating with named points, because the words are visible where a slider's would not be.
Ordering matters twice over. The rows appear in the order you write them, and they stay in that order on the participant's Progress tab. Write a scale worst to best or best to worst. Adding an option at the end later is safe. Shuffling them after people have answered is not, because the history stops lining up.
No option arrives chosen for the participant. The list opens with nothing selected, so every answer on file is one they picked.
multi_select
What it renders as. The same stack of rows, with a checkbox on each. Tapping toggles.
On screen it asks for an Options list as above, then Min selections and Max selections side by side.
Config.
| Key | What it accepts | Default | What changes |
|---|---|---|---|
options | a list of { label, value, score } | none, required | As above. Scores add up across everything ticked. |
minSelections | a whole number | none | The fewest that may be ticked. |
maxSelections | a whole number | none | The most that may be ticked. |
Stores. A list of values, always in the order the options were authored, whatever order they were tapped in. Nothing ticked stores nothing.
Reach for it when more than one answer can be true at once.
Set maxSelections wherever the source material caps the answer. With no cap a
participant can tick everything, so if the material says "choose up to three", that
number belongs in this field.
The selection count is checked on both phones, and a participant who ticks too many is stopped when they try to move on.
boolean
What it renders as. Two buttons side by side, carrying the two labels you authored, or Yes and No when you author none. The chosen one tints and gains an outline.
On screen it asks for an Options list locked to exactly two rows. The labels are yours to edit and the values are read-only. Then Default.
Config.
| Key | What it accepts | Default | What changes |
|---|---|---|---|
options | a pair of { label, value, score } | Yes and No | The pair of scores. See below. |
Stores. True or false.
Reach for it when the answer really is yes or no. Where it is yes, no and
sometimes, use single_select.
The two labels are what the participant reads. Write Taken and Skipped and the buttons say Taken and Skipped, on both phones and on their Progress page. Leave them alone and they read Yes and No, which is the fallback when none are authored. The values underneath stay true and false whatever the labels say, so the stored answer and any chart are unaffected.
A boolean can carry a score. It scores its option's score where one is
authored, and 1 or 0 where none is. The question opens with neither button chosen.
datetime
What it renders as. A compact picker: a date wheel, a clock, or both.
On screen it asks for Mode, then Earliest, Latest and Default in one row. The three pickers follow the mode, so a time-mode atom is authored with a time picker rather than a date one.
Config.
| Key | What it accepts | Default | What changes |
|---|---|---|---|
mode | date, time, datetime | date | Which picker appears, and the shape the answer is stored in. |
minDate | a value in the same shape as the answer | none | The earliest allowed. |
maxDate | the same | none | The latest allowed. |
Stores. A string, and the shape follows mode: date stores 2026-03-14,
time stores 08:30, datetime stores a full timestamp. Because those shapes sort
as text, the bounds compare as text too, so write them in exactly the same shape.
Reach for it when you need a specific day or time: an appointment, a surgery date, the time they woke.
minDate and maxDate are checked on both phones, and an out of range answer is
refused when the participant tries to move on.
Ask for the date or time you want in the prompt. The picker opens with nothing chosen.
blood_pressure
What it renders as. Two number boxes side by side, Systolic and Diastolic, with mmHg beside them. Whole numbers only.
On screen it asks for nothing.
Config. None. The two fields and the ranges they accept are the same in every tenancy, so a reading means the same thing wherever it was entered.
Stores. One object holding systolic and diastolic.
Reach for it when the participant is reading a figure off a home monitor. Both numbers are required together, so a half-filled pair is refused.
It is recorded, not assessed. The reading is stored with the sequence's other answers, where a coach can see it, and it stays separate from the readings the phone collects from Health. The platform does not interpret it, score it, or raise a clinical alert on it, so clinical judgement stays with your team. The two numbers are range checked on entry: a systolic outside 50 to 250, a diastolic outside 30 to 150, or a systolic at or below the diastolic is refused with a message naming the range.
On the Progress page it draws a single Responded row once both numbers are there,
rather than a trend line. Where the figures themselves have to trend, use two number
atoms.
breathing
What it renders as. A row that says "Start breathing exercise". Tapping it opens a full screen paced practice with an orb that grows on the inhale and shrinks on the exhale, and the word Inhale or Exhale under it. When it finishes, the row says "Breathing exercise completed" with a tick.
On screen it asks for Pattern, then Rounds, Inhale (s), Hold (s) and Exhale (s) in one row.
Config.
| Key | What it accepts | Default | What changes |
|---|---|---|---|
rounds | a whole number | 3 | How many breaths. |
inhaleSecs | seconds | 4 | How long the orb takes to grow. |
exhaleSecs | seconds | 6 | How long it takes to shrink. |
Stores. An object holding the rounds actually completed and how many seconds the participant spent in it. Someone who leaves early still records what they did.
Reach for it when the practice itself is the intervention. A longer exhale than inhale is the usual shape.
Build the pacing out of inhaleSecs and exhaleSecs. The practice runs inhale
then exhale with no pause, so those two settings are the whole shape of it.
embed
Use an asset atom instead of this type. Put the hosted address in the asset
atom's url, and a video hosting address opens there as an embedded player, which is
the behaviour embed is named for.
What the answer looks like once it is stored
Two things are true of every answer.
Answers are added, never overwritten. A correction is a new answer with a later timestamp, and the earlier one stays on file. A participant's history is a full record of what they said and when, rather than a running total that has been edited.
A locked answer is fixed once it is given. defaultRevisable: false accepts the
first answer for an occasion and then refuses any change to it, with
response_not_revisable and the message "This response is part of a journey and
cannot be changed." Drafts, retries of the same submission, and answers for a
different day are unaffected.
Where each setting takes effect
Some settings are authored in one place and take effect in another. This is the quick answer for the ones people look for most.
| Setting | Where it takes effect |
|---|---|
default on text, number, single_select, boolean, datetime | These controls open empty, so ask for the answer you want in the prompt. A slider is the exception: its default sets where the thumb starts. |
format and maxLength on text | Ask for the format and the length in the prompt. |
step on number | step shapes a slider. A number atom gives the participant an empty box and a number pad. |
minLabel and maxLabel on slider | Put the words in the prompt, or use single_select, which shows the words on the rows. |
holdSecs and pattern on breathing | Shape the practice with inhaleSecs and exhaleSecs. |
tracking on an atom | Tracking is set on the sequence and on the journey. |
the embed type | Use asset with a url. |
tracking is the one to watch. Set it on the sequence and the answers inside that
sequence reach the participant's Progress page. See
Tracked and untracked.
Next
You have the thirteen types, the two the portal names almost the same, and the one decision that cannot be undone once the atom exists.
Sequences is the container atoms sit in: the pages, the order, and the settings that decide how the finished thing behaves on the home screen.
Questionnaires and scoring takes the five types that can carry a number and turns a set of answers into one score.