API reference

Authentication

Every request carries a bearer token. Two kinds work, and they reach exactly the same routes.

API keys

An admin creates a key under Admin, API and integrations, picks its scopes and, for a health system with several sites, the sites it may reach. The key is shown once and hashed at rest. Send it as a bearer token.

Authorization: Bearer lmg_live_...

A key beginning lmg_test_ reaches a sandbox copy of your organization seeded with synthetic patients. Nothing written with a test key touches your real data, so a first request is impossible to regret.

OAuth 2.0 client credentials

For an integration service that should hold a client id and secret rather than a key. A client is created against an existing key and inherits its scopes, sites, environment and revocation. Exchange the credentials for an access token that lasts one hour, then send the token as a bearer.

POST /api/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=lmg_client_...&client_secret=lmg_cs_...

Scopes

A credential carries the scopes it was created with. A request to a route whose scope the credential lacks is refused with 403 missing_scope.

• patients:read
• patients:write
• appointments:read
• appointments:write
• pedigrees:read
• eligibility:read
• results:read
• results:write
• recontact:read
• guidelines:read
• locations:read
• locations:write
• calls:read

Revoking a key takes effect on the next request, and revokes any client created against it.

Requests and writes

Bodies are JSON. Responses are JSON with a data field, or an error field and a message you can show to a person.

Idempotency-Key

Every write (POST and PATCH) requires an Idempotency-Key header, any string unique to the attempt. A retry with the same key replays the first response instead of writing twice. The same key with a different body is refused with 409.

Idempotency-Key: 6f1c2d5e-appointment-84213

Validation

A write body is checked against the fields listed for the resource. A field the resource does not have is refused rather than dropped, and the response names every field that did not validate.

Rate limits

Each credential may make 600 requests per minute. Past that the response is 429 with a Retry-After header and X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Limits are per credential, not per organization, so one script cannot starve another.

Sites

A credential scoped to particular sites reads and writes only records at those sites. A write naming another site is refused with 403 location_out_of_scope.

Every write an integration makes is recorded in your organization's audit log against the credential that made it.

Errors

Errors carry an error code for your program and a message for a person.

Resources

Every route sits under the base URL. Path parameters are UUIDs from earlier responses.

Webhooks

Register an endpoint under Admin, API and integrations and choose the events it receives. Every attempt is listed there with its status, so a missed event has an answer without a support ticket.

Events

• pedigree.completed
• eligibility.changed
• result.released
• recontact.created
• call.failed

Each delivery is a POST with a JSON body: event, created_at, and data describing the record.

Verifying a delivery

Each delivery carries an x-lumagen-signature header of the form t=<unix seconds>,v1=<hex>. Compute HMAC-SHA256 over "<t>.<raw body>" with the endpoint's signing secret, compare it to v1 in constant time, and reject a timestamp more than 300 seconds from now.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300;
  return fresh && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}
// header: request.headers["x-lumagen-signature"]

A delivery that fails is retried 5 times with increasing delays, then marked failed. Answer with any 2xx status within ten seconds.

FHIR

POST /fhir accepts a Bundle of Patient, Appointment and DiagnosticReport resources. Lumagen maps them onto its own patient, appointment and result records and keeps nothing else; every field it did not store is named in the response as an issue with code ignored-field, and the drop is recorded. A Patient identifier of type MR becomes the record number, and an Appointment participant referencing that patient books the appointment on the case.

Needs patients:write and appointments:write.