Using Sahha data as inputs for marketing and CX systems

An educational guide to routing Sahha Scores, Factors, Archetypes, Biomarkers, and Insights into lifecycle messaging, personalization, and experience decisioning.

Modern engagement systems (CRM, lifecycle messaging, CDPs, in-app personalization, rewards, recommendations) are very good at reacting to in-product behavior—sessions, clicks, purchases.

They are less effective at reacting to real-world context: how someone has been sleeping, how consistent their routines have been, whether their week is trending up or down, and what capacity they likely have today.

This guide explains how to use Sahha outputs as decision inputs for marketing and CX systems—so downstream tools can make better calls about timing, effort, tone, and format—without requiring you to build a health data pipeline yourself.

Who this guide is for

Product, growth, and lifecycle teams designing journeys and in-app experiences
Data/engineering teams mapping Sahha payloads into a CDP, warehouse, or internal decision service
Teams using tools like Segment/mParticle/RudderStack, Braze/Iterable/Customer.io/OneSignal, or custom orchestration

The Sahha outputs you should treat as engagement inputs

Scores (state signals)

Sahha Scores are normalized 0.0 → 1.0 measures with a discrete state label (minimal, low, medium, high) and a set of explainable factors. They are designed to be operationally simple and machine-friendly (good for triggers, segmentation, and decisioning).
See: Scores overview in Sahha Docs.

Score types referenced in webhook schemas include: activity, sleep, readiness, wellbeing, mental_wellbeing.

Why this matters in CX: Scores are clean “state” inputs that help you decide when to engage and how much effort to ask for.

Factors (explainability + copy grounding)

Each Score includes an array of factors with their own 0–1 score and state, alongside the measured value, an optional goal, and a unit.
See: Score + Factor schema in Sahha Docs.

Why this matters in CX: Factors are the difference between “generic personalization” and messaging/UI that’s anchored to something concrete.

Archetypes (trait signals for segmentation)

Archetypes are longer-horizon labels derived from weeks of data. They are explicitly positioned for segmentation and personalization, and are refreshed weekly/monthly.

Sahha describes:

Ordinal archetypes (ranked progression; e.g., activity_level)
Categorical archetypes (distinct groups; e.g., sleep_chronotype with values early_bird, night_owl, intermediate)
See: Archetypes in Sahha Docs.

Why this matters in CX: Archetypes are stable inputs for content packaging, send-time strategy, and long-term lifecycle logic.

Biomarkers (metric layer for precision and measurement)

Biomarkers translate raw device data into standardized metrics (deduplicated, aggregated, and updated with less than 1 minute latency). See: Biomarkers in Sahha Docs.

Biomarkers support multiple categories, and webhook schemas indicate categories include activity, sleep, body, vitals, and engagement. (Use the data dictionary to confirm the exact metrics you want.)

Why this matters in CX: Biomarkers let you build precise triggers (“what happened?”) and evaluate impact (“did it change?”) without managing raw data logs.

Insights (pattern layer: Trends and Comparisons)

Insights analyze existing Sahha outputs (scores, factors, biomarkers) and surface higher-level patterns.

Currently documented as live:

Trends (weekly): directional change over a rolling window; state is increasing, decreasing, or stable
Comparisons (daily): position vs global / demographic / baseline with descriptive labels (e.g., very_low, low, average, high, very_high)
See: Insights, Trends, and Comparisons in Sahha Docs.

Why this matters in CX: Insights are “sanity filters” that help you trigger on meaningful change rather than noisy day-to-day fluctuation.

Note: Trends documentation currently indicates webhook delivery is coming soon, so plan on using the Insights API until insight webhooks are available.

Data Logs (raw stream; use selectively)

Data Logs provide unprocessed data for advanced analysis and research. Sahha explicitly recommends Biomarkers for most product use-cases, and Data Logs only when you need raw detail.
See: Data Logs in Sahha Docs.

Why this matters in CX: For engagement systems, raw logs are rarely the right integration surface. Prefer Biomarkers, Scores, Archetypes, and Insights.

Where Sahha fits in a marketing/CX architecture

A practical mental model:

Sahha outputs (Scores, Factors, Archetypes, Biomarkers, Insights)
Routing layer (webhooks or batch API sync)
Profile + event model in your stack (CDP / warehouse / decision service)
Decisioning (rules, experiments, AI workflows)
Delivery (push/email/SMS, in-app, paywalls, content feeds, rewards)

Sahha is most valuable when treated as a context layer that downstream tools can consume as traits and events.

Integration option A: Webhooks (event-driven)

Sahha Webhooks deliver events to your server automatically. Webhook requests include:

X-Signature (HMAC-SHA256 of the payload using your secret)
X-External-Id (your external user identifier)
X-Event-Type (event type string)
See: Webhooks in Sahha Docs.

Webhook event types (current)

The Webhooks page enumerates:

ScoreCreatedIntegrationEvent
BiomarkerCreatedIntegrationEvent
ArchetypeCreatedIntegrationEvent
DataLogReceivedIntegrationEvent
See: Webhooks in Sahha Docs.

Use the Event Reference to parse payload schemas exactly.
See: Webhook Event Reference in Sahha Docs.

Integration option B: Batch pulls (API/warehouse-first)

For workflows like weekly digests, cohort analytics, or nightly segment refresh:

pull Sahha outputs on a schedule
compute segments/modes in your warehouse or service
sync traits to your engagement platform

This is also the default approach for Insights until insight webhooks are available.

Recommended data model: traits + events (both)

Most engagement stacks work better when you keep:

1) Traits (latest snapshot for segmentation)

Examples:

latest sleep score + state
latest activity score + state
current sleep_chronotype archetype
most recent trend state (if you sync Insights)

2) Events (for triggers + attribution)

Examples:

score updated (for journey entry)
archetype assigned (weekly/monthly)
biomarker calculated (daily or intra-day)
trend/comparison updated (when you sync Insights)

This dual model keeps segmentation easy and automation/attribution reliable.

Practical decision framework: Protect / Maintain / Progress

A simple way to turn “health context” into engagement logic is to define three modes.

Protect: reduce cognitive load; lower effort asks; emphasize maintenance
Maintain: reinforce routines; keep asks modest; focus on consistency
Progress: increase challenge/commitment; introduce higher-effort actions

You can compute the mode from one or two Scores, optionally stabilized with Insights.

Example (illustrative):

Low readiness + low sleep → Protect
Medium states → Maintain
High readiness + stable/increasing trends → Progress

The important point is not the exact formula—it’s designing distinct playbooks per mode.

Five high-leverage patterns that use Sahha well

1) Timing and suppression (avoid the wrong moment)

Use Score state and/or Trends to decide:

when not to message
when to delay
when to switch channel (in-app instead of push)

This tends to reduce “message fatigue” without lowering total engagement.

2) Effort scaling (ask less when capacity is low)

Use Score state to choose the size of the ask:

Protect → 1–3 minute actions, minimal steps
Maintain → small routine actions, gentle progression
Progress → challenges, deeper content, higher-intent CTAs

3) Factor-grounded content (make it explainable)

Use Score Factors to personalize copy and UI prompts:

what changed
what lever is most actionable
what the “next smallest step” is

This reduces the risk of generic recommendations because the content has an explicit driver.

4) Archetype-aware packaging (format and cadence)

Use Archetypes for:

send windows (e.g., chronotype)
content style preferences (short vs detailed)
coaching cadence and reinforcement style

Because archetypes are weekly/monthly, they won’t thrash like daily states.

5) Stabilize triggers with Insights (detect real change)

Use Trends and Comparisons to avoid overreacting to a single day:

Trends answer: “Is this improving or worsening?”
Comparisons answer: “Where does this sit vs baseline or population?”

These become strong “when to intervene” inputs for nudges, rewards, or UI shifts.

Implementation checklist (minimal, engagement-first)

Start with 1–2 Scores (commonly sleep, activity, or readiness)
Store both score and state and keep the latest snapshot as traits
Forward Score events as journey triggers
Add 1 Archetype that changes packaging or timing (e.g., sleep_chronotype)
Add Biomarkers only where you need metric precision or measurement
Introduce Insights once you have basic journeys working (to stabilize triggers)

Appendix: Relevant Sahha schemas (quick reference)

Webhook headers (request-level)

From Sahha Webhooks docs:

X-Signature
X-External-Id
X-Event-Type

ScoreCreatedIntegrationEvent (payload)

See: Webhook Event Reference in Sahha Docs.

Common fields include:

id, profileId, accountId, externalId
type, state, score
factors[], dataSources[]
scoreDateTime, createdAtUtc
version

ScoreFactor (inside `factors[]`)

See: Webhook Event Reference and Scores docs.

Fields include:

id, name
value, goal
score, state
unit