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.

Identity & consent

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

1. You provide Lumen with the user's email through the onboarding channel agreed during integration (out-of-band, not via this API).
2. 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.
3. Once consent is granted, Lumen issues a sharedUserId for that user.
4. You retrieve the email-to-sharedUserId mapping via the identity mappings endpoint and store it on your side.
5. 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.
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.

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.