Sync and read wearable data

Ovok pulls each connection's readings from the provider and writes them as Observation resources about the Patient, in the Patient's project. Your app reads them like any other FHIR data.

When data arrivesCopy Anchor Link

• Daily at 08:00 UTC, for every connection, after the night's sleep has reached the providers.
• On notification, for Withings, Polar and Suunto: when the provider tells Ovok a patient has new data, Ovok syncs that connection about 30 seconds later. Notifications within one 30-second window share one sync. A notification only starts a sync; it never carries data, so the window and the writes are the same as any other sync.
• On demand, when the patient's app calls the sync route, at most once every 15 minutes per connection.

What a sync reads:

syncedThrough on the connection moves only after the readings are written. A sync that fails leaves it, and the Observations, as they were.

What each provider syncsCopy Anchor Link

Heart rate is not the same kind of value everywhere: a sleep or nightly average for Oura, Withings and Polar (Withings adds single measurements), the day's average for WHOOP, and one workout's average for Strava. Read effectivePeriod before comparing values.

• Oura: rest periods and periods the user deleted are not sleep and are skipped.
• WHOOP: only records WHOOP has scored are synced; an unscored or still-open record arrives with a later sync. WHOOP has no step count. Sleep duration is light + deep + REM.
• Strava: records workouts only. A workout without heart rate gives nothing.
• Withings: reads measurements, daily activity and the nightly sleep summary, not the high-frequency sleep series.
• Polar: lists sleep and nightly recharge for its last 28 days only, so a first sync holds 28 days of those and 30 of steps. Nights are dated by the night; steps by the watch's local day. Polar's access cannot be refreshed: once Polar stops accepting it, the connection needs reconnecting.
• Ultrahuman: per-sample heart rate and HRV are not synced, and there is no respiratory rate. Days are UTC dates. Ovok asks one day at a time, so a first sync makes 31 requests; days with no data are skipped. Built without partner access, so metrics may be missing.
• Suunto: daily steps only, until Ovok has partner access. When two sources report one day, the highest count is kept.

Garmin can be connected but is not synced yet: its sync answers 501 SYNC_NOT_SUPPORTED.

Sync on demandCopy Anchor Link

export OVOK_TOKEN='<access token of a patient>'

curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/wearables/connections/oura/sync' \
  --header "Authorization: Bearer ${OVOK_TOKEN}"

{
  "provider": "oura",
  "created": 42,
  "syncedThrough": "2026-10-22T08:00:00.000Z"
}

created counts the Observations this sync created. Readings Ovok already holds are updated in place and not counted, so a repeated sync answers created: 0.

The cooldown counts from syncedThrough, so it also applies just after the daily sync. Within it, the answer is 429 SYNC_TOO_SOON with Retry-After in seconds, and the provider is not asked. Use the errors table to decide what the app shows.

What a wearable Observation looks likeCopy Anchor Link

{
  "resourceType": "Observation",
  "status": "final",
  "meta": {
    "project": "<project id>",
    "tag": [{ "system": "https://api.ovok.com/fhir/CodeSystem/wearables-source", "code": "oura" }]
  },
  "identifier": [
    { "system": "ovok-event-id", "value": "wearable:oura:<patient id>:<record id>:heart_rate" }
  ],
  "category": [
    { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "vital-signs" }] }
  ],
  "code": {
    "coding": [{ "system": "http://loinc.org", "code": "8867-4", "display": "Heart rate" }],
    "text": "Heart rate"
  },
  "subject": { "reference": "Patient/<patient id>" },
  "device": { "display": "Oura" },
  "effectivePeriod": { "start": "2026-10-21T23:12:00+02:00", "end": "2026-10-22T07:03:00+02:00" },
  "valueQuantity": { "value": 54, "system": "http://unitsofmeasure.org", "code": "/min", "unit": "/min" }
}

Codes and unitsCopy Anchor Link

LOINC has no code for RMSSD (80404-7 is SDNN), so HRV uses Ovok's own code system.

Read the dataCopy Anchor Link

All examples use a practitioner or patient token that can read the Patient's Observations.

Everything one provider synced for a patient:

curl --get 'https://api.sandbox.ovok.com/fhir/R4/Observation' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --data-urlencode "subject=Patient/${PATIENT_ID}" \
  --data-urlencode '_tag=https://api.ovok.com/fhir/CodeSystem/wearables-source|oura' \
  --data-urlencode '_sort=-date'

One metric from any wearable, for example nightly HRV:

curl --get 'https://api.sandbox.ovok.com/fhir/R4/Observation' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --data-urlencode "subject=Patient/${PATIENT_ID}" \
  --data-urlencode 'code=https://api.ovok.com/fhir/CodeSystem/wearables|hrv-rmssd' \
  --data-urlencode 'date=ge2026-10-01'

Keep wearable and device readings apartCopy Anchor Link

Only wearable readings: add _tag with the provider, comma-separated for several:

--data-urlencode '_tag=https://api.ovok.com/fhir/CodeSystem/wearables-source|oura,https://api.ovok.com/fhir/CodeSystem/wearables-source|withings'

Everything except wearable readings: add _tag:not with every provider.

curl --get 'https://api.sandbox.ovok.com/fhir/R4/Observation/$lastn' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --data-urlencode "patient=Patient/${PATIENT_ID}" \
  --data-urlencode 'code=8867-4' \
  --data-urlencode '_tag:not=https://api.ovok.com/fhir/CodeSystem/wearables-source|oura,https://api.ovok.com/fhir/CodeSystem/wearables-source|whoop,https://api.ovok.com/fhir/CodeSystem/wearables-source|strava,https://api.ovok.com/fhir/CodeSystem/wearables-source|withings,https://api.ovok.com/fhir/CodeSystem/wearables-source|polar,https://api.ovok.com/fhir/CodeSystem/wearables-source|suunto,https://api.ovok.com/fhir/CodeSystem/wearables-source|garmin,https://api.ovok.com/fhir/CodeSystem/wearables-source|ultrahuman'

$lastn passes extra search parameters such as _tag through to the search. List all eight providers in _tag:not, Garmin included, so the filter keeps working when Garmin starts syncing.

What else to knowCopy Anchor Link

• Not forwarded to Signals. Wearable Observations are never sent for Signals alert evaluation, whether or not the patient is enrolled.
• Disconnecting keeps the data. Observations already written stay. Delete them yourself if your retention rules require it; their ovok-event-id identifier names the provider.
• Reconnect required. When the provider refuses the stored grant, for example after the patient removed your app's access, Ovok marks the connection reconnectRequired and stops syncing it. The patient connects again to resume; the next sync catches up on at most 30 days.
• Values follow the provider. Ovok stores what the provider reports, converted to the units above. It does not validate, smooth or clinically review readings.