The Opala Provider Directory API

The CMS Interoperability and Patient Access final rule requires MA organizations, Medicaid FFS programs, CHIP FFS programs, Medicaid managed care plans, and CHIP managed care entities to make provider directory information publicly available via a FHIR-based Provider Directory API.

Provider directories play a key role in enabling the identification of individual providers and provider organizations within a network. The Provider Directory API enables a member to use a third-party application to access information about in-network providers and provider organizations. The Provider Directory API is an open-access API and does not require authentication to access the data.

Opala's Provider Directory API supports the Da Vinci PDEX Plan-Net standard for search and retrieval, based on FHIR R4. The provider directory uses a push service to send new records and updates to the FHIR Repository. This documentation assumes that the developer is familiar with the Da Vinci PDEX implementation guide for a provider directory.

Use this URL to request data from Opala's Provider Directory API:

https://api.opalahealth.io:45000/pdir/premera/v1/fhir/r4

Use this URL to access Opala's Provider Directory API public metadata:

https://api.opalahealth.io:45000/pdir/premera/v1/fhir/r4/metadata

Plan-Net

The PDEX Payer Network (a.k.a., Plan-Net) Implementation Guide is, conceptually, based on the Validated Healthcare Directory Implementation Guide (VHDir IG), an international standard, which in turn is based on FHIR Version 4.0. The primary changes made by Plan-Net are:

• Removal of the validation and restriction resources
• Use of US Core for R4 as the base suite of profiles (where possible)
• Elimination of extensions that are unnecessary for this use case
• Introduction of additional constraints (e.g., search criteria, cardinality, value-set bindings, and MustSupport) where appropriate.

Note: Alignment with VhDir is maintained by adapting VhDir content where possible.

The Plan-Net IG was written for a US audience, and describes resources from US Core STU 3.1 where available (Practitioner, Organization, Location), and from R4 (OrganizationAffiliation, PractitionerRole, HealthCareService, Endpoint) otherwise.

The Network profile is based on USCore Organization, since there is no contradiction between the USCore profile and the Plan-Net requirements; however, the NPI and CLIA identifier types, which are Must-Support, are intended for provider organizations only and are not expected to be populated for other organization types.

Note: The PractitionerRole profile from US Core was not used because it is overly constrained for use in a Provider Directory based on Payer information.

Use Cases

The Provider Directory enables you to find a practitioner or organization. This section describes the use cases and search expectations for the Provider Directory.

• Search for a practitioner by demographics (e.g., name, specialty).
• Search for a practitioner or specialty within a region (e.g., city, state, distance from location). Or search for every practitioner with a specific specialty within a region.
• Search for an organization and facility.
• Search for a practitioner by organizational relationship (e.g., a practitioner in a specific health organization, a practitioner in a specific clinic)

Note: When searching for a practitioner by region using a postal code, Opala recommends you do not use the zip+4 format. Including the +4 suffix limits the results to a very specific area and is much less useful for finding a practioner within a postal code area.

Searches

The _include and _revinclude Parameters

The _include and _revinclude parameters request that search results include additional resources related to the resources directly matching the query (i.e., the primary results). Use these parameters to retrieve additional resources with a single request rather than making a series of requests for the resources separately.

• Forward inclusion using the _include parameter adds resources and resource versions referenced by the primary results.
• Reverse inclusion with the _revinclude parameter adds resources that reference the primary results.

The Opala Provider Directory supports the _include and _revinclude parameters using the following syntax:

GET {{base_Url}}/[resourceType]?[optional parameters]&[_include|_revinclude]=[parameters]

For example,

GET https://api.opalahealth.io:45000/pdir/premera/v1/fhir/r4/Location?address-postalcode=98008&_revInclude=PractitionerRole:location

Provider Resources

There are two methods for querying Provider-type FHIR Resources.

1. You can query any Practitioner that is a Da Vinci Plan-Net provider and view any PractitionerRoles assigned to it.
2. You can query the PractitionerRole directly and view any PractitionerRole resources that are returned.

Additional Resources

• PDEX Payer Network Implementation Guide (1.1)
• DaVinci PDEX Plan Net Artifacts Summary (6.0)