From 36adb614855515c5e6d7b7a75ff014aa96898a24 Mon Sep 17 00:00:00 2001 From: Mikhail Kulakov Date: Mon, 9 Nov 2026 13:24:03 +0000 Subject: [PATCH 1/3] Provider Directory: add the plan's provider number to providers and facilities Adds optional payer_provider_id and payer_provider_id_system columns to the providers and facilities datasets. The number goes on PractitionerRole (providers) and Organization (facilities) as a second identifier next to the NPI, with type PRN from v2-0203. Facilities that share an NPI but carry different plan numbers become separate rows. Co-Authored-By: Claude Opus 5.5 --- docs/data-integration/provider-directory/README.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/data-integration/provider-directory/README.md b/docs/data-integration/provider-directory/README.md index 349da2c..bb12b7d 100644 --- a/docs/data-integration/provider-directory/README.md +++ b/docs/data-integration/provider-directory/README.md @@ -30,11 +30,13 @@ Built to [Plan-Net STU 1.2.0](https://hl7.org/fhir/us/davinci-pdex-plan-net/STU1 ## providers -One row per unique NPI, practice location, plan and specialty. A provider at two locations in two plans produces several rows. +One row per unique NPI, plan provider number (when sent), practice location, plan and specialty. A provider at two locations in two plans produces several rows. | Column | Required | Format / values | Example | |---|---|---|---| | `npi` | Yes | 10 digits, Luhn-valid over the `80840` prefix | `9999999995` | +| `payer_provider_id` | If available | the plan's own number for this provider at this location, as used on claims and with utilization-management vendors | `100234` | +| `payer_provider_id_system` | If `payer_provider_id` is sent | URI of the plan's provider numbering, a URL the plan controls or an OID; the same value on every row | `http://acme.org/provider-ids` | | `first_name` | Yes | text | `Jane` | | `last_name` | Yes | text | `Smith` | | `middle_name` | No | text | `G` | @@ -63,14 +65,17 @@ One row per unique NPI, practice location, plan and specialty. A provider at two | `hours_of_operation` | If available | `day open-close`, `;`-separated | `mon 09:00-17:00;tue 09:00-17:00` | - `latitude` and `longitude` are one value in FHIR: send both or neither. A Location cannot carry half a position. +- `payer_provider_id` goes on the PractitionerRole as a second identifier, next to the NPI on the Practitioner, with `payer_provider_id_system` as its system and type `PRN` (Provider number) from [v2-0203](https://terminology.hl7.org/CodeSystem-v2-0203.html). Send it when systems that use the directory, such as a utilization-management vendor, identify providers by the plan's number rather than by NPI: one NPI can cover several provider records. The directory is public, so the number is visible in it. ## facilities -One row per facility NPI, plan and network. +One row per facility NPI, plan provider number (when sent), plan and network. Facilities that share an NPI but carry different plan provider numbers are separate facilities: send a row for each. | Column | Required | Format / values | Example | |---|---|---|---| | `npi` | Yes | 10 digits, Luhn-valid over the `80840` prefix | `9999999995` | +| `payer_provider_id` | If available | the plan's own number for this facility, as used on claims and with utilization-management vendors | `200871` | +| `payer_provider_id_system` | If `payer_provider_id` is sent | URI of the plan's provider numbering, the same value as in `providers` | `http://acme.org/provider-ids` | | `facility_name` | Yes | text | `Example Hospital` | | `facility_type_nucc` | Yes | NUCC organization taxonomy code(s), `;`-separated [IndividualAndGroupSpecialtiesVS](https://hl7.org/fhir/us/davinci-pdex-plan-net/STU1.2/ValueSet-IndividualAndGroupSpecialtiesVS.html) | `282N00000X` | | `affiliation_type` | Recommended | `group` medical group, `hospital`, `outpatient` clinic, `pharmacy`, `laboratory`, `dme`, `urgent` urgent care, `hospice` [OrganizationAffiliationRoleVS](https://hl7.org/fhir/us/davinci-pdex-plan-net/STU1.2/ValueSet-OrganizationAffiliationRoleVS.html) | `group` | @@ -88,6 +93,8 @@ One row per facility NPI, plan and network. | `longitude` | If available | decimal, WGS84 | `-73.9100` | | `phone` | Yes | 10 digits | `7185551212` | +- `payer_provider_id` goes on the Organization as a second identifier, next to the NPI, with the same system and type as in `providers`. Several hospitals of one health system can share an NPI; with the plan's number each hospital becomes its own Organization and Location, and each keeps the shared NPI. + ## networks The authoritative list of networks, so `network_id` stays consistent across datasets. One row per network. From e1df53bd8ea48acaa6783b3f2aa17f2f92a2176b Mon Sep 17 00:00:00 2001 From: Mikhail Kulakov Date: Mon, 9 Nov 2026 13:31:27 +0000 Subject: [PATCH 2/3] Provider Directory: one plan provider number per row State that a plan sends one number per row and, when it numbers providers in more than one way, gives each numbering its own system URI. Co-Authored-By: Claude Opus 5.5 --- docs/data-integration/provider-directory/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/data-integration/provider-directory/README.md b/docs/data-integration/provider-directory/README.md index bb12b7d..73e9dea 100644 --- a/docs/data-integration/provider-directory/README.md +++ b/docs/data-integration/provider-directory/README.md @@ -66,6 +66,7 @@ One row per unique NPI, plan provider number (when sent), practice location, pla - `latitude` and `longitude` are one value in FHIR: send both or neither. A Location cannot carry half a position. - `payer_provider_id` goes on the PractitionerRole as a second identifier, next to the NPI on the Practitioner, with `payer_provider_id_system` as its system and type `PRN` (Provider number) from [v2-0203](https://terminology.hl7.org/CodeSystem-v2-0203.html). Send it when systems that use the directory, such as a utilization-management vendor, identify providers by the plan's number rather than by NPI: one NPI can cover several provider records. The directory is public, so the number is visible in it. +- One number per row. If you number providers in more than one way, for example per provider and per site, send one of them here, under a `payer_provider_id_system` that names that numbering and no other. ## facilities @@ -94,6 +95,7 @@ One row per facility NPI, plan provider number (when sent), plan and network. Fa | `phone` | Yes | 10 digits | `7185551212` | - `payer_provider_id` goes on the Organization as a second identifier, next to the NPI, with the same system and type as in `providers`. Several hospitals of one health system can share an NPI; with the plan's number each hospital becomes its own Organization and Location, and each keeps the shared NPI. +- One number per row, as in `providers`. ## networks From 9a07c566c46a0de7243ff72eed0513250da3d2ce Mon Sep 17 00:00:00 2001 From: Mikhail Kulakov Date: Mon, 9 Nov 2026 13:33:00 +0000 Subject: [PATCH 3/3] Provider Directory: define payer_provider_id without listing its uses Co-Authored-By: Claude Opus 5.5 --- docs/data-integration/provider-directory/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/data-integration/provider-directory/README.md b/docs/data-integration/provider-directory/README.md index 73e9dea..d338778 100644 --- a/docs/data-integration/provider-directory/README.md +++ b/docs/data-integration/provider-directory/README.md @@ -35,7 +35,7 @@ One row per unique NPI, plan provider number (when sent), practice location, pla | Column | Required | Format / values | Example | |---|---|---|---| | `npi` | Yes | 10 digits, Luhn-valid over the `80840` prefix | `9999999995` | -| `payer_provider_id` | If available | the plan's own number for this provider at this location, as used on claims and with utilization-management vendors | `100234` | +| `payer_provider_id` | If available | the plan's own number for this provider at this location | `100234` | | `payer_provider_id_system` | If `payer_provider_id` is sent | URI of the plan's provider numbering, a URL the plan controls or an OID; the same value on every row | `http://acme.org/provider-ids` | | `first_name` | Yes | text | `Jane` | | `last_name` | Yes | text | `Smith` | @@ -75,7 +75,7 @@ One row per facility NPI, plan provider number (when sent), plan and network. Fa | Column | Required | Format / values | Example | |---|---|---|---| | `npi` | Yes | 10 digits, Luhn-valid over the `80840` prefix | `9999999995` | -| `payer_provider_id` | If available | the plan's own number for this facility, as used on claims and with utilization-management vendors | `200871` | +| `payer_provider_id` | If available | the plan's own number for this facility | `200871` | | `payer_provider_id_system` | If `payer_provider_id` is sent | URI of the plan's provider numbering, the same value as in `providers` | `http://acme.org/provider-ids` | | `facility_name` | Yes | text | `Example Hospital` | | `facility_type_nucc` | Yes | NUCC organization taxonomy code(s), `;`-separated [IndividualAndGroupSpecialtiesVS](https://hl7.org/fhir/us/davinci-pdex-plan-net/STU1.2/ValueSet-IndividualAndGroupSpecialtiesVS.html) | `282N00000X` |