Processing and Storing Neurofit Vitals Scan Results

Every completed scan produces a VitalsResult object that contains the measured biometrics, a quality verdict, per-scan signal diagnostics, and metadata. Before reading any metric value, your code must inspect qualityTier — the single most important field in the result. This page explains the full data model, the correct way to branch on quality, and how to persist results in your own data store.

Understanding QualityTier

The SDK evaluates signal quality throughout the 60-second scan and assigns every result one of two quality tiers at completion.

.accepted / ACCEPTED

Signal quality met the SDK’s validation threshold. All metric fields are populated and the reading is reliable enough to display to the user or store in your data model.

.withheld / WITHHELD

The signal was too noisy or unstable to produce a reliable reading. Metric fields are not populated. Show a retry prompt — never display withheld values.

Never display or store metric values from a withheld result. The numeric fields in a WITHHELD result are undefined placeholders, not real measurements. Always gate on qualityTier before reading any metric field.

A minimal quality-tier guard looks like this in both languages:

Swift
Kotlin

Quality gate

func vitalsScan(_ scan: VitalsScan, didComplete result: VitalsResult) {
    guard result.qualityTier == .accepted else {
        showRetryPrompt()
        return
    }
    displayMetrics(result)
}

Quality gate

private fun handleVitalsResult(result: VitalsResult) {
    if (result.qualityTier != QualityTier.ACCEPTED) {
        showRetryPrompt()
        return
    }
    displayMetrics(result)
}

VitalsResult field reference

The full result type is defined identically on both platforms, with idiomatic adjustments for nullability and date types.

iOS (Swift)
Android (Kotlin)

VitalsResult

struct VitalsResult {
    let qualityTier: QualityTier     // .accepted or .withheld
    let heartRate: Double            // Heart rate in bpm
    let rmssd: Double                // HRV RMSSD in ms
    let sdnn: Double                 // HRV SDNN in ms
    let baevsky: Double              // Baevsky stress index (natural log)
    let poincareSD2SD1: Double       // Poincaré SD2:SD1 ratio (dimensionless)
    let breathingRate: Double?       // Respiration rate in bpm; nil if confidence too low
    let diagnostics: ScanDiagnostics // Per-scan signal quality metadata
    let scanDurationSeconds: Int     // Always 60
    let timestamp: Date              // When the scan completed (device local time)
}

VitalsResult

data class VitalsResult(
    val qualityTier: QualityTier,
    val heartRate: Double,            // Heart rate in bpm
    val rmssd: Double,                // HRV RMSSD in ms
    val sdnn: Double,                 // HRV SDNN in ms
    val baevsky: Double,              // Baevsky stress index (natural log)
    val poincareSD2SD1: Double,       // Poincaré SD2:SD1 ratio (dimensionless)
    val breathingRate: Double?,       // Respiration rate in bpm; null if confidence too low
    val diagnostics: ScanDiagnostics,
    val scanDurationSeconds: Int,     // Always 60
    val timestamp: Instant            // UTC instant when the scan completed
)

Each field is described in detail below.

heartRate — Double (bpm)

The average heart rate measured across the full 60-second scan window, expressed in beats per minute. This is the primary output of the scan and is always present in accepted results. Typical resting values for healthy adults fall between 50 and 100 bpm.

rmssd — Double (ms)

Root mean square of successive differences between adjacent R-R intervals, expressed in milliseconds. RMSSD is the most widely used time-domain HRV metric and is particularly sensitive to parasympathetic nervous system activity. Higher values generally indicate greater autonomic flexibility.

sdnn — Double (ms)

Standard deviation of all normal-to-normal R-R intervals across the scan window, expressed in milliseconds. SDNN captures both sympathetic and parasympathetic contributions to heart rate variability and is commonly used as an overall HRV index.

baevsky — Double (dimensionless ln)

The Baevsky Stress Index, expressed as a natural logarithm of the ratio of the histogram peak amplitude to the mean R-R interval and SDNN. It is a non-linear HRV index used to estimate autonomic regulatory tension. Lower ln values indicate lower sympathetic stress load.

poincareSD2SD1 — Double (dimensionless ratio)

The ratio of the long-axis standard deviation (SD2) to the short-axis standard deviation (SD1) from a Poincaré plot of R-R intervals. A higher ratio suggests a greater contribution of long-term HRV components relative to short-term beat-to-beat variation.

breathingRate — Double? / Double? (bpm, nullable)

Respiration rate estimated from the respiratory sinus arrhythmia signal embedded in the R-R interval series, expressed in breaths per minute. This field is confidence-gated: it will be nil / null in some accepted readings when the breathing modulation in the signal was not strong enough to produce a reliable estimate. Treat a nil / null value as “not available this scan” and omit it from your display rather than showing a fallback number.

diagnostics — ScanDiagnostics

A structured object containing per-scan signal quality metrics such as motion artifact score, signal-to-noise ratio, and coverage percentage. Use these fields to build developer-facing diagnostics dashboards or to log scan health alongside your result records.

scanDurationSeconds — Int

The duration of the completed scan in seconds. This field is always 60 in the current SDK version. It is included in the result model to make stored records self-describing and to accommodate potential future scan-length options.

timestamp — Date / Instant

The moment the scan completed, recorded in device local time on iOS (Date) and as a UTC Instant on Android. Always persist this field alongside your metrics so you can reconstruct a timeline of readings.

Storing results

Scan data belongs entirely to you — no results are transmitted to Neurofit servers. Because the SDK performs all processing on-device, your application is the sole custodian of user health data. Follow your platform’s data protection guidelines (HealthKit on iOS, Android Health Connect, or your own encrypted database) when persisting results. Include the following fields in every stored record to ensure your data model is complete and auditable:

Field	Why it matters
`timestamp`	Enables time-series analysis and trend visualization
`qualityTier`	Lets you filter out any withheld results that were stored by mistake
`scanDurationSeconds`	Makes records self-describing; useful if scan lengths change in a future SDK version
Platform & SDK version	Allows you to detect and handle any metric changes across SDK releases
`heartRate`, `rmssd`, `sdnn`, `baevsky`, `poincareSD2SD1`	Core HRV metrics for all downstream analysis
`breathingRate` (nullable)	Include if non-nil; omit or mark explicitly as unavailable when nil

Because scan data is processed and stored locally, you are responsible for complying with applicable privacy regulations (GDPR, HIPAA, etc.) when storing or transmitting this data from your own backend. The Neurofit Vitals SDK is not a medical device and its outputs should not be used for clinical diagnosis or treatment decisions.

When serializing results to JSON for your backend, use ISO 8601 strings for timestamps and record metric units (bpm, ms) in your schema definition rather than relying on field-name conventions. This prevents unit confusion if your data model evolves.

Metrics Overview

Detailed explanations of every biometric output, including physiological context and normal reference ranges.

iOS Result Types

Full Swift API reference for VitalsResult, QualityTier, ScanDiagnostics, and VitalsError.

Android Result Types

Full Kotlin API reference for VitalsResult, QualityTier, ScanDiagnostics, and VitalsException.

Overview

Getting Started

Integration Guide

Metrics Reference

Help

Processing and Storing Neurofit Vitals Scan Results

Understanding QualityTier

.accepted / ACCEPTED

.withheld / WITHHELD

VitalsResult field reference

Storing results

Metrics Overview

iOS Result Types

Android Result Types

​Understanding QualityTier

.accepted / ACCEPTED

.withheld / WITHHELD

​VitalsResult field reference

​Storing results

​Related references

Metrics Overview

iOS Result Types

Android Result Types

Understanding QualityTier

VitalsResult field reference

Storing results

Related references