Labs

You hold the lab contract and the lab's API key. neolife relays the order and carries the result back to a clinician. That sentence is the entire commercial model, and it is not a preference — a margin on a diagnostic is prohibited outright in this category, so the code refuses to build the alternative. See billing & compliance for why.

Gated by labs_ordering (dark by default, revealed once the vendor BAA is on file). Result write-back into a connected chart adds labs_result_writeback on top of emr_integrations.

BYO, concretely#

Connecting a lab means three things and no more.

Your account. You sign with the lab, you agree the panel prices, you get the client id. neolife never appears in that agreement.

Your key, held by reference. The connection stores a credentialsRef pointing at the secret manager. The key value is never a column on the connection row and is never returned by any endpoint.

Your invoice. The lab bills you directly for every panel, at your negotiated rate. neolife's platform fee is flat and does not move when you order more diagnostics — nothing on a lab order is metered. There is no usage event written on this path at all, which is a stronger statement than a zero-rated one: there is no counter to later switch on.

The four collection modalities#

A lab order isn't finished when it's placed — a sample has to come out of a patient. Four ways, and the modality is chosen per order because it changes the patient experience, the turnaround, and what has to be printed.

Modality	How the sample is taken	What neolife produces
Patient service center	The patient walks into the lab's own draw site	Requisition PDF + the booked appointment
At-home phlebotomy	A mobile phlebotomist visits the patient	Requisition + the scheduled visit window
Self-collection kit	A kit ships to the patient, who collects and returns it	Kit shipment + return tracking
In-clinic draw	Your own staff draw and the lab collects or the patient ships	Requisition + specimen labels

Every modality produces a requisition — the document that authorizes the lab to run the panel — plus specimen labels where the sample is handled outside the lab's own site, and an ABN where one is required. Those are generated as PDFs; they are not something you assemble from the API response.

The patient-facing half is a first-class surface, not an afterthought: patient.labs.view lets a patient see what was ordered and where it stands, patient.labs.schedule lets them book or rebook their own draw. A patient who can move their own appointment is a phone call your staff doesn't take.

The result lifecycle#

An order walks a fixed set of states. Several of them exist specifically so that a stalled order is visibly stalled rather than silently absent.

Status	Meaning
requisition_ready	Ordered. The requisition exists; nothing has been collected
scheduled	A draw appointment or a kit shipment is booked
collected	The sample is out of the patient
in_transit	The specimen is on its way to the lab
at_lab	Accessioned. The lab has it and is running it
partial_results	Some analytes have resulted; the panel is incomplete
resulted	The lab has returned a complete result
reviewed	A licensed clinician has reviewed and released it
critical	The lab flagged a critical value — escalated immediately
collection_failed	The draw failed, the kit wasn't returned, or the specimen was rejected

collection_failed is the state most lab integrations omit and most clinics need. A patient who never went to the draw site and a patient whose specimen haemolysed both look identical from the outside — "no result" — and both need a human. Naming the state is what puts them in a queue.

partial_results matters for the same reason: a panel where one analyte is still running is not the same as a panel that came back, and treating it as complete is how a clinician reads a result that isn't finished.

The release gate#

resulted is not reviewed. A result returned by the lab is not visible to the patient until a licensed clinician holding labs.result.review has reviewed and released it.

That permission sits in the clinical set, alongside order approval and intake review — it is licensure, not seniority, so an admin cannot hold it and there is no configuration that grants it to one. labs.order is gated the same way on the way in: ordering a diagnostic is a clinical act.

A critical flag from the lab escalates immediately rather than waiting in the review queue. A critical value that sits behind a release gate until someone happens to open the console is the failure mode the gate is supposed to prevent, so it routes as an exception the moment it lands.

Rule: neolife never interprets a result, never derives a verdict from one, and never releases one to a patient on its own. The rail carries the result to a clinician and stops.

Results into the chart#

With labs_result_writeback on, a reviewed result summary is written back into the connected EMR — a Task or non-visit note on a proprietary chart, a DiagnosticReport or Communication on FHIR.

This flag is triple-gated: it needs labs_ordering, emr_integrations, and itself. It's the one path on the platform where lab PHI crosses into a third-party system, so it gets its own switch rather than riding either parent — turning on lab ordering must not, as a side effect, start pushing results into a chart.

Where the chart can't accept the write, neolife holds the result and notifies the provider in-app. The same degrade as order write-back, for the same reason.

What neolife charges#

Nothing. Not a per-order fee, not a per-panel fee, not a percentage, not a rebate from the lab. Your flat platform fee is the same whether you order one panel a month or a thousand.

If that seems like money left on the table, read the next page — it isn't a pricing choice.

Next steps#

• Billing & compliance — the statute behind the BYO-only posture.
• Connection health — triaging a lab connection that stopped responding.
• Provider networks — who signs a lab order when your own prescriber isn't licensed in the patient's state.