Skip to main content
Last updated: 2026-05-25

1) Document Overview and Purpose

This document defines the input-side information that Health Yourself should prepare for the Idunox integration. The following information should be treated as final for Health Yourself data preparation:
  • Health questionnaire — the 36 questions, value shapes, accepted values and ranges, required/conditional logic, user-facing explanations, and intake-flow implementation details.
  • Blood markers — the 14 markers Health Yourself should provide, including required units, accepted intake-validation ranges, and lab-defined reference range data for every marker.
The OpenAPI contract, authentication, endpoint details, response payloads, report delivery, and webhook behaviour are documented in the API Platform and API Reference sections. The definitions in this guide (questionnaire fields, blood markers, conditional logic) should be treated as final for data preparation.

2) Health Questionnaire Markers

The table below defines the subject questionnaire information Health Yourself should collect and validate on its side.

Column Descriptions

ColumnDescription
Marker IDQuestion identifier for reference and discussion, in the format Q001, Q002, and so on.
Marker NameShort canonical marker name used in API payloads.
User-facing questionExact question text Health Yourself should show to the end consumer.
User-facing explanationHelper text or tooltip that can be shown to subjects.
User-facing answersThe answer options or input range that the subject actually sees and selects. Include the expected value shape such as string: Yes, No, integer: 1..200, or number: 0.00..300.00. Auto-set values that are never shown to the subject are excluded from this column.
Required / conditional logicWhether the question is asked to all subjects or only under certain conditions. This determines the questionnaire flow and which follow-up questions are shown.
What to do if not shown to the userWhat Health Yourself should prepare in the payload when a conditional question is not shown to the subject.
Idunox accepted values / rangeValues accepted by POST /v1/submissions after your BFF maps intake answers to canonical JSON (canonical_submission_v1). Lists canonical paths, enums, numeric bounds, and -1 (not applicable). Intake display strings such as Male or Not applicable are not sent on the wire. See Canonical submission JSON.
Integration notesNotes for Health Yourself, including branch logic, data handling, and conditional semantics.

Marker Table

