DaVinci PDEX Plan Net
1.2.0 - STU 2 (ci-build) United States of America flag

DaVinci PDEX Plan Net, published by HL7 International / Financial Management. This guide is not an authorized publication; it is the continuous build for version 1.2.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/davinci-pdex-plan-net/ and changes regularly. See the Directory of published versions


Page standards status: Informative

Implementation Notes

This page contains miscellaneous information on FHIR implementation. The content is primarily directed at implementers of Plan-Net.

Conformance Requirements

The conformance verbs (SHALL, SHALL NOT, SHOULD, MAY) used in this guide are defined in FHIR Conformance Rules.

Privacy Considerations

Access to the Plan-Net service should not require authentication, and the server should not maintain any records that could associate the consumer with the entities that were queried.

A conformant Plan-Net service SHALL NOT require a directory mobile application to send consumer identifying information in order to query content.

A directory mobile application SHALL NOT send consumer identifiable information when querying a Plan-Net service.

Must Support

When querying and reading the Plan-Net Profiles defined in this IG, Must Support on any profile data element SHALL be interpreted as follows:

Health Plan API Requirements
  • Health Plan API actors SHALL be capable of populating all Must Support data elements as part of the query results.
  • In situations where information on a particular Must Support data element is not present and the minimum cardinality is 0 , the Health Plan API actors SHALL NOT include the data elements in the resource instance returned as part of the query results.
  • In situations where information on a particular data element is not present and the minimum cardinality is >0 SHALL send the reason for the missing information using values (such as nullFlavors) from the value set where they exist or use the dataAbsentReason extension.
Application Requirements
  • Application actors SHALL be capable of processing resource instances containing the Must Support data elements without generating an error or causing the application to fail.
  • Application actors SHOULD be capable of displaying the data elements for human use or storing the information for other purposes.
  • When querying Health Plan API actors, Application actors SHALL interpret missing Must Support data elements within resource instances as data not present in the Health Plan API actors system.
  • Consumer App actors SHALL be able to process resource instances containing Must Support data elements asserting missing information.

Client Detection of Updates Directory Content

Each profile in this guide requires that the lastUpdate timestamp be provided as part of the profile's data content.  Clients that cache query results can track additions or modifications to directory content through queries that filter content using the _lastUpdated search parameter.  Clients should periodically check that data cached from past queries has not been deleted by querying for the same elements by _id.

General Security Considerations


Representing and Searching Provider Directory Data

It is important for payers to use the Plan-Net profiles consistently in order to achieve true interoperability of directory information among payers. The intent of this section is to provide examples of the canonical use of the profiles provided in this IG that will guide implementers towards the consistent use of these profiles that will enable 3rd party applications to search the data.  The Plan-Net design is based around the following types of searches.



Focal  Resource and Field

Qualifications of Search

General Search


HealthcareService.category, HealthcareService.specialty

Location, network

Provider by Name

Joe Smith


Location, network, specialty, role/privileges

Organization by Name

Montgomery Cardiology or CVS


Location, network, specialty

Provider by Specialty



Location, network, name

Organization by Specialty

Compounding Pharmacy


Location, network, name

The content in this section of the IG is based on the examples provided and on the patterns provided here.
Specific examples are referenced in the text below.

Searching for active Practictioners and Organizations

Sample query to search for currently active Practitioners (replace date in query with current date):

Sample query to search for currently active Organizations (replace date in query with current date):

To search for Practitioners or Organizations that will be active at a future time, change the date to a future date.

If no period is provided, then it is assumend the role is active with no expiration date.


The first type of search starts from HealthcareService.category and HealthcareService.specialty, so it is essential that each provider's service be supported by appropriate set of HealthcareService instances.  HealthcareServices are typically provided by an organization, except in the case of a Practitioner that is not associated with an organization (see the solo practitioner example), and can be linked to a set of locations where service is provided, or identified as virtual services through an indicated set of virtual modalities.   The examples illustrate this with an organization that provides three distinct Pharmacy services -- retail, compounding, and mail-order -- across its locations.  All organizations that provide service should define an appropriate set. of HealthcareServices to facilitate search.  The HealthcareService category, specialty and type fields are the highest level of organization of the services provided by the provider's network.

Relevant examples:

Scenario Example Instances
Retail Pharmacy Chain


Compounding Pharmacy PharmChainCompService
Mail Order Pharmacy (virtual service with no physical location) PharmChainMailService
Provider Group HartfordOrthopedicServices
Emergency Room HospERService
Cancer Clinic CancerClinicService
Virtual Counseling Service
 Solo Family Practitioner   HansSoloService

Insurance Plan and Network

Each payer will offer one or more products -- Insurance Plans -- and each plan is associated with one or more Networks.  Practitioners and Organizations indicate participation in a Network with a link to the Network using a PractitionerRole or OrganizationAffiliation instance, respectively.   PractitionerRole and OrganizationAffiliation instances are what tie Practitioners and Organizations to HealthcareServices, Organizations, Networks and Locations.

The examples demonstrate the use of the InsurancePlan profile to represent two distinct Qualified Health Plan products covering the state of Connecticut, using a pair of Networks.  The practitioners and organizations in the examples participate in one or both of these networks.

Relevant examples:

Scenario Example Instances
Insurance Company


QHP Gold Plan with two networks AcmeQHPGold
QHP Bronze plan with one network AcmeQHPBronze
Standard Network AcmeofCTStdNet
Premium Network AcmeofCTPremNet


Location instances provide information about location where service is provided, including contact information, address, accessibility, hours of operation and contact, as well as position (lattitude and longitude).   Locations can also be used to represent regions using an associated or attached GeoJSON object.

Relevant examples:

Scenario Example Instances
Hospital Location #1


Hospital Location #2 HospLoc2
Pharmacy Location #1 .  Shows newpatient,
accessibliity, and contactpoint-availabletime extensions
Pharmacy Location #2 PharmLoc2
Location used as CoverageArea StateOfCTLocation

Practitioners and PractitionerRoles

Practitioner instances provide information about a specific person, including name, gender, languages spoken, and qualifications.   PractitionerRole defines a role for a particular practitioner, and associates it with locations, specialties, an organization, and networks.

Scenario Example Instances
Solo Practitioner (no organization)


Anonymous role (not associated with a specific practitioner) AnonRole
Physician working at a provider group JoeSmith, JoeSmithRole2
Physician with admitting privileges JoeSmith, JoeSmithRole3
Physician working at a hospital JoeSmith, JoeSmithRole1
Counselor working virtually

Organizations and Organization Affiliations

Organization instances provide information about a specific organization and organizational hierarchies, including organization name, specialty, type, address and contact information.  Organization Affiliation instances describe a role, and link a participating organization that provides or performs the role, with an organization where that role is available, and also links the participating organization to a HealthcareServices and networks.  OrganizationalAffiliation can also be used to associate a HealthcareService provided by an organization with networks.

Scenario Example Instances
Pharmacy services are associated with a specific provider network


Clinic Providing Service to a Hospital BurrClinicBurrClinicAffil, Hospital
Clinic that is part of a Hospital HamiltonClinicHamiltonClinicAffil, Hospital
Specialty group providing service to a network at hospital HartfordOrthopedicsHartfordOrthopedicAffil, Hospital
Clinic that is a member of a regional HIE BurrClinicConnHIEConnHIEAffil


An Endpoint instance provides  technical details of an endpoint that can be used for electronic services, such as a portal or FHIR REST services, messaging or operations, or DIRECT messaging.

Scenario Example Instances
Payer Portal AcmeOfCTPortalEndpoint