Connect your system to Ellie Care

01What is Ellie Care?

02The players

Six actors. Knowing who's who is half the mental model — the rest of the API falls into place once this is clear.

03How it works

The telecare lifecycle in four steps; the API plugs you in at step 4. Underneath, a single door (api.ellie.care) authenticates you, isolates you by company and zone, and returns only what's yours.

04The watch: what it measures

The watch does three things: it measures continuous vitals while worn, runs on-demand checks, and detects safety events.

Continuous vitals — while the watch is worn

Device signals — technical, not clinical

Delivered through the device.status channel and in GET /devices/{id}. Useful for adherence and operations.

Telecheckups — guided, on-demand measurements

Your system (or an operator) requests a measurement; the watch guides the patient, takes the sample, and returns a result with a status of done/failed/deferred.

Life safety

05Signal vs. alert

The distinction that avoids misunderstandings: Ellie sends you raw signals, not clinical verdicts.

That's why the contract separates clinical events (clinical.event), device status (device.status), and alerts (life). Ellie avoids pre-judging: it gives you the signal so your system can apply its own clinical logic.

06What you can do with the API

Everything is scoped to your company (from the token) and your patients. In business terms:

07First steps and Quickstart

From zero to your first data point, with no real data. The map first, then the code.

# sandbox base (synthetic data)
BASE=https://api-sandbox.ellie.care

# 1) OAuth2 token (empresa_id + zone go inside the token)
TOKEN=$(curl -s -X POST $BASE/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=ellie_sandbox_br -d client_secret=sandbox \
  -d scope="read:patients read:vitals telecheckup:read" \
  | jq -r .access_token)

# 2) your first call — no company parameter (comes from the token)
curl -s $BASE/v1/patients -H "Authorization: Bearer $TOKEN"
curl -s "$BASE/v1/vitals?patient_id=pat_test_001&type=heart_rate" -H "Authorization: Bearer $TOKEN"

Prefer to explore without writing code? Open the interactive reference (try-it against the sandbox).

08Authentication

OAuth 2.0 client-credentials (app-to-app). You register an app → client_id + client_secret. The token is short-lived and carries your empresa_id, your zone, and your scopes.

09Health data: endpoints

Telemetry and telecheckups are served in two forms: raw REST or standard FHIR R4. The edge abstracts away where they come from.

• Telemetry — GET /v1/vitals?patient_id=&type=heart_rate&since=. Types: heart_rate, spo2, skin_temperature, ibi, eda, motion (ENMO actigraphy), steps, calories, ppg/ppg_ir/ppg_red, accel_raw. High volume → cursor + since.
• Per-minute aggregated heart rate — GET /v1/patients/{id}/vitals/heart-rate?start=&end=. Median, max, min, and sample count per minute. Window ≤ 30 days per query; for more, paginate.
• Sleep sessions — GET /v1/patients/{id}/sleep-sessions. Sleep window with averaged signals (HR, EDA, HRV, temperature, actigraphy). Roadmap
• Telecheckups — GET /v1/patients/{id}/telecheckups; requested with POST /v1/telecheckups:request. They always report a status (done/failed/deferred).
• FHIR — GET /v1/fhir/Observation?patient=&code=8867-4 (LOINC). Returns an R4 Bundle. Emotional telecheckup as QuestionnaireResponse.

10Events (webhooks)

You register your URL yourself (self-serve) and Ellie pushes you the raw events (signals, not pre-judged alerts) as CloudEvents. Every delivery is signed with HMAC in X-Ellie-Signature: ALWAYS verify the signature. No-endpoint alternative: polling GET /v1/events (omit since the first time; after that ?since=<next_cursor>).

# 1) register your URL → returns the secret ONCE (save it)
curl -s -X POST $BASE/v1/subscriptions -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://tu-endpoint/hooks","event_types":["clinical.event","device.status"]}'
# → 201 { "id":"sub_…", "secret":"whsec_…", "status":"active", … }

# 2) test the signed delivery end-to-end (literal colon, don't URL-encode it)
curl -s -X POST "$BASE/v1/subscriptions/sub_…:test" -H "Authorization: Bearer $TOKEN"
# → 202 { "status":"delivered", "response_status":200 }

const mac = crypto.createHmac("sha256", WEBHOOK_SECRET).update(rawBody).digest("hex");
if (`sha256=${mac}` !== req.header("X-Ellie-Signature")) return res.status(401).end();

Manage your subscriptions with GET /v1/subscriptions and DELETE /v1/subscriptions/{id}.

11Tenancy, zones, and privacy

Your empresa_id comes from the token — you never send it via query or body, which is why you only see your own patients. Each company has a residency zone and its health data doesn't leave its region.

• A single host (api.ellie.care) routes you to your region based on the token.
• Requesting a patient_id from another tenant returns 404. You only see what's yours.
• The sandbox uses 100% synthetic data (zero real PHI).

12Real use cases

What companies build on top of Ellie. Each one combines a handful of endpoints.

13Sandbox → Production

It's the same API. Going to prod isn't reprogramming: you change 2 values (host + credentials).

14Errors and pagination

Errors arrive as RFC 9457 (application/problem+json), parseable. Pagination is always cursor-based (next_cursor), never offset.

{ "type": "https://api.ellie.care/errors/insufficient-scope",
  "title": "Missing scope read:vitals", "status": 403,
  "detail": "Your token does not include read:vitals." }

15Frequently asked questions

16Glossary

Ready for the endpoint-by-endpoint detail? Open the interactive reference and try it against the sandbox.