Marker IDMarker NameUser-facing questionUser-facing explanationUser-facing answersRequired / conditional logicWhat to do if not shown to the userIdunox accepted values / rangeIntegration notes
Q001Sex at BirthWhat was your sex at birth?-string: Male, FemaleRequiredAlways shown; value required.subject.demographics.sexAtBirth: male | femaleMap UI Malemale, Femalefemale.
Q002Age (Years)What is your age?-integer: 0..120RequiredAlways shown; value required.subject.demographics.ageYears: integer 0..120 (or birthYear 1900..2100; at least one required)Age anchor for the submission.
Q003Weight (kg)What is your weight (kg)?-number: 0.00..300.00RequiredAlways shown; value required.subject.measurements.weightKg: number 0..300Decimal values accepted.
Q004Height (cm)What is your height (cm)?-number: 0.00..250.00RequiredAlways shown; value required.subject.measurements.heightCm: number 0..250Decimal values accepted.
Q005Self Rated HealthIn general how would you rate your overall health?Self-rated health helps capture important issues that biomarkers and other questions may miss.string: Excellent, Good, Fair, PoorRequiredAlways shown; value required.subject.history.overallHealth: excellent | very_good | good | fair | poor | unknownMap UI labels to lowercase enums (e.g. Goodgood).
Q006Smoking StatusIn terms of cigarette smoking, which case are you?Select Never smoker only if you have never smoked a single cigarette in your life.string: Current smoker, Former smoker, Never smokerRequiredAlways shown; value required.subject.history.smoking.status: never | former | current | prefer_not_to_sayRoot of the smoking tree.
Q007Past Smoking FrequencyIn the past, how often have you smoked cigarettes?-string: Just tried once or twice, Only occasionally, On most or all daysAsk when question Q006 is Former smoker, or when question Q006 is Current smoker and question Q008 is Only occasionallyIf question Q006 is Never smoker, auto-set as I have never smoked; otherwise Not applicablesubject.history.smoking.pastFrequency: none | light | moderate | heavy | unknown. Map On most or all daysheavy, Only occasionallylight, Just tried once or twicelight. Omit when status is never or current; omit for former when not collected.Never-smoker: omit smoking subfields or use status: "never" only.
Q008Current Smoking FrequencyHow often do you smoke cigarettes?-string: Only occasionally, On most or all daysAsk when question Q006 is Current smokerIf question Q006 is not Current smoker, auto-set as Nosubject.history.smoking.currentFrequency: none | light | moderate | heavy | unknown. Map On most or all daysheavy, Only occasionallylight, Nonone. Only when status: current. Must be omitted for former and never.Do not send "none" on former smokers — omit the field.
Q009Current Cigarettes per DayHow many cigarettes do you smoke on average each day?-integer: 1..200Ask when question Q006 is Current smoker and question Q008 is On most or all daysNot applicablesubject.history.smoking.currentCigsPerDay: number 0..200 (or -1). Only when status: current with daily smoking branch. Omit for former.
Q010Past Cigarettes per DayHow many cigarettes did you smoke on average each day?-integer: 1..200Ask when question Q006 is Former smoker and question Q007 is On most or all daysNot applicablesubject.history.smoking.pastCigsPerDay: number 0..200 (or -1). When status: former and heavy past branch. Omit for never/current.
Q011Age Stopped SmokingAt what age did you stop smoking cigarettes?-integer: 0..120Ask when question Q006 is Former smoker and question Q007 is On most or all daysNot applicablesubject.history.smoking.stopAge: integer 0..120 (or -1). Required when status: former (use -1 if not applicable on light/occasional former branch). Omit for never/current.
Q012Age Started SmokingAt what age did you start smoking cigarettes?-integer: 0..120Ask when question Q006 is Current smoker and question Q008 is On most or all days, or when question Q006 is Former smoker and question Q007 is On most or all daysNot applicablesubject.history.smoking.startAge: integer 0..120 (or -1). Heavy current or heavy former branch only; otherwise omit.
Q013Doctor Diagnosed DiabetesHas a doctor ever told you that you have or have had diabetes?Select Yes if you have any of these conditions: Type 1 (also known as insulin-dependent), Type 2 (also known as non-insulin-dependent), gestational diabetes, diabetes related to malnutrition or pancreatitis, steroid-induced diabetes, maturity-onset diabetes (MODY), or an unknown type of diabetes. Select No if none of those apply.string: Yes, NoRequiredAlways shown; value required.subject.history.conditions.hasDiabetes: boolean (true / false)
Q014Doctor Diagnosed DementiaHas a doctor ever told you that you have or have had dementia?Select Yes if you have any of these conditions: Alzheimer’s disease, Vascular dementia, Frontotemporal dementia, Dementia with Lewy bodies, Dementia in other diseases (for example, Parkinson’s disease, Huntington’s disease, prion disease, HIV), or Unknown dementia type. Select No if none of those apply.string: Yes, NoRequiredAlways shown; value required.subject.history.conditions.hasDementia: boolean
Q015Doctor Diagnosed Cardio/CerebrovascularHas a doctor ever told you that you have or have had any cardiovascular or brain blood vessel disease?Select Yes if you have any of these conditions: angina or other ischaemic heart disease, heart attack or myocardial infarction, stroke or cerebral infarction, bleeding in or around the brain, endocarditis, heart valve disease, heart block, cardiac arrest, paroxysmal tachycardia, atrial fibrillation or flutter, heart failure, or transient ischaemic attack TIA. Select No if none of those apply.string: Yes, NoRequiredAlways shown; value required.subject.history.conditions.hasCardioCerebrovascular: boolean
Q016Doctor Diagnosed Lung CancerHas a doctor ever told you that you have or have had lung cancer?Select Yes if you have any of these conditions: lung cancer, bronchial cancer, tracheal cancer, carcinoma in situ of the lung or bronchus, cancer in another or unspecified part of the respiratory system or inside the chest. Select No if none of those apply.string: Yes, NoRequiredAlways shown; value required.subject.history.conditions.hasLungCancer: boolean
Q017Doctor Diagnosed Kidney DiseaseHas a doctor ever told you that you have or have had chronic kidney disease or end-stage kidney disease?Select Yes if you have any of these conditions: chronic kidney disease of any stage (1 to 5), chronic renal failure or kidney failure, long-term dialysis such as haemodialysis or peritoneal dialysis, or a kidney transplant because of kidney failure. Select No if none of those apply.string: Yes, NoRequiredAlways shown; value required.subject.history.conditions.hasKidneyDisease: boolean
Q018Regular Relevant MedicationDo you regularly take any of the following medications?Select Yes if you take any of these medications: blood pressure medication, cholesterol-lowering medication, insulin, hormone replacement therapy, oral contraceptive pill, or mini-pill. Select No if none of those apply.string: Yes, NoRequiredAlways shown; value required.subject.history.medications.takesRegularMedication: boolean (required when medications object is sent)
Q019Father AliveIs your Biological Father still alive?-string: Yes, No, I do not knowRequiredAlways shown; value required.subject.familyHistory.father.aliveStatus: alive | deceased | unknownMap Yesalive, Nodeceased, I do not knowunknown.
Q020Father Age at DeathWhat was the age of your Biological Father when he died?-integer: 0..120Ask when question Q019 is NoNot applicablesubject.familyHistory.father.deathAge: integer 0..120. Required when aliveStatus: deceased. Omit or -1 when alive or unknown.
Q021Father Current AgeWhat is the age of your Biological Father?-integer: 0..120Ask when question Q019 is YesNot applicablesubject.familyHistory.father.currentAge: integer 0..120. Required when aliveStatus: alive. Omit or -1 when deceased or unknown.
Q022Father DementiaDid your Biological Father ever have Alzheimer’s disease or Dementia?This question includes any subtype and any age at diagnosis.string: Yes, NoRequiredAlways shown; value required.subject.familyHistory.father.conditions[]: include alzheimer_disease and/or dementia when UI YesCoded list; omit code when No.
Q023Father DiabetesDid your Biological Father ever have Diabetes?This question includes any subtype and any age at diagnosis.string: Yes, NoRequiredAlways shown; value required.subject.familyHistory.father.conditions[]: include diabetes_mellitus when UI Yes
Q024Father Heart DiseaseDid your Biological Father ever have Heart Disease?This question includes any subtype and any age at diagnosis.string: Yes, NoRequiredAlways shown; value required.subject.familyHistory.father.conditions[]: include cardiovascular_disease when UI Yes
Q025Father High Blood PressureDid your Biological Father ever have High Blood Pressure?This question includes any subtype and any age at diagnosis.string: Yes, NoRequiredAlways shown; value required.subject.familyHistory.father.conditions[]: include hypertension when UI Yes
Q026Father Lung CancerDid your Biological Father ever have Lung Cancer?This question includes any subtype and any age at diagnosis.string: Yes, NoRequiredAlways shown; value required.subject.familyHistory.father.conditions[]: include lung_cancer when UI Yes
Q027Father StrokeDid your Biological Father ever have a Stroke?This question includes any subtype and any age at diagnosis.string: Yes, NoRequiredAlways shown; value required.subject.familyHistory.father.conditions[]: include cerebrovascular_disease when UI Yes
Q028Mother AliveIs your Biological Mother still alive?-string: Yes, No, I do not knowRequiredAlways shown; value required.subject.familyHistory.mother.aliveStatus: alive | deceased | unknown
Q029Mother Age at DeathWhat was the age of your Biological Mother when she died?-integer: 0..120Ask when question Q028 is NoNot applicablesubject.familyHistory.mother.deathAge: integer 0..120. Required when aliveStatus: deceased. Omit or -1 otherwise.
Q030Mother Current AgeWhat is the age of your Biological Mother?-integer: 0..120Ask when question Q028 is YesNot applicablesubject.familyHistory.mother.currentAge: integer 0..120. Required when aliveStatus: alive. Omit or -1 otherwise.
Q031Mother DementiaDid your Biological Mother ever have Alzheimer’s disease or Dementia?This question includes any subtype and any age at diagnosis.string: Yes, NoRequiredAlways shown; value required.subject.familyHistory.mother.conditions[]: include alzheimer_disease and/or dementia when UI Yes
Q032Mother DiabetesDid your Biological Mother ever have Diabetes?This question includes any subtype and any age at diagnosis.string: Yes, NoRequiredAlways shown; value required.subject.familyHistory.mother.conditions[]: include diabetes_mellitus when UI Yes
Q033Mother Heart DiseaseDid your Biological Mother ever have Heart Disease?This question includes any subtype and any age at diagnosis.string: Yes, NoRequiredAlways shown; value required.subject.familyHistory.mother.conditions[]: include cardiovascular_disease when UI Yes
Q034Mother High Blood PressureDid your Biological Mother ever have High Blood Pressure?This question includes any subtype and any age at diagnosis.string: Yes, NoRequiredAlways shown; value required.subject.familyHistory.mother.conditions[]: include hypertension when UI Yes
Q035Mother Lung CancerDid your Biological Mother ever have Lung Cancer?This question includes any subtype and any age at diagnosis.string: Yes, NoRequiredAlways shown; value required.subject.familyHistory.mother.conditions[]: include lung_cancer when UI Yes
Q036Mother StrokeDid your Biological Mother ever have a Stroke?This question includes any subtype and any age at diagnosis.string: Yes, NoRequiredAlways shown; value required.subject.familyHistory.mother.conditions[]: include cerebrovascular_disease when UI Yes
Numeric sentinel: -1 means “not applicable” on optional integer fields (stopAge, currentAge, deathAge, cigarette counts). Prefer omitting the key when the branch does not apply.Parent conditions[] allowed codes: diabetes_mellitus, cardiovascular_disease, cerebrovascular_disease, dementia, alzheimer_disease, kidney_disease, lung_cancer, hypertension, other_malignancy, none_known, unknown.Observation time: set once on sourceMetadata.sourceTimestamp (ISO-8601). Do not send per-question observedAt on the canonical body.

