Sleep API

A sleep score for every user, wearable or not.

Sahha’s Sleep API returns 14 standardized sleep biomarkers, per-sample sleep stages and a research-backed 0–100 sleep score, from 48 connected sources on one schema. When nothing tracked the night at all, Sahha infers it from passive phone signal and scores it anyway.

Start free Read the docs

Free for 30 days · No credit card

48: connected sources
14: biomarkers
0–100: sleep score
7: archetypes

Data logs

Raw stages, per sample

awake
rem
light
deep
23:10–06:34
Four stages, streamed per sample by webhook rather than as a daily total. In-bed and unspecified records come through too, so a provider’s ambiguity is preserved rather than guessed at.
Biomarkers

Fourteen sleep metrics, daily

sleep_duration7.4hrs
Last 7 nights
sleep_debt
1.2hrs
sleep_regularity
0.91
sleep_efficiency
0.94
One clean value per metric, reconciled across every device a user has connected.
Scores

A 0–100 sleep score that explains itself

Sleep82High
sleep duration
7.4hrs
sleep regularity
0.91
sleep debt
1.2hrs
physical recovery
84min
Seven factors return with it, each carrying its own sub-score.
Archetypes

The sleeper, classified

sleep_qualityGood
sleep_regularityHighly regular
wake_scheduleEarly riser
Seven of Sahha’s fourteen archetypes are sleep archetypes.
Insights

Where this night sits

Sleep scorelast 30 days
68thpercentile
You82
Peers, men 30 to 3571
You sleep 15% better than men aged 30 to 35.
Trends and cohort comparisons on the score and on every sleep factor.
Tags

Context a device can’t see

TagsAugust 2026
MTWTFSS
10111213141516
Mon, Aug 10
alcoholevent
2 drinks21:40
No fixed schema. Define any tag your product needs, then cut any score or biomarker by it.

Why Sahha

The three things a raw sleep feed can’t give you.

Carries a smartphone82–97%
Owns a wearable13–46%
Share of adults across surveyed markets. Build for the first number, not the second.

Every user, not just the ones with a wearable

Wearable ownership runs 13% to 46% across surveyed markets; smartphones run 82% to 97%. When nothing tracked a night, Sahha infers its start and end from passive phone signal, device use and movement, with no microphone and no personal data. That is enough for four of the seven score factors and a full score.
- Oura Ringsame night
- Apple Watchsame night
sleep_duration7.4hrs
One night, not two

A user wearing an Oura ring next to an Apple Watch produces two overlapping records of the same night. Sahha reconciles them into one value per metric per day, so totals stay honest and trends hold when someone changes device. Both raw records stay available, so you can always see which source fed the number.
7
research-backed factors returned with every score

The research is already done.

Raw stage durations leave the modeling, and the clinical liability, with you. A generic score you tune yourself is the same problem wearing a nicer interface. Sahha returns a research-backed 0–100 score with the seven factors behind it, so you can show a user why their night rated the way it did.

Sources

It works with what your users already own.

Every user already carries one of these

Wearables and apps that add stage detail

48 sources ship a documented sleep integration. Any other app writing sleep to Apple Health or Health Connect arrives on the same schema.

Browse all integrations

API reference

Every endpoint, payload and field.

The individual samples underneath everything else, exactly as each device recorded them and each naming the device it came from. This is the one layer delivered by webhook only.

POST your webhook endpoint

[
  {
    "logType": "sleep",
    "dataType": "sleep_stage_deep",
    "externalId": "ext-789",
    "receivedAtUtc": "2026-08-11T06:40:00+00:00",
    "dataLogs": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174003",
        "parentId": null,
        "value": 52,
        "unit": "minute",
        "source": "Oura Ring",
        "recordingMethod": "RECORDING_METHOD_AUTOMATICALLY_RECORDED",
        "deviceType": "Gen3",
        "startDateTime": "2026-08-10T23:25:00+12:00",
        "endDateTime": "2026-08-11T00:17:00+12:00",
        "additionalProperties": {}
      }
    ]
  }
]

Stage log types 6

