Alerts¶

Beta

The Alerts API is in beta. Behavior, field names, and alert types may change before general availability. Contact integration support before relying on it in production.

The Alerts API lets you retrieve daily, user-level alerts produced by Lumen's analysis of your enrolled users' metabolic and behavioral data. Alerts surface meaningful changes in weight, metabolic flexibility (FLEX), and medication adherence so you can prioritize outreach and intervention.

The API is read-only. Alerts are produced once per day. Each call to the alerts endpoint returns the latest alert per user per type for a single calendar date.

Privacy posture¶

No PII is returned by this API. Email, name, phone, and date of birth are never transmitted.
Alerts are returned only for users who have actively granted consent for your organization in the Lumen app. Consent can be revoked at any time, after which the user no longer appears in your responses.

The `sharedUserId`¶

Every alert is keyed by a sharedUserId, a UUID Lumen issues per user, scoped to your partnership. You use the sharedUserId on every alerts API call. The same Lumen user has a different sharedUserId for each partner, so user identifiers are never shareable across partners.

The sharedUserId is stable for the life of the user's consent with you. If a user revokes consent, the sharedUserId is retained, and consent can be re-activated later without changing it.

How a user gets linked to your account¶

You provide Lumen with the user's email through the onboarding channel agreed during integration (out-of-band, not via this API).
When the user opens the Lumen app and is recognized as one of your enrolled users, they are prompted to grant consent for you to receive their alerts.
Once consent is granted, Lumen issues a sharedUserId for that user.
You retrieve the email-to-sharedUserId mapping via the identity mappings endpoint and store it on your side.
From that point on, you call the alerts endpoint using sharedUserId. The mapping back to the user's identity stays on your side.

If a user revokes consent, they stop appearing in your alerts API responses. They are not flagged or surfaced in any other way.

Get identity mappings¶

GET /partners/v1/identity-mappings

Returns the email-to-sharedUserId mappings for users who granted consent after a given timestamp. Use this to reconcile new consents into your own records. Recommended polling cadence: hourly.

Headers¶

Header	Type	Required	Description
`X-Partner-Api-Key`	string	Yes	Your partner API key

Query parameters¶

Parameter	Type	Required	Description
`grantedAfter`	string (ISO 8601)	No	Return mappings granted strictly after this timestamp. Defaults to the start of the current day in UTC.

cURL¶

curl -X GET "https://{baseUrl}/partners/v1/identity-mappings?grantedAfter=2026-05-04T00:00:00Z" \
  -H "X-Partner-Api-Key: YOUR_API_KEY"

Response (200 OK)¶

{
  "success": true,
  "data": {
    "mappings": [
      {
        "email": "user@example.com",
        "sharedUserId": "5d3b1c44-9e8a-4f2d-9c7e-6d0a3b1f7c21",
        "grantedAt": "2026-05-04T10:22:14Z"
      }
    ]
  }
}

Get alerts¶

GET /partners/v1/alerts

Returns the latest alert per (user, alert type) for the requested date.

Headers¶

Header	Type	Required	Description
`X-Partner-Api-Key`	string	Yes	Your partner API key

Query parameters¶

Parameter	Type	Required	Description
`date`	string (`YYYY-MM-DD`)	No	The calendar date to retrieve alerts for, in your account's timezone. Defaults to today. Must be within the last 14 days.

The endpoint takes no other filters. To narrow by user, alert type, or severity, filter the response array on your side.

cURL¶

curl -X GET "https://{baseUrl}/partners/v1/alerts?date=2026-05-04" \
  -H "X-Partner-Api-Key: YOUR_API_KEY"

Response (200 OK)¶

{
  "success": true,
  "data": {
    "date": "2026-05-04",
    "alerts": [
      {
        "sharedUserId": "5d3b1c44-9e8a-4f2d-9c7e-6d0a3b1f7c21",
        "alertType": "WEIGHT",
        "alertSubtype": "TOO_FAST",
        "severity": "HIGH",
        "generatedAt": "2026-05-05T03:14:22Z",
        "details": {
          "currentWeightKg": 78.4,
          "weeklyPctChange": -2.6,
          "logsUsed": 14,
          "lastLogDate": "2026-05-04"
        }
      },
      {
        "sharedUserId": "9f0a8b22-1c34-4d56-8e7f-0a1b2c3d4e5f",
        "alertType": "FLEX",
        "alertSubtype": "PLATEAU",
        "severity": "MEDIUM",
        "generatedAt": "2026-05-05T03:14:22Z",
        "details": {
          "stage": "PLATEAU",
          "segmentStart": "2026-04-10",
          "segmentEnd": "2026-05-04",
          "ratePctPerWeek": -0.05
        }
      },
      {
        "sharedUserId": "2e75c801-3b4a-4f5d-9e6f-7a8b9c0d1e2f",
        "alertType": "MEDICATION",
        "alertSubtype": "MISSED_DOSE_HIGH",
        "severity": "HIGH",
        "generatedAt": "2026-05-05T03:14:22Z",
        "details": {
          "missedDoses7d": 5,
          "scheduledDoses7d": 7,
          "adherencePct7d": 28.6,
          "lastLoggedDoseAt": "2026-04-30T08:11:00Z",
          "consecutiveMisses": 4
        }
      }
    ]
  }
}