Conditional Trees

Tree 1: Smoking

Tree 2: Biological Father

Tree 3: Biological Mother

3) Blood Markers

Health Yourself should prepare only the 14 blood markers listed below for the initial integration. Values should be numeric and reported in the units shown here. If the measurement lab reports a marker in a different unit, Health Yourself should convert to the Idunox-required unit before submission.

Column Descriptions

ColumnDescription
Blood marker #Reference id from the Idunox master guide (B001, B002, …) for discussions with Idunox.
API marker codeCode to use in markers[].code and sourceMetadata.markerRanges keys.
Blood marker nameFull name of the blood marker.
Required unitMeasurement unit the numeric value should be reported in (markers[].unit).
Idunox accepted values / rangeWhat POST /v1/submissions validates for markers[]: numeric value, required unit, default analytical bounds from the server preset (or your sourceMetadata.markerRanges bounds when supplied for that code).
Lab-defined reference rangeSubmit per code as sourceMetadata.markerRanges.{CODE}{ "unit", "lowerBound", "upperBound" } (structured object, not a display string).

Marker Table

Blood marker #API marker codeBlood marker nameRequired unitIdunox accepted values / rangeLab-defined reference range
B001ALBUMINAlbuming/Lmarkers[]: { "code": "ALBUMIN", "value": number, "unit": "g/L" }; default value bounds 15..60markerRanges.ALBUMIN: { "unit": "g/L", "lowerBound", "upperBound" }
B002ALTAlanine aminotransferaseU/Lcode ALT; value 3..500; unit U/LmarkerRanges.ALT (same object shape)
B003ALPAlkaline phosphataseU/Lcode ALP; value 5..1500; unit U/LmarkerRanges.ALP
B006ASTAspartate aminotransferaseU/Lcode AST; value 3..1000; unit U/LmarkerRanges.AST
B007CALCIUMCalciummmol/Lcode CALCIUM; value 1..5; unit mmol/LmarkerRanges.CALCIUM
B008CHOLCholesterolmmol/Lcode CHOL (aliases TOTAL_CHOLESTEROL, TCHOL); value 0.5..18; unit mmol/LmarkerRanges.CHOL
B010CYSTATIN_CCystatin Cmg/Lcode CYSTATIN_C; value 0.1..8.99; unit mg/LmarkerRanges.CYSTATIN_C
B012GGTGamma glutamyltransferaseU/Lcode GGT; value 5..1200; unit U/LmarkerRanges.GGT
B014HDLCholesterol HDLmmol/Lcode HDL; value 0.05..4.65; unit mmol/LmarkerRanges.HDL
B015CRPC-reactive proteinmg/Lcode CRP; value 0.08..80; unit mg/LmarkerRanges.CRP
B018LDLCholesterol LDLmmol/Lcode LDL; value 0.26..10.3; unit mmol/LmarkerRanges.LDL
B020PHOSPHATEPhosphatemmol/Lcode PHOSPHATE; value 0.32..6.4; unit mmol/LmarkerRanges.PHOSPHATE
B028URATEUrateµmol/Lcode URATE; value 89..1785; unit µmol/L (μ/µ accepted)markerRanges.URATE
B030HBA1C_MMOL_MOLGlycated haemoglobin (HbA1c)mmol/molcode HBA1C_MMOL_MOL (alias HBA1C); value 15..515.2; unit mmol/molmarkerRanges.HBA1C_MMOL_MOL
Validation rules (baseline):
  • All 14 codes must appear exactly once in markers[] with a numeric value.
  • unit must match the required unit for that code (after normalization).
  • If sourceMetadata.markerRanges.{CODE} is present, value must fall within your lowerBound..upperBound and unit must match; otherwise the default analytical bounds in the Idunox column above apply.
  • Optional per-marker observedAt (ISO-8601); otherwise use sourceMetadata.sourceTimestamp for the panel.
Use the Idunox column for intake sanity checks when you are not yet supplying markerRanges. When you supply markerRanges, those bounds replace the default for validation.

4) B2B API payload guidance

Health Yourself should prepare one de-identified submission containing:
  • all 36 questionnaire values mapped into subject.* (following conditionals above),
  • all 14 blood markers in markers[] using canonical codes (ALBUMIN, ALT, … HBA1C_MMOL_MOL),
  • structured lab reference intervals in sourceMetadata.markerRanges,
  • a single intake timestamp in sourceMetadata.sourceTimestamp,
  • options.requestedOutcomes for the four HY wellbeing areas and options.requestedOutputs for desired artefacts.
The API does not accept legacy markers.healthQuestionnaireMarkers / markers.bloodMarkers or top-level requestedAssessments. See Canonical submission JSON and Create Submissions.
Use the default analytical bounds in section 3 for intake sanity checks when lab markerRanges are not yet wired; map the panel into markers[] before submit.

5) Derived Markers

Idunox derives additional input fields from submitted questionnaire and blood markers. Health Yourself should not submit derived markers as separate fields. Submit the complete 36 questionnaire markers and 14 blood markers listed above. The platform derives the remaining model inputs during processing.