Lab results API

This endpoint is for lab and pharmacy partners that need to push finalized structured biomarker results into Clovi over HTTPS in one request (participant context + metrics). It is separate from the screener mobile API (JWT): partners authenticate with a per-lab Bearer token, not a screener login. It is also separate from CoreMedica home-kit / HL7 flows that use a pre-created lab order (LabInteraction); this JSON path does not require an order id.

Endpoint

POST https://app.clovi.com/api/v0/labs/:lab_slug/results

Replace :lab_slug with the slug Clovi assigned (for example lab_a1b2c3d4e5).

Authentication

Send the integration token in the Authorization header:

Authorization: Bearer <your_integration_token>

Clovi stores only a BCrypt digest of the token server-side. Treat the plaintext token like a password: HTTPS only, never log it, rotate if compromised.

Request body

Content-Type: application/json

• metrics (required, object) — Top-level map of biomarker codes to values. Only codes Clovi recognizes are stored; unknown keys are ignored. At least one recognized code is required. Structure:

  {
    "cholesterol": { "value": 195 },
    "hdl": 52,
    "fasting_glucose": { "value": 99 }
  }

  Each value may be a plain number (or string coerced to a number), or an object { "value": <number>, "options": <optional> } if you need structured options later.
• participant (required, object) — Who the results belong to. Partners do not send Clovi’s participant id; use demographics. Include email, or first_name + last_name + born_at (ISO date string), to match an existing participant or create one if there is no match. Optional fields such as sex may be included when creating a record.

Example payload

{
  "participant": {
    "email": "employee@example.com",
    "first_name": "Sam",
    "last_name": "Rivera",
    "born_at": "1988-03-15",
    "sex": "male"
  },
  "metrics": {
    "cholesterol": { "value": 195 },
    "hdl": 52,
    "ldl": 118,
    "triglycerides": 140,
    "fasting_glucose": 99
  }
}

Example using name and date of birth instead of email:

{
  "participant": {
    "first_name": "Sam",
    "last_name": "Rivera",
    "born_at": "1988-03-15"
  },
  "metrics": { "cholesterol": { "value": 210 }, "hdl": 48 }
}

Valid metric keys align with Clovi’s internal measurement field names (for example cholesterol, hdl, calculated_ldl, fasting_glucose, hba1c_dcct). If you need the exact list for your panel, ask Clovi support for the current allowlist for your program.

Successful response

200 OK with JSON:

{
  "lab_result_id": 987,
  "participant_slug": "par_abc123"
}

participant_slug is Clovi’s id for the matched or created participant (for your logs and support). It is not sent in the request. Clovi persists a lab result linked to that participant with your biomarker map. This call does not return a measurement_id or change live measurement data. No LabInteraction row is created or required for this path.

Errors

Typical responses (JSON body includes a human-readable error message where applicable):

• 400 — Invalid JSON body.
• 401 — Missing or malformed Authorization: Bearer header.
• 403 — Token does not match the lab.
• 404 — Unknown lab_slug.
• 422 — Missing or invalid metrics or participant; insufficient identity fields inside participant; or no recognized biomarker codes in metrics.

Example: curl

curl -sS -X POST \
  'https://app.clovi.com/api/v0/labs/YOUR_LAB_SLUG/results' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "participant": {
      "email": "employee@example.com",
      "first_name": "Sam",
      "last_name": "Rivera",
      "born_at": "1988-03-15"
    },
    "metrics": { "cholesterol": { "value": 195 }, "hdl": 52 }
  }'