Provider directory CSV import API
provider_directory_v1
Import this template via API. Import a provider directory CSV with NPI Luhn validation and GLN check-digit. Emits FHIR Practitioner.
30-second curl
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"
At a glance
- Pack
- Healthcare
- FHIR resource
- Practitioner
- Risk level
- low
- Fields
- 6 (2 required, 2 validated)
Why this template?
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 (SNOMED CT, 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 a snomed_code validator if your downstream is FHIR-strict.
Migration scenarios & common foreign headers
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.
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 | — | — |
| last_name | string | yes | — | — |
| npi | string | — | npi | npi |
| gln | string | — | gln | gln |
| license_state | string | — | — | kanton · canton · state |
| specialty | string | — | — | fachrichtung · spécialité · specialità · especialidad |
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=provider_directory_v1" \ -F "file=@your_data.csv"
The canonical template definition is read-only at GET /v1/templates/provider_directory_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: "provider_directory_v1",
headers: ["first_name", "last_name", "npi", "gln"]
})MCP install instructions →FAQ — Provider directory CSV import
Can I require both NPI and GLN?
Fork the template and toggle `required: true` on either field. The canonical shape leaves both optional because most providers carry exactly one of the two.
How do I model multi-state licensure?
license_state is a single string in the canonical row. Multi-state licensure (interstate compact, multiple state-by-state licenses) needs a separate qualifications table — fork and link.
Does the NPI validator hit the registry?
No, only the checksum is verified locally. Registry lookups (deactivation, taxonomy) are a separate concern and belong in an enrichment step.
What about advanced-practice clinicians and non-physician providers?
They land in the same row — Practitioner is the FHIR resource for any qualified provider, not just physicians. Use the specialty field to disambiguate (NP, PA, CRNA, RN).