Lab results CSV import API
lab_results_v1
Import this template via API. Import patient-linked lab results from CSV. LOINC-validated, emits FHIR Observation. Schema-only mode free.
30-second curl
curl -X POST https://api.adaptivmapr.com/v1/uploads \ -H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \ -F "template=lab_results_v1" \ -F "file=@your_data.csv"
At a glance
- Pack
- Healthcare
- FHIR resource
- Observation
- Risk level
- medium
- Fields
- 5 (4 required, 1 validated)
Why this template?
The Lab results template is the patient-linked counterpart to lab_result_catalog_v1 — each row is one observation for one patient at one point in time. patient_id links back to the demographics row, loinc_code identifies the test (and runs through the resolver fallback if free-text), value is the numeric result, unit is the human-readable unit, and taken_at is the sample collection timestamp. The template is `medium` risk because the row carries PHI (a result tied to a patient on a date is identifying), so full-data mode requires the phi-cloud bundle. Each row emits a FHIR Observation resource — code goes into Observation.code, value goes into Observation.valueQuantity.value, unit goes into Observation.valueQuantity.unit, and effectiveDateTime is taken_at. The cascade picks up "valeur", "valor", "wert" without escalation.
value is required and number-typed; results that come in as strings ("positive", "negative") need either a separate field or a custom enum — the canonical template is quantitative. Reference ranges live on the catalog row, not here, so downstream interpretation joins on loinc_code.
Migration scenarios & common foreign headers
Migration scenarios for Lab results: backfilling a brand-new EMR with historical lab results from a reference-lab archive, building a population-health dashboard that needs years of HbA1c trajectories, feeding a clinical-trial registry with longitudinal lab data for enrolled patients, and migrating between LIS vendors at hospital-system level. Foreign headers seen routinely: "Patient ID / Patientennr / PID / LOINC / Code LOINC / Wert / Valeur / Valor / Valore / Einheit / Unité / Unidad / Unità / Entnahme / Prélèvement / Toma / Prelievo / Datum". Because lab results are PHI under HIPAA, GDPR, and nFADP, the schema-only mode is the default ingress and the cascade has been tuned so the headers alone are enough to make a confident mapping decision without seeing row content.
Schema
The canonical column set, with the type each row carries, whether it is required, the field-level validators that fire on commit, and the multilingual header hints the cascade resolves against.
| Column | Type | Required | Validators | Hints |
|---|---|---|---|---|
| patient_id | string | yes | — | patient · patient_id · pid |
| loinc_code | string | yes | loinc_code | loinc |
| value | number | yes | — | wert · valeur · valor |
| unit | string | — | — | einheit · unité · unidad |
| taken_at | date | yes | — | entnahme · prélèvement · fecha |
How AdaptivMapr maps your headers to this template
Five layers run in order, cheapest first. Layer 1 (Statistics) auto-accepts headers that have been mapped the same way across past uploads. Layer 2 (Heuristic) compares your header to the column name, the optional label, and every registered hint (DE / FR / IT / EN / ES) after a Unicode-and-punctuation-normalising pass. Layer 3 (Fuzzy) catches typos and reordered words. Layer 4 (Semantic) uses cached embeddings to catch the long tail of paraphrases. Layer 5 (LLM) only fires on genuinely ambiguous columns, constrained to the template’s allowed column set so it cannot invent a field. When a layer auto-accepts, the lower-cost layers below it never run — that is the cost lever.
REST · POST /v1/uploads
Pass the template_id; the cascade picks up the rest.
curl -X POST https://api.adaptivmapr.com/v1/uploads \ -H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \ -F "template=lab_results_v1" \ -F "file=@your_data.csv"
The canonical template definition is read-only at GET /v1/templates/lab_results_v1.
MCP · Cursor / Claude Desktop
Drop AdaptivMapr into your IDE. Schema-only calls are free and unlimited.
// In Cursor or Claude Desktop with the AdaptivMapr MCP server installed:
adaptivmapr.match_headers({
template: "lab_results_v1",
headers: ["patient_id", "loinc_code", "value", "unit"]
})MCP install instructions →FAQ — Lab results CSV import
How do I model qualitative results (positive / negative)?
Fork the template and replace value (number) with an enum field. The canonical row is quantitative because most lab volume is quantitative — qualitative is a separate template.
Can taken_at carry a timezone?
Yes — ISO-8601 with offset parses cleanly. The validator does not enforce a timezone; pick one per workspace and normalise upstream if mixed.
What about result interpretation flags (H/L)?
Add an `interpretation` field via a fork. The canonical row is bare quantity; clinical interpretation belongs alongside or downstream.
Does AdaptivMapr block PHI from leaving the customer?
In schema-only mode, yes — only headers and three clamped sample rows (≤80 chars each) leave the customer. Full-data mode requires the phi-cloud bundle; the layer-5 LLM call goes to a PHI-eligible provider in your region.