Healthcare pack
Provider directory CSV import API
Import a provider directory CSV with NPI Luhn validation and GLN check-digit. Emits FHIR Practitioner.
curl -X POST https://api.adaptivmapr.com/v1/uploads \
-H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \
-F "template=provider_directory_v1" \
-F "file=@your_data.csv"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.
provider_directory_v1FHIR · Practitioner- fields
- 6
- required
- 2
- validated
- 2
- hints
- 9
| Canonical column | Type | Required | Validators | Header hints the cascade matches |
|---|---|---|---|---|
first_name | string | yes | — | matched on the column name |
last_name | string | yes | — | matched on the column name |
npi | string | — | npi | npi |
gln | string | — | gln | gln |
license_state | string | — | — | kantoncantonstate |
specialty | string | — | — | fachrichtungspécialitéspecialitàespecialidad |
Read the same definition as JSON at GET /v1/templates/provider_directory_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.
- 6 canonical fields
- 2 required
- 2 validated
- 9 header hints, 5 languages
- FHIR Practitioner
Why it exists
Written for the file you actually receive.
The Provider directory template is the schema for the practitioners who deliver care — physicians, advanced-practice clinicians, therapists, technicians. Each row emits a FHIR Practitioner resource with first_name and last_name in Practitioner.name, the NPI (US) and GLN (CH / EU) in Practitioner.identifier with the right system URI, the license state in Practitioner.qualification.code, and a free-text specialty in Practitioner.specialty. The NPI validator runs the canonical Luhn check against "80840" + the first 9 digits — the same algorithm CMS publishes. GLN runs the GS1 mod-10 checksum. The template is `low` risk because provider names are public information (NPI is a public registry). Customers use it when standing up a directory, building a referral network module, or migrating between credentialing systems.
specialty is intentionally a free-text string — the controlled vocabulary (NUCC taxonomy) varies per workspace and per use case, and pinning to one ontology in the canonical row breaks too many imports. Fork the template and add an icd10_code validator if your downstream is FHIR-strict.
Migration scenarios & the foreign headers they ship
Migration scenarios for the Provider directory: standing up a credentialing module from scratch, populating a referral network with regional providers, importing a state medical-board roster for license verification, and consolidating after an IDN merger where multiple provider databases need to reconcile. Foreign headers we see often: "Vorname / Prénom / Nombre / Nachname / Nom / Apellido / NPI / National Provider Identifier / GLN / License State / Kanton / Bundesland / Provincia / Fachrichtung / Spécialité / Specialità / Especialidad". The NPI Luhn check is the most-triggered validator in the catalogue — provider files arrive with at least one bad digit almost every time, and the algorithmic check catches it long before CMS does on the receiving end.
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/provider_directory_v1.
curl -X POST https://api.adaptivmapr.com/v1/uploads \
-H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \
-F "template=provider_directory_v1" \
-F "file=@your_data.csv"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.
// In Cursor or Claude Desktop with the AdaptivMapr MCP server installed:
adaptivmapr.match_headers({
template_id: "provider_directory_v1",
headers: ["first_name", "last_name", "npi", "gln"]
})Questions
Provider directory CSV import — FAQ
Ready when you are
Map provider directory 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.