Patient demographics CSV import API
patient_demographics_v1
Import this template via API. Import patient demographics from CSV directly into FHIR Patient resources. AHV-validated, multilingual, schema-only mode.
30-second curl
curl -X POST https://api.adaptivmapr.com/v1/uploads \ -H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \ -F "template=patient_demographics_v1" \ -F "file=@your_data.csv"
At a glance
- Pack
- Healthcare
- FHIR resource
- Patient
- Risk level
- medium
- Fields
- 7 (3 required, 4 validated)
Why it exists
Why this template?
The Patient demographics template is the FHIR-shaped backbone of any healthcare import. Each row lands as a FHIR Patient resource — names go into Patient.name, the date of birth into Patient.birthDate, gender into Patient.gender, the AHV number into Patient.identifier with the Swiss OID, and phone/email into Patient.telecom with the right system code. The template is marked `medium` risk because the row carries identifying information about a real person; an AdaptivMapr subscription unlocks full-data ingestion. Schema-only mode — headers plus three clamped sample rows — keeps raw records home. Customers use this template to backfill a brand-new EMR, to migrate between practice-management vendors, and to seed clinical-trial registries. The cascade is tuned heavily on this shape — multilingual date headers alone cover most of the long tail.
The date_of_birth field has the deepest hint coverage of any field in the catalogue: Geburtsdatum, GebDatum, date de naissance, data di nascita, fecha de nacimiento, DoB, birthday, birth date. The date_range validator rejects 1899-and-before and any future date. Gender is mapped to FHIR's administrative-gender value set; "M / Männlich / Homme" all land on `male`.
Migration scenarios & common foreign headers
Migration scenarios for Patient demographics: bootstrapping a brand-new EMR with a full patient panel on day one, swapping practice-management vendors mid-year and porting active patients with zero data loss, seeding clinical-trial registries from referring-physician CSV lists, and consolidating multi-clinic patient databases at group-practice acquisition. Foreign headers we routinely see: "Patientennr / Numéro patient / PID / Vorname / Prénom / Nombre / Nachname / Nom / Apellido / Geburtsdatum / Date de naissance / Fecha de nacimiento / Geschlecht / Sexe / Sexo / AHV / AVS / Telefon / Téléphone / Teléfono / E-Mail". Because demographics is the keystone of any FHIR-backed pipeline, the cascade has been tuned heaviest on this template — the hints are exhaustive for Swiss, French, German, Italian, and Spanish source files.
Canonical columns
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 |
|---|---|---|---|---|
| first_name | string | yes | — | vorname · prenom · prénom · given name · nombre |
| last_name | string | yes | — | nachname · nom · cognome · family name · apellido |
| date_of_birth | date | yes | date_range (min 1900-01-01, max today) | geburtsdatum · gebdatum · date de naissance · data di nascita · fecha de nacimiento · dob · birthday · birth date |
| gender | enum | — | — | geschlecht · sexe · sesso · sexo |
| ahv_number | string | — | regex (^756\.\d{4}\.\d{4}\.\d{2}$) | ahv · avs · nss · ssn |
| phone | phone | — | phone | telefon · téléphone · telefono · phone · mobile |
| — | email · e-mail · mail · correo |
The cascade
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=patient_demographics_v1" \ -F "file=@your_data.csv"
The canonical template definition is read-only at GET /v1/templates/patient_demographics_v1.
MCP · Cursor / Claude Desktop
Drop AdaptivMapr into your IDE. Schema-only calls need no key and draw only the small flat per-map fee.
// In Cursor or Claude Desktop with the AdaptivMapr MCP server installed:
adaptivmapr.match_headers({
template: "patient_demographics_v1",
headers: ["first_name", "last_name", "date_of_birth", "gender"]
})MCP install instructions →Questions
FAQ — Patient demographics CSV import
Does the template emit valid FHIR R4?
Yes. Each row, after mapping, produces a FHIR R4 Patient JSON with the AHV identifier carrying the urn:oid:2.16.756.5.32 system. We do not invent extension URIs.
How does AdaptivMapr handle PHI in schema-only mode?
In schema-only mode only headers and three clamped sample rows (≤80 chars each) leave the customer. The cascade picks up the mapping decision from header text alone — no full row ever touches our infrastructure unless you have an AdaptivMapr subscription.
Is the AHV regex configurable for non-CH patients?
Make the field optional via a workspace fork. For multi-country deployments, capture each identifier as a separate column and emit Patient.identifier slices downstream.
What about Swiss double-barrel names like "Müller-Schmid"?
Names are passed through untouched. The cascade matches headers, not row contents — Unicode (including ß and umlauts) round-trips cleanly.