Canonical submission JSON - Health Yourself

Last updated: 2026-05-25 (aligned with platform baseline 488e91e / tag baseline).

Overview

Health Yourself collects questionnaire answers and blood results in your intake UX (see the Input Data Preparation Guide). Before calling Idunox, your backend maps that data into canonical Type A JSON — a structured subject block, a flat markers[] blood panel, optional sourceMetadata, and options.

Do not send legacy markers.healthQuestionnaireMarkers / markers.bloodMarkers arrays or top-level requestedAssessments. Those shapes are not accepted by the live partner API.

Concept	Canonical location
Questionnaire (36 items)	`subject.demographics`, `subject.measurements`, `subject.history`, `subject.familyHistory`
Blood panel (14 analytes)	`markers[]` with `code`, `value`, `unit`
Lab reference intervals	`sourceMetadata.markerRanges` (structured bounds per marker code)
Intake observation time	`sourceMetadata.sourceTimestamp` (single timestamp for the bundle)
Wellbeing areas to score	`options.requestedOutcomes` (public `wellbeing.*` ids)
Report artefacts	`options.requestedOutputs` (e.g. `json`, `html`, `pdf`, `inference_score_v1`)

Top-level fields

Field	Required	Notes
`schemaVersion`	Yes	Always `canonical_submission_v1`
`partnerId`	Yes	UUID of your PartnerCredential (must match the API key used in `Authorization`; mismatch → `403` `PARTNER_ID_MISMATCH`)
`partnerSubmissionId`	Yes	Your unique submission reference (max 512 chars)
`partnerSubjectId`	Yes	De-identified subject reference — no names, MRNs, email, or addresses
`subject`	Yes	`demographics` required; HY should also send `measurements`, `history`, and `familyHistory`
`markers`	Yes*	Non-empty array of 14 blood markers for Health Yourself
`options`	Yes	`requestedOutputs` required (min 1); `requestedOutcomes` optional (max 8 entries)
`sourceMetadata`	Recommended	`sourceTimestamp`, `sourceSystem`, `labName`, `facilityId`, and `markerRanges`
`questionnaire`	Optional	Future wellbeing Likert / B2B checklist only — not the 36 HY markers
`clinicalExtensions`	Optional	Reserved key bag (max 64 keys); still scanned for disallowed identifier field names
`reportDocuments`	Optional	Alternative to `markers` when submitting report metadata only

* At least one of markers or reportDocuments must be non-empty. Health Yourself always sends the 14-marker panel in markers.

Numeric sentinel (`-1`)

Optional integer and number fields on smoking and family history accept -1 as “not applicable” (TYPE_A_NOT_APPLICABLE in the platform). The server treats -1 like a missing value for branch rules (e.g. stopAge is not considered “set” when -1).

Prefer omitting a key when the intake branch does not collect that field.
Use -1 only when your serializer must send a number but the UI path is “Not applicable”.
Do not use -1 on blood markers[].value — values must be finite numbers within range.

Questionnaire → canonical mapping

Map intake labels to canonical enum values (lowercase snake_case). Omit keys that do not apply; do not send null for optional numbers unless your serializer requires it.

Demographics and measurements

Intake (Q ID)	Canonical path	Canonical values
Q001 Sex at birth	`subject.demographics.sexAtBirth`	`male`, `female`
Q002 Age	`subject.demographics.ageYears` or `birthYear`	`ageYears`: integer `0..120`; or `birthYear`: `1900..2100` (at least one required)
Q003 Weight	`subject.measurements.weightKg`	number `0..300`
Q004 Height	`subject.measurements.heightCm`	number `0..250`
Q005 Self-rated health	`subject.history.overallHealth`	`excellent`, `very_good`, `good`, `fair`, `poor`, `unknown` (map UI labels to lowercase enums)

Optional demographics: ethnicity (string), educationYears (integer 0..40).

Smoking (`subject.history.smoking`)

status (required when smoking is sent): never, former, current, prefer_not_to_say pastFrequency / currentFrequency (when allowed): none, light, moderate, heavy, unknown

UKB / intake label	Canonical frequency
`I have never smoked`	`none`
`Just tried once or twice`	`light`
`Only occasionally`	`light`
`On most or all days`	`heavy`
`No` (current-frequency auto)	`none`

Intake	Canonical field	Rules
Q006 Status	`status`	`Never smoker` → `never`; `Former smoker` → `former`; `Current smoker` → `current`
Q007 Past frequency	`pastFrequency`	Omit when `status` is `never`, `current`, or `prefer_not_to_say`. For `former`, map labels per table above.
Q008 Current frequency	`currentFrequency`	Only when `status: "current"`. Must be omitted for `former`, `never`, and `prefer_not_to_say` (do not send `"none"` on former).
Q009 Current cigs/day	`currentCigsPerDay`	number `0..200` or `-1`. Only for `current`; must be omitted for `former` / `never`.
Q010 Past cigs/day	`pastCigsPerDay`	number `0..200` or `-1`. Omit for `current` / `never`.
Q011 Stop age	`stopAge`	integer `0..120` or `-1`. Required when `status: "former"` (use `-1` on light/occasional former branches if needed). Omit for `current` / `never`.
Q012 Start age	`startAge`	integer `0..120` or `-1`. Heavy current or heavy former branch; otherwise omit.

Current smokers: provide currentCigsPerDay and/or currentFrequency (not unknown) so intensity is defined. Never / prefer not to say: send only status (or omit the whole smoking object for never-only paths); all other smoking keys must be omitted.

Former smoker example (canonical)

"smoking": {
  "status": "former",
  "pastFrequency": "heavy",
  "pastCigsPerDay": 12,
  "startAge": 19,
  "stopAge": 41
}

Do not include currentFrequency or currentCigsPerDay.

Conditions and medications

Intake	Canonical path	Mapping
Q013–Q017	`subject.history.conditions.*`	`Yes` → `true`, `No` → `false` for `hasDiabetes`, `hasDementia`, `hasCardioCerebrovascular`, `hasLungCancer`, `hasKidneyDisease`
Q018 Medication	`subject.history.medications.takesRegularMedication`	`Yes` → `true`, `No` → `false`. If you send a `medications` object, `takesRegularMedication` is required.

Family history (`subject.familyHistory`)

Each parent (father, mother) uses aliveStatus, optional ages, and conditions[].

Intake	Canonical	Mapping
Q019 / Q028 Alive	`aliveStatus`	`Yes` → `alive`; `No` → `deceased`; `I do not know` → `unknown`
Q020 / Q029 Death age	`deathAge`	integer `0..120` or `-1`. Required when `aliveStatus: deceased`. Omit or `-1` when `alive` or `unknown`.
Q021 / Q030 Current age	`currentAge`	integer `0..120` or `-1`. Required when `aliveStatus: alive`. Omit or `-1` when `deceased` or `unknown`.
Q022–Q027 / Q031–Q036	`conditions[]`	Each UI `Yes` adds a code; each `No` omits that code

UI “Yes” for…	`conditions[]` code
Alzheimer’s / Dementia	`alzheimer_disease` and/or `dementia`
Diabetes	`diabetes_mellitus`
Heart disease	`cardiovascular_disease`
High blood pressure	`hypertension`
Lung cancer	`lung_cancer`
Stroke	`cerebrovascular_disease`

All allowed conditions[] codes: diabetes_mellitus, cardiovascular_disease, cerebrovascular_disease, dementia, alzheimer_disease, kidney_disease, lung_cancer, other_malignancy, hypertension, none_known, unknown.

Align aliveStatus with ages. If father is deceased, send deathAge only (omit currentAge). If mother is alive, send currentAge only (omit deathAge). Swapping these causes validation errors.

Blood markers → `markers[]`