Top-level response fields¶

Field	Type	Description
`data.date`	string (date)	The calendar date the response covers.
`data.alerts[]`	array	Alerts for your consented users on `data.date`. Sorted by severity, then most recent.
`data.alerts[].sharedUserId`	string (UUID)	The user's identifier within your partnership. See The sharedUserId.
`data.alerts[].alertType`	enum	One of `WEIGHT`, `FLEX`, `MEDICATION`. Full subtype reference in Alert types.
`data.alerts[].alertSubtype`	enum	See Alert types for the full list per `alertType`.
`data.alerts[].severity`	enum	One of `HIGH`, `MEDIUM`, `LOW`.
`data.alerts[].generatedAt`	string (ISO 8601)	When Lumen produced the alert.
`data.alerts[].details`	object	Type-specific payload. Schema per alert type in Alert types.

Alert types¶

Every alert has a stable (alertType, alertSubtype) pair, a severity, and a typed details payload. Severity is set deterministically from the subtype.

New subtypes may be added in future minor versions. Treat any unknown subtype as LOW severity and pass it through.

Select a type below for its subtypes and details schema.

WEIGHTFLEXMEDICATION

At most one WEIGHT alert per user per day, reflecting the user's current weight-change trajectory.

`alertSubtype`	Severity	Meaning
`IN_RANGE`	LOW	Healthy loss pace (between -2.0% and -0.1% per week). No action needed.
`TOO_SLOW`	MEDIUM	Loss has stalled or reversed slightly (pace above -0.1% per week). Worth checking adherence.
`TOO_FAST`	HIGH	Loss exceeds the safe corridor (pace below -2.0% per week). Risk of muscle loss.
`AT_GOAL`	LOW	User has reached their target weight. Consider switching to maintenance.
`FIRST_LOG`	LOW	The user's first weigh-in. Baseline established, no trend yet.

details schema

Field	Type	Description
`currentWeightKg`	number	Most recent weight, smoothed.
`weeklyPctChange`	number	Signed percent change vs. the prior week.
`logsUsed`	integer	Number of weight logs that contributed to the calculation.
`lastLogDate`	string (date)	Date of the most recent log used.

Lumen's metabolic-flexibility-aware signal, derived from a user's logs over time. FLEX surfaces only the two patterns that warrant clinical attention.

`alertSubtype`	Severity	Meaning
`DRAMATIC_DROP`	HIGH	Flex score has fallen sharply over a sustained window. Significant adverse drift, warrants outreach.
`PLATEAU`	MEDIUM	Flex score has shown no meaningful movement over a sustained window.

details schema

Field	Type	Description
`stage`	enum	Same value as `alertSubtype`, repeated for convenience.
`segmentStart`	string (date)	First day of the current trend segment.
`segmentEnd`	string (date)	Last day of the current trend segment.
`ratePctPerWeek`	number	Rate of change across the segment.

Tracks scheduled-dose adherence over a rolling 7-day window. At most one MEDICATION alert per user per day.

`alertSubtype`	Severity	Meaning
`MISSED_DOSE_LOW`	LOW	Minor slippage (1 missed dose in the last 7 days, adherence at or above 80%). Routine reminder.
`MISSED_DOSE_MEDIUM`	MEDIUM	Concerning pattern (2-3 missed doses in the last 7 days, adherence between 60% and 80%). Outreach recommended.
`MISSED_DOSE_HIGH`	HIGH	Severe non-adherence (4 or more missed doses in the last 7 days, or no logged dose in the last 72 hours). Escalate.

details schema

Field	Type	Description
`missedDoses7d`	integer	Doses missed in the last 7 days.
`scheduledDoses7d`	integer	Doses scheduled in the last 7 days.
`adherencePct7d`	number	`(scheduled - missed) / scheduled * 100`. Range [0, 100].
`lastLoggedDoseAt`	string (ISO 8601) \| null	Timestamp of the most recent logged dose, or `null` if none on file.
`consecutiveMisses`	integer	Length of the current consecutive missed-dose run.

Daily generation timing¶

Lumen's daily analysis runs once per day and completes by 06:00 UTC. If you call the alerts endpoint without specifying date (or with today's date) before generation completes, you receive the most recent available alerts, typically yesterday's. The generatedAt field tells you when each alert was produced.

Retention¶

Alerts are available for the last 14 days. Requesting a date older than 14 days returns 409 DATE_UNAVAILABLE.

Errors¶

HTTP	code	Description
400	`INVALID_INPUT`	Malformed query (e.g. bad `date` format).
401	`UNAUTHORIZED`	Missing or invalid API key.
409	`DATE_UNAVAILABLE`	The requested `date` is older than 14 days or in the future.
429	`RATE_LIMIT`	Too many requests. The `Retry-After` header indicates how long to wait.

Alerts¶

Privacy posture¶

Identity & consent¶

The sharedUserId¶

How a user gets linked to your account¶

Get identity mappings¶

Headers¶

Query parameters¶

cURL¶

Response (200 OK)¶

Get alerts¶

Headers¶

Query parameters¶

cURL¶

Response (200 OK)¶

Top-level response fields¶

Alert types¶

Daily generation timing¶

Retention¶

Errors¶

The `sharedUserId`¶