Exposing FHIR to Third-Party Applications
The client is a large payer organization maintaining a mature Provider Data Management (PDM) system which tracks provider demographics, credentials, contracting status, network participation (in-network/out-of-network), and location affiliations.
While the internal PDM is robust and domain-authoritative, there was no standard FHIR-based interface exposed for third‐party applications to query provider network status reliably and dynamically.
The Challenge.
The client wanted to enable partner applications (third-party apps) to query: “Is this provider in this network for this plan?” or “List all in-network providers for plan X in region Y.” They needed the solution to:
- Use standardized FHIR PDM: Use a standardized FHIR provider directory model (not bespoke internal APIs).
- Support search and export: Support both search (query by practitioner, organization, location) and export/roster of providers.
- Utilize Argonaut PD IG: To utilize Argonaut PD IG which is designed for provider directory use-cases
- Leverage existing PDM: Leverage but not replace their existing PDM system.
- Publish capability statement: Publish a clearly defined Capability Statement so that external apps know exactly which resources/searches are supported.
- Network participation: The client’s main added dimension was: network participation (in-network/out-of-network) in addition to directory search.
Solution.
FHIR Facade Implementation Using Argonaut PD
We built a FHIR facade layer on top of the existing PDM system, implementing the provider directory search pattern derived from Argonaut PD IG, and extending it to network status exposure.
Architecture and Data Mapping.
- API Layer: A facade API layer connects via read-access to the PDM database and transforms data into FHIR R4-style resources (we adopted R4 to keep current, mapping from Argonaut STU3).
- Search Endpoints: Search endpoints implemented as per Argonaut PD: e.g., search by practitioner name, location city/state, specialty, organization affiliation.
- Search Filters: Additional search filters added to support network status.
Example: PractitionerRole?organization=ORG_ID&networkStatus=in-network&location.state=MI.
Key FHIR Resource Modelling
- Practitioner: Representing individual providers, identified by NPI or internal identifier.
- PractitionerRole: Representing the provider’s role in an organization + their network participation status (in-network/out-of-network).
- Organization: Provider group, hospital, facility network entity.
- Location: Practice/site location (for geo/regional search).
- Organization: or custom extension – network or plan participation metadata (we added extensions or used standard fields to indicate network status).
Roster/Bulk Export Capability.
Bulk Export Endpoint
We implemented a bulk export endpoint (or equivalent large-query capability) so that partner applications can download full rosters of in-network providers for a given plan/network and region.
PD Cache Refresh
We leveraged the facade to support both incremental updates (delta) and full snapshots, enabling apps to refresh their provider directory caches.
Capability Statement and Discovery.
Exposed Metadata
We exposed a /metadata endpoint returning a CapabilityStatement resource that describes:
- Supported resources: (Practitioner, PractitionerRole, Organization, Location);
- Supported operations: (search‐type, read, bulk export);
- Search parameters supported: (including networkStatus, organization, location.state, specialty, identifier);
- Authentication/access model (open read-only);
- Formats (application/fhir+json).
This allows apps to programmatically discover what the API supports, consistent with Argonaut PD guidance and good FHIR practice.
Security and Access Model.
Open API
Because the data exposed is provider directory + network status (non-PHI, publicly available network participation), we implemented an open read-only API (no OAuth required), with HTTPS for transport security and rate limiting.
Audit Logs
Audit logs maintained for usage tracking and abuse protection.
Implementation Phasing.
Phase I
Core directory search – implement Practitioner, Organization, Location, PractitionerRole search.
Phase II
Add network participation filter and network status attribute (in-network/out-of-network) & Bulk export / roster capability.
Phase III
Monitor and optimize caching & search performance
Benefits.
- Standards Based FHIR: The client now offers a standards-based FHIR endpoint for provider directory + network participation, aligned with Argonaut PD IG patterns.
- In-network Query: Third-party apps can query in-network status in real time, e.g., “Is this provider in-network for this plan?” or “List all in-network providers in Illinois for this network.”
- Minimal Risk: Internal PDM system remained unchanged; the facade did not disrupt credentialing workflows - minimal operational risk.
- Clear Capability Statement: The published CapabilityStatement provided clarity to partner app developers on search parameters and supported resources, accelerating onboarding.
- Reduced Friction: The open read-only model reduced friction for app integration while still providing secure, high-availability access.
- Future Ready Architecture: As business needs evolve (e.g., exposing provider quality or claims/encounter data), this facade can be extended to other IGs (such as roster export or clinical data) without redesigning core systems.
Conclusion.
We delivered a robust, FHIR-compliant provider directory façade based on the Argonaut PD Implementation Guide, extended to support in-network vs out-of-network queries.
This solution:
- Enables partner applications to dynamically discover and query provider network status.
- Preserves the integrity and operation of the PDM system.
- Exposes a clearly documented API (via CapabilityStatement) consistent with FHIR best-practice.
- Is adaptable for future expansion.