Use canonical marker codes in markers[].code (not B### guide ids in the JSON body). Submit exactly 14 rows — one per code, no duplicates. Aliases resolve to the same canonical code (e.g. ALB → ALBUMIN, HBA1C → HBA1C_MMOL_MOL with mmol/mol unit).

B# (guide)	API `code`	Required `unit`	Default analytical value range*
B001	`ALBUMIN`	`g/L`	`15..60`
B002	`ALT`	`U/L`	`3..500`
B003	`ALP`	`U/L`	`5..1500`
B006	`AST`	`U/L`	`3..1000`
B007	`CALCIUM`	`mmol/L`	`1..5`
B008	`CHOL`	`mmol/L`	`0.5..18`
B010	`CYSTATIN_C`	`mg/L`	`0.1..8.99`
B012	`GGT`	`U/L`	`5..1200`
B014	`HDL`	`mmol/L`	`0.05..4.65`
B015	`CRP`	`mg/L`	`0.08..80`
B018	`LDL`	`mmol/L`	`0.26..10.3`
B020	`PHOSPHATE`	`mmol/L`	`0.32..6.4`
B028	`URATE`	`µmol/L`	`89..1785`
B030	`HBA1C_MMOL_MOL`	`mmol/mol`	`15..515.2`

*When sourceMetadata.markerRanges.{CODE} is present for a marker, validation uses your lowerBound..upperBound instead of the preset analytical range. µ / μ in units normalize to the same value as u for comparison. Accepted code aliases (non-exhaustive): ALB, CA, TCHOL / TOTAL_CHOLESTEROL, CYSTATIN, HDL_CHOLESTEROL, C_REACTIVE_PROTEIN, LDL_DIRECT, PHOS, UA, HBA1C (with mmol/mol unit only). Each array element:

{ "code": "ALT", "value": 28, "unit": "U/L" }

value must be a finite number (JSON number preferred).
Optional per-marker observedAt (ISO-8601); otherwise use sourceMetadata.sourceTimestamp for the panel.

Lab reference ranges (`sourceMetadata.markerRanges`)

Provide structured bounds keyed by marker code:

"markerRanges": {
  "ALT": { "unit": "U/L", "lowerBound": 7, "upperBound": 56 }
}

lowerBound must be ≤ upperBound.
unit must match the preset unit for that code (after normalization).
When a code is listed, value validation uses your bounds instead of the default analytical preset.
Unknown keys in markerRanges fail validation.
Omit markerRanges entirely to use server preset analytical ranges only (still validates units, panel size, and duplicates).

Options

"options": {
  "requestedOutputs": ["inference_score_v1", "json", "html"],
  "requestedOutcomes": [
    "wellbeing.cardiovascular",
    "wellbeing.cognitive",
    "wellbeing.renal",
    "wellbeing.respiratory"
  ]
}

Field	Description
`requestedOutputs`	Required array (min 1): `inference_score_v1`, `score`, `json`, `pdf`, `html`
`requestedOutcomes`	Optional, max 8 entries. Public ids: `wellbeing.cardiovascular`, `wellbeing.renal`, `wellbeing.cognitive`, `wellbeing.respiratory`, `wellbeing.general`. Synonyms accepted: `wellbeing.kidney`, `renal.wellbeing` (renal). Legacy aliases (e.g. `cardiovascular_wellbeing_10y`) still normalize server-side. When omitted, the platform resolves defaults from configuration.

Public outcome ids match GET /v1/results → outcomes[].outcomeId.

Validation errors

Stage	HTTP	`error.code`	`details` shape
Zod canonical body	400	`VALIDATION_ERROR`	Zod flatten: `formErrors`, `fieldErrors`
`partnerId` ≠ API key credential	403	`PARTNER_ID_MISMATCH`	—
14-marker panel (codes, units, bounds)	400	`SUBMISSION_VALIDATION_ERROR`	Array of `{ field, message }`

See Errors for examples.

​Overview

​Top-level fields

​Numeric sentinel (-1)

​Questionnaire → canonical mapping

​Demographics and measurements

​Smoking (subject.history.smoking)

​Conditions and medications

​Family history (subject.familyHistory)

​Blood markers → markers[]

​Lab reference ranges (sourceMetadata.markerRanges)

​Options

​Validation errors

​Further reading

Overview

Top-level fields

Numeric sentinel (`-1`)

Questionnaire → canonical mapping

Demographics and measurements

Smoking (`subject.history.smoking`)

Conditions and medications

Family history (`subject.familyHistory`)

Blood markers → `markers[]`

Lab reference ranges (`sourceMetadata.markerRanges`)

Options

Validation errors

Further reading