Healthcare pack

Patient demographics CSV import API

Import patient demographics from CSV directly into FHIR Patient resources. AHV-validated, multilingual, schema-only mode.

Try in Workbench Quickstart

medium riskFHIR · Patientpatient_demographics_v1

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"

→ 7 canonical fields · 4 validated · medium risk

Canonical columns

The whole schema, printed as it ships.

Every canonical column, 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. This is the shipped definition, not a summary of it.

patient_demographics_v1FHIR · Patient

fields: 7
required: 3
validated: 4
hints: 35

Canonical column	Type	Required	Validators	Header hints the cascade matches
`first_name`	string	yes	—	vornameprenomprénomgiven namenombre
`last_name`	string	yes	—	nachnamenomcognomefamily nameapellido
`date_of_birth`	date	yes	`date_range`	geburtsdatumgebdatumdate de naissancedata di nascitafecha de nacimientodobbirthdaybirth date
`gender`	enummalefemaleotherunknown	—	—	geschlechtsexesessosexo
`ahv_number`	string	—	`regex`	ahvavsnssssn
`phone`	phone	—	`phone`	telefontéléphonetelefonophonemobile
`email`	email	—	`email`	emaile-mailmailcorreo

Read the same definition as JSON at GET /v1/templates/patient_demographics_v1. A hint match resolves on layer 2 — no LLM call, no token spend, just the flat per-map fee. Hover a validator id to see what it checks.

7 canonical fields
3 required
4 validated
35 header hints, 5 languages
FHIR Patient

Why it exists

Written for the file you actually receive.

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 & the foreign headers they ship

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.

The cascade

Five layers, and the cheapest one wins.

Layers run in order and stop the moment a column resolves. That is the single biggest cost lever in the system: a column caught on layer 2 never reaches the metered layer 5.

L1Statisticsno LLM
Auto-accepts a header that past confirmations already resolved the same way, at {minN:100, minRatio:0.95} or {minN:20, minRatio:1.00}.
L2Heuristicno LLM
Normalises accents, punctuation and whitespace, then compares against the column name, the label, and every registered hint (DE / FR / IT / EN / ES).
L3Fuzzyno LLM
Token-set ratio plus Levenshtein over the normalised strings. Auto-accepts at 0.80 — it absorbs typos and reordered words.
L4Semanticcheap, cached
Embedding cosine between the header and the field’s label + hints. Catches the long tail of paraphrases.
L5LLMmetered
Everything still unresolved goes up in ONE batched, collision-aware call, constrained to this template’s column set so it cannot invent a field.

Try it

One template id, two ways in.

REST for your import pipeline, MCP for your editor. Both run the same cascade and both honour the same schema-only clamp.

REST · POST /v1/uploads

Name the template; the cascade picks up the rest. The canonical definition is read-only at GET /v1/templates/patient_demographics_v1.

bash

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"

→ upload created · mappings ready · confirm before commit

MCP · Cursor / Claude Desktop

Drop AdaptivMapr into your editor and call the same cascade as a tool. Schema-only calls leave only column names and up to three clamped sample rows.

mcp

// In Cursor or Claude Desktop with the AdaptivMapr MCP server installed:
adaptivmapr.match_headers({
  template_id: "patient_demographics_v1",
  headers: ["first_name", "last_name", "date_of_birth", "gender"]
})

schema-only · headers and ≤3 rows, 80 chars each

MCP install instructions

medium-risk template

The mappings response comes back flagged. PATCH /uploads/:id/mappings returns requires_hitl: true and hitl_status: "pending_review" so you can hold the commit in your own workflow — the flag is a signal, not a queue we run. Schema-only mode (headers plus at most three sample rows, each clamped to 80 characters) is a data-minimization mode enforced at the HTTP edge. Full-data mode routes the metered layer-5 call to phi-cloud in-region under a BAA, costs 20% more on the whole map charge, and stays locked until the workspace accepts the BAA/NDA in Settings → Security & Data.

How the wallet is charged

Questions

Patient demographics CSV import — FAQ

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.

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.

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.

Names are passed through untouched. The cascade matches headers, not row contents — Unicode (including ß and umlauts) round-trips cleanly.

Ready when you are

Map patient demographics in production — without shipping raw records.

Schema-only mode leaves only headers and a handful of clamped samples. Add full-data when you need row-level AI, routed in-region under a BAA.

Get an API key More Healthcare templates →

No free tier · $10 prepaid wallet to start · every map draws a small flat fee, deterministic ones included