Provider Directory API
Base URL:
This API is designed to follow the DaVinci PDEX Plan Net 1.1.0 - STU1 implementation guide (IG):
- Based on HL7 ®️ FHIR ©️ R4: https://www.hl7.org/fhir/
- Da Vinci PlanNet Implementation Guide: http://hl7.org/fhir/us/davinci-pdex-plan-net/STU1.1/
Per DaVinci PDEX Plan Net IG, please refer to the CapabilityStatement (/metadata) for currently available functionality:
Capability Statement
This section describes the expected capabilities of the Plan-Net Server actor which is responsible for providing responses to the queries submitted by the Plan-Net Requestors. This server uses the HTTP Protocol and is compatible with any software that can consume a REST API. The complete list of FHIR profiles, RESTful operations, and search parameters supported by Plan-Net Servers are defined. Systems implementing this capability statement should meet the CMS Final Rule requirement for provider directory access. Plan-Net Clients can use the required capabilities to access necessary data based on their local use cases and other contextual requirements.
HealthcareService
The Health Care Service resource typically describes services offered by an organization/practitioner at a location. The resource may be used to encompass a variety of services covering the entire healthcare spectrum, including promotion, prevention, diagnostics, pharmacy, hospital and ambulatory care, home care, long-term care, and other health-related and community services.
InsurancePlan
An Insurance Plan resource is a discrete package of health insurance coverage benefits that are offered under a particular network type. A given payer's products typically differ by network type and/or covered benefits. A plan pairs a product's covered benefits with the particular cost sharing structure offered to a consumer. A given product may comprise multiple plans (i.e. each plan offers different cost sharing requirements for the same set of covered benefits).
InsurancePlan describes a health insurance offering comprised of a list of covered benefits (i.e. the product), costs associated with those benefits (i.e. the plan), and additional information about the offering, such as who it is owned and administered by, a coverage area, contact information, etc.
Location
A Location is the physical place where healthcare services are provided, practitioners are employed, organizations are based, etc. Locations can range in scope from a room in a building to a geographic region/area.
Network
A Network refers to a healthcare provider insurance network. A healthcare provider insurance network is an aggregation of organizations and individuals that deliver a set of services across a geography through health insurance products/plans. A network is typically owned by a payer.
In the PlanNet IG, individuals and organizations are represented as participants in a Plan-Net Network through the practitionerRole and Plan-Net-organizationAffiliation resources, respectively.
Organization
An organization is a formal or informal grouping of people or organizations with a common purpose, such as a company, institution, corporation, community group, or healthcare practice. Guidance: When the contact is a department name, rather than a human (e.g., patient help line), include a blank family and given name, and provide the department name in contact.name.text
OrganizationAffiliation
The Organization Affiliation resource describes relationships between two or more organizations, including the services one organization provides another, the location(s) where they provide services, the availability of those services, electronic endpoints, and other relevant information.
Practitioner
Practitioner is a person who is directly or indirectly involved in the provisioning of healthcare.
PractitionerRole
Practioner Role describes details about a provider, which can be a practitioner or an organization. When the provider is a practitioner, there may be a relationship to an organization. A provider renders services to patients at a location. When the provider is a practitioner, there may also be a relationship to an organization. Practitioner participation in healthcare provider insurance networks may be direct or through their role at an organization.
Provider Directory API Response Codes
| HTTP Response/Exception Codes | Response/Exception Code Definition | Return Type |
|---|---|---|
| 200 | Success | Bundle or Resource |
| 400 | Invalid parameter | OperationOutcome/Error |
| 404 | Unknown resource | OperationOutcome/Error |
Capability Statement
Retrieve the CapabilityStatement
Syntax: GET [Base URL]/metadata
| Interaction | Definition | Parameter Type | Return Type |
|---|---|---|---|
| metadata | Capabilities interaction: Returns a CapabilityStatement describing the server's current operational functionality | N/A | CapabilityStatement |
Healthcare Service
Search for HealthcareService
Syntax: GET [Base URL]/HealthcareService?{[parameter=value]}
| Supported Searches | Search Parameter Definition | Parameter Type | Return Type |
|---|---|---|---|
| _id | Logical ID of the Resource (HealthcareService) | Token | Bundle |
| _lastUpdated | When the resource (HealthcareService) version last changed | Date/DateTime | Bundle |
| location | Select HealthcareServices available at the specified location | Reference | Bundle |
| coverage-area | Select HealthcareServices available at the specified location | Reference | Bundle |
| organization | Select HealthcareServices provided by the specified organization | Reference | Bundle |
| name | Select HealthcareServices with the specified name | String | Bundle |
| service-category | Select HealthcareServices with the specified category | Token | Bundle |
Insurance Plan
Search for InsurancePlan
Syntax: GET [Base URL]/InsurancePlan?{[parameter=value]}
| Supported Searches | Search Parameter Definition | Parameter Type | Return Type |
|---|---|---|---|
| _id | Logical ID of the Resource (InsurancePlan) | Token | Bundle |
| _lastUpdated | When the resource (InsurancePlan) version last changed | Date/DateTime | Bundle |
| administered-by | Select products that are administered by the specified organization | Reference | Bundle |
| owned-by | Select products that are owned by the specified organization | Reference | Bundle |
| name | Select products with the specified name | String | Bundle |
| plan-type | Select plans of the specified type | Token | Bundle |
| identifier | Select products with the specified identifier | Token | Bundle |
| type | Select insurance plans of the specified type | Token | Bundle |
Location
Search for Location
Syntax: GET [Base URL]/Location?{[parameter=value]}
| Supported Searches | Search Parameter Definition | Parameter Type | Return Type |
|---|---|---|---|
| _id | Logical ID of the Resource (Location) | Token | Bundle |
| _lastUpdated | When the resource (Location) version last changed | Date/DateTime | Bundle |
| organization | Select Locations managed by the specified organization | Reference | Bundle |
| address-city | Select Locations with the specified address.city | String | Bundle |
| address-state | Select Locations with the specified address.state | String | Bundle |
| address-postalcode | Select Locations with the specified address.postalCode | String | Bundle |
| address | Select Locations with the specified address | String | Bundle |
| type | Select Locations of the specified type | Token | Bundle |
Organization
Search for Organization
Syntax: GET [Base URL]/Organization?{[parameter=value]}
| Supported Searches | Search Parameter Definition | Parameter Type | Return Type |
|---|---|---|---|
| _id | Logical ID of the Resource (Organization) | Token | Bundle |
| _lastUpdated | When the resource (Organization) version last changed | Date/DateTime | Bundle |
| partof | Select Organizations that are part of the specified organization | Reference | Bundle |
| address | Select organizations with the specified address (matches any of the string elements of an address) | String | Bundle |
| name | Select Organizations with the specified name | String | Bundle |
| type | Select Organizations of the specified type | Token | Bundle |
Organization Affiliation
Search for OrganizationAffiliation
Syntax: GET [Base URL]/OrganizationAffiliation?{[parameter=value]}
| Supported Searches | Search Parameter Definition | Parameter Type | Return Type |
|---|---|---|---|
| _id | Logical ID of the Resource (OrganizationAffiliation) | Token | Bundle |
| _lastUpdated | When the resource (OrganizationAffiliation) version last changed | Date/DateTime | Bundle |
Practitioner
Search for Practitioner
Syntax: GET [Base URL]/Practitioner?{[parameter=value]}
| Supported Searches | Search Parameter Definition | Parameter Type | Return Type |
|---|---|---|---|
| _id | Logical ID of the Resource (Practitioner) | Token | Bundle |
| _lastUpdated | When the resource (Practitioner) version last changed | Date/DateTime | Bundle |
| name | Select Practitioners with the specified name (matches against any of the elements in the HumanName data type) | String | Bundle |
| family | Select Practitioners with the specified family name | String | Bundle |
| given | Select Practitioners with the specified given name | String | Bundle |
Practitioner Role
Search for PractitionerRole
Syntax: GET [Base URL]/PractitionerRole?{[parameter=value]}
| Supported Searches | Search Parameter Definition | Parameter Type | Return Type |
|---|---|---|---|
| _id | Logical ID of the Resource (PractitionerRole) | Token | Bundle |
| _lastUpdated | When the resource (PractitionerRole) version last changed | Date/DateTime | Bundle |
Disclaimer- This page complies with Behavioral Health Information Notice No: 23-032