Field	Description	Unit
sleep_stage_deep	Duration in deep sleep	minute
sleep_stage_rem	Duration in REM sleep	minute
sleep_stage_light	Duration in light sleep	minute
sleep_stage_awake	Duration awake	minute
sleep_stage_in_bed	Duration in bed, not necessarily asleep	minute
sleep_stage_sleeping	Duration actually spent asleep	minute

Four of these are physiological stages; in-bed and sleeping are coverage records. Further types cover sleep a source reported without a stage, so a provider’s ambiguity is preserved rather than guessed at.

The daily rollup: one typed record per metric per day, reconciled across every device a user has connected. This is the layer most apps build on.

GET /api/v1/profile/biomarker/{externalId}?categories=sleep

{
  "id": "b7c8d9e0-f1a2-3456-bcde-f78901234567",
  "type": "sleep_duration",
  "category": "sleep",
  "value": "444",
  "valueType": "long",
  "unit": "minute",
  "aggregation": "total",
  "periodicity": "daily",
  "startDateTime": "2026-08-10T23:10:00+12:00",
  "endDateTime": "2026-08-11T06:34:00+12:00",
  "createdAtUtc": "2026-08-11T18:40:00Z"
}

Sleep biomarkers 14

Field	Description	Unit	Cadence	Wearable
sleep_duration	Total time spent sleeping	minute	daily	Not required
sleep_start_time	Time the individual falls asleep	datetime	daily	Not required
sleep_mid_time	Midpoint of the sleep window	datetime	daily	Not required
sleep_end_time	Time the individual wakes	datetime	daily	Not required
sleep_in_bed_duration	Total time spent in bed	minute	daily	Not required
sleep_debt	Discrepancy between required and actual sleep	hour	weekly	Not required
sleep_regularity	Consistency of sleep patterns over time	index	weekly	Not required
sleep_efficiency	Ratio of sleep time to time in bed, 0 to 1	ratio	daily	Required
sleep_latency	Time to fall asleep after going to bed	minute	daily	Required
sleep_interruptions	Count of awakenings during the night	count	daily	Required
sleep_awake_duration	Time awake after first falling asleep	minute	daily	Required
sleep_light_duration	Time spent in light sleep	minute	daily	Required
sleep_rem_duration	Time spent in REM sleep	minute	daily	Required
sleep_deep_duration	Time spent in deep sleep	minute	daily	Required

Seven of the fourteen need no wearable. Where nothing tracked the night, Sahha estimates the sleep window from passive phone signal and those seven still populate.

The score plus every contributing factor, each carrying its own sub-score and the goal it was measured against.

GET /api/v1/profile/score/{externalId}?types=sleep

{
  "type": "sleep",
  "score": 0.82,
  "state": "high",
  "factors": [
    { "name": "sleep_duration", "value": 7.4, "goal": 8.0, "unit": "hour", "score": 0.88, "state": "high" },
    { "name": "sleep_regularity", "value": 0.91, "goal": 1.0, "unit": "index", "score": 0.91, "state": "high" },
    { "name": "sleep_debt", "value": 1.2, "goal": 0.0, "unit": "hour", "score": 0.64, "state": "medium" },
    { "name": "physical_recovery", "value": 84.0, "goal": 90.0, "unit": "minute", "score": 0.79, "state": "medium" }
  ],
  "scoreDateTime": "2026-08-11T00:00:00+12:00",
  "dataSources": ["age", "sleep"],
  "version": 1.1
}

Score factors 7

Factor	What it measures
sleep_duration	Total time spent asleep
sleep_regularity	Consistency of sleep schedule
sleep_continuity	Uninterrupted sleep with minimal awakenings
sleep_debt	Accumulated sleep deficit
circadian_alignment	Alignment with the natural sleep-wake cycle
physical_recovery	Deep sleep phase duration
mental_recovery	REM sleep phase duration

Sub-scores are research-backed curves, not a value divided by its goal. A factor sitting at 80% of target does not score 80.

A classification with its position on the scale, so you can segment without asking the user a single question.

GET /api/v1/profile/archetypes/{externalId}

{
  "id": "91ced284-5355-57f0-b162-1ac920a42371",
  "name": "sleep_regularity",
  "value": "highly_regular_sleeper",
  "dataType": "ordinal",
  "ordinality": 3,
  "periodicity": "monthly",
  "startDateTime": "2026-08-01T00:00:00+12:00",
  "endDateTime": "2026-08-31T00:00:00+12:00",
  "createdAtUtc": "2026-09-01T13:08:53.322886Z"
}

Sleep archetypes 7

Archetype	Type	What it captures
sleep_duration	Ordinal	Typical sleep duration relative to norms
sleep_efficiency	Ordinal	Sleep maintenance effectiveness
sleep_quality	Ordinal	Long-term sleep quality assessment
sleep_regularity	Ordinal	Consistency in sleep timings
sleep_pattern	Categorical	Overall sleep behavior patterns
bed_schedule	Ordinal	Typical bedtime patterns
wake_schedule	Ordinal	Typical wake-up time patterns

Seven of Sahha’s fourteen archetypes are sleep archetypes. Recomputed weekly and monthly.

The same score placed against a matched cohort. The population baseline is the part you cannot build yourself.

GET /api/v1/profile/insight/comparison/{externalId}

{
  "name": "sleep",
  "category": "score",
  "value": 0.82,
  "data": [
    {
      "type": "demographic",
      "value": 0.71,
      "percentile": 0.68,
      "percentageDifference": 0.15,
      "properties": { "sex": "male", "ageRange": "30-35" }
    }
  ],
  "startDateTime": "2026-07-13T00:00:00+12:00",
  "endDateTime": "2026-08-11T00:00:00+12:00"
}

Sleep signals with insights 8

Signal	Type	Available as
sleep	score	Trend and comparison
sleep_duration	factor, biomarker	Trend and comparison
sleep_regularity	factor	Trend
sleep_continuity	factor	Trend
sleep_debt	factor	Trend
circadian_alignment	factor	Trend
physical_recovery	factor	Trend
mental_recovery	factor	Trend

Every one of the seven score factors is tracked as its own trend, so you can see which part of a night is moving rather than only that the total moved. The score and duration also compare against a matched cohort.

The layer that runs both ways. Reserved tags such as sleep_changes and fatigue arrive on their own when a user logs them in their phone’s health app; anything else your product tracks you post yourself, and the same path reads it all back with GET. Tags are either a state with a duration, as here, or a point-in-time event.

POST /api/v1/profile/tag/{externalId}

{
  "type": "state",
  "category": "work",
  "name": "night_shift",
  "value": "12_hour",
  "source": "acme.sleepapp",
  "startDateTime": "2026-08-10T19:00:00+12:00",
  "endDateTime": "2026-08-11T07:00:00+12:00",
  "additionalProperties": {
    "role": "icu_nurse"
  }
}

The ideas behind the fields, rather than the fields themselves. Each links to the guide that covers it in full.

Sleep debt: The gap between the sleep someone needed and the sleep they got, accumulated over a rolling window. Measured against a personal baseline, not a fixed eight-hour target. Read the guide
Sleep regularity: How consistent bed and wake times are from one day to the next, scored independently of how long the person actually slept. Read the guide
Sleep latency: How long it takes to fall asleep after going to bed. Needs a wearable, since a phone cannot see the moment sleep begins. Read the guide
Circadian alignment: Whether the sleep window sits where the body clock expects it. Two people with identical durations can score differently on this alone. Read the guide
Sleep efficiency: Time asleep divided by time in bed, from 0 to 1. What separates a restless eight hours from a solid six.
Physical and mental recovery: Two separate score factors. Physical recovery tracks deep sleep, mental recovery tracks REM, and a night can be strong on one while weak on the other. Read the guide

REST API
Pull any of it on demand, per profile, whenever your app asks.
Webhooks
Or have it pushed to your endpoint as it arrives, so you never have to poll for it.
Mobile SDK
Read straight from the device on iOS and Android, with no round trip.

What you build

What one night’s data lets you ship.

Explain the night

Render the score with the seven factors behind it, so someone who woke up tired can see which part of the night caused it.

Sahha Scores

Adapt today’s plan

Read last night’s duration, debt and efficiency and adjust the plan. A lighter session after a rough night reads as attentive rather than generic.

Sahha Biomarkers

Catch the drift

Spot regularity sliding against a user’s own baseline, weeks before they would mention it or quietly stop opening the app.

Sahha Insights

Segment by sleeper

Build cohorts on archetypes computed from behavior, instead of asking people to describe their own sleep in an onboarding survey.

Sahha Archetypes

Close the loop

Let someone log a late shift or a drink, then show them what it did to the score. The tag is how you capture it; the correlation is what they came for.

Sahha Tags

Prove it worked

Report sleep improving across a population against a benchmark you could not build yourself, for an employer, a payer or a study.

Workplace wellness

How it compares

Three ways to get sleep data into your app.

	Sahha Sleep API	Other health APIs	Build it yourself
Works with no wearable			Timing only
Deduplicated across devices			On you
Research-backed 0 to 100 score		Generic or tunable	On you
Factors behind the number	All seven
Sleep archetypes
Cohort benchmark			No population
Time to ship	Days	Weeks	Months

Other health APIs = wearable and health-data APIs that also offer scores. Generic or customizable scores leave validation, and the liability, with you. Build it yourself = reading HealthKit and Health Connect directly.

What building it yourself actually costs

FAQ

Questions that come up before you integrate.

Can I get sleep data from a user with no wearable?

Yes. Duration, in-bed duration, start, mid and end times, regularity and debt, plus a full 0 to 100 score built on four of its seven factors. Where nothing recorded the night at all, Sahha estimates the sleep window from passive smartphone signal, device use and movement. Stage detail (REM, deep, light, awake), efficiency, latency and interruption counts do need a wearable, because a phone cannot observe them.

Which devices provide sleep stages?

Oura, WHOOP, Garmin, Samsung Health, Withings, Ultrahuman, RingConn, Eight Sleep, Amazfit, Coros, Biostrap and Muse, among others: 28 sources report REM, deep and light separately. A further set contributes sleep timing without stages, for 48 delivering sleep data in total, all on the same normalized schema.

What happens when a user has two devices tracking the same night?

Sahha reconciles them before you see the data. Someone wearing an Oura ring next to an Apple Watch produces two overlapping records of one night; you receive a single value per metric, so totals stay honest and trends hold when they switch device.

Is sleep data real time, or only daily?

Both. Raw stage logs are pushed by webhook immediately, as each sample arrives. Scores and biomarkers can be pushed too, on a delivery interval you configure: it acts as a deduplication window, so repeated updates to the same metric collapse into a single send rather than flooding your endpoint. Set it to real time and every update goes out as it happens. All of it is also readable on demand over REST.

How far back does data go when a user connects?

Sahha backfills up to 30 days on connect, so a score has the baseline it needs and personalization works from the first session rather than after weeks of waiting.

How is the sleep score calculated?

From seven research-backed factors: duration, regularity, continuity, debt, circadian alignment, physical recovery and mental recovery. Each returns its own sub-score alongside the total, so you can show a user which part of the night drove the number. The sub-scores are non-linear curves, not a value divided by a goal.

Do I need my own developer account with Oura or Garmin?

For cloud sources such as Oura, Garmin, WHOOP, Polar and Withings, yes, and deliberately so. You register your own developer app with the provider and give Sahha the credentials, which means your brand appears on the consent screen your users see and you get your own rate limits rather than sharing a pool. Sahha runs everything after that: ingestion, backfill, normalization, deduplication, scoring, and maintenance as those APIs change. Apple Health and Health Connect need no third-party registration at all.

Is Sahha HIPAA and GDPR compliant?

Yes, and SOC 2. Health data is handled under all three, and on cloud integrations the end-user consent screen carries your brand rather than Sahha’s.

Add sleep to your app in days.

One integration for the sources your users already own, with the modeling and the maintenance already done.

Start building Book a demo

Free for 30 days · No credit card

Every user covered, including the ones with no tracker
14 biomarkers and per-sample stages on one schema
Webhooks as data arrives, or REST on demand
HIPAA, GDPR and SOC 2, with your brand on the consent screen

A sleep score for every user, wearable or not.

Raw stages, per sample

Fourteen sleep metrics, daily

A 0–100 sleep score that explains itself

The sleeper, classified

Where this night sits

Context a device can’t see