Provider Directory API
Overview
The Provider Directory API accesses the HAP FHIR server Provider and Pharmacy Directories. You can create an application to access data about providers and pharmacies using read-only RESTful API GET calls (PUT and POST are not currently supported).
Below you will find the FHIR profiles, resources, and RESTful capabilities the HAP Provider Directory API supports. A profile is a set of rules which allows a resource to be constrained, or to include extensions, so the resource can add additional attributes. The RESTful capabilities are discussed in further detail below.
Conformance Language
This specification uses the conformance verbs SHALL, SHOULD, and MAY:
  • SHALL: An absolute requirement for all implementations. The FHIR server must return this data.
  • SHOULD: A best practice or recommendation for the implementation. The FHIR server is recommended to return this data.
  • MAY: An optional inclusion for the implementation; not a requirement. The FHIR server may return the data, but there is no requirement to do so.
Security
HAP’s Provider Directory FHIR server does not maintain any records that can be associated with a consumer. The Provider Directory API does not require third-party applications to send consumer identifying information and does not require authentication.
However, we do throttle access to the unauthenticated endpoint. If you wish to call this API more frequently than a few times a minute, you must register with us.
FHIR RESTful API Capabilities
HAP has implemented and supports RESTful behaviors according to the FHIR specification.
Returns the following http status codes:
HTTP Status Code Description
200Successful Request
400Invalid Parameter
401Not Authorized
403Insufficient Scope
404Unknown Resource
410Deleted Resource
Note: For more information please refer to the HL7® FHIR® RESTful API guides
RESTful Capability by Resource, with Alignment to Profiles
Read (Fetch) Syntax
To fetch resource interactions, use the following syntax:
GET [base]/[Resource-type]/[id] {parameters}
  • GET: the HTTP verb used to fetch the resource
  • Content surrounded by " " are mandatory for the client to supply, and will be replaced by the string literal identified.
    • base: The Service Root URL
    • Resource-type: The name of the resource type (e.g "Practitioner")
    • id: The logical ID for a resource (e.g. "24342")
  • Content surrounded by "{ }" is optional for the client to supply, and will be replaced by the string literal identified.
    • parameters: optional - definition for the particular interaction
Search Syntax
To search resource interactions, use the following syntax:
GET [base]/[Resource-type]?[parameter1]{:m1|m2|...}={c1|c2|...}[value1{,value2,...}]{&[parameter2]{:m1|m2|...}={c1|c2|...}[value1{,value2,...}]&....}
  • GET: the HTTP verb used to fetch the resource
  • Variables surrounded by " " are mandatory for the client to supply, and will be replaced by the string literal identified.
  • Variables surrounded by "{ }" are optional for the client to supply, and will be replaced by the string literal identified.
    • base: The Service Root URL
    • Resource-type: The name of a resource type (e.g "Practitioner")
    • parameter: The search parameters as defined for the particular interaction (e.g. "?patient=Patient/123")
    • value: the search parameter value for a particular search
      • Note: For values of type Token, the syntax {system|}[code] means that the system value is optional for the client to supply.
    • {:m1|m2|...}: The list of supported search parameter modifiers
    • {c1|c2|...}: The list of supported search parameter comparators
    • {,value2,...}: Optional multiple "OR" values
    • {¶meter2={:m1 m2 ...}={c1 c2 ...}[value1{,value2,...}&...}: Optional multiple "AND" search parameters
In the simplest case, a search is executed by performing a GET operation in the RESTful framework:
GET [base]/[Resource-type]?name=value&...
For this RESTful search, the parameters are a series of name=[value] pairs encoded in the URL. The search parameter names are defined for each resource. For example, the Observation resource the name "code" for search on the LOINC code.
Note: For more information about how the search resource interactions are handled, refer to the HL7® FHIR® Search topic.
Provider Directory Resources
Below you will find the resources and endpoints supported by the HAP Provider Directory API. The API supports the following FHIR approved implementation guide and profiles:
Implementation Guide
Supported Profiles
Base URL
Use the following base URLs to access the HAP Provider Directory API:
InsurancePlan
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.
The DaVinci PDEX Plan-Net InsurancePlan profile is based on the core FHIR InsurancePlan resource.
Fetch and Search Criteria:
  • The HAP FHIR server SHALL be capable of returning a InsurancePlan resource using:
    GET [base]/InsurancePlan/[id]
  • The HAP FHIR server SHOULD be capable of returning a InsurancePlan resource using:
    GET [base]/InsurancePlan/[id]/_history/vid
  • The HAP FHIR server SHALL be capable of supporting the following _includes:
    GET [base]/InsurancePlan?[parameter=value]&_include=InsurancePlan:administered-by
    GET [base]/InsurancePlan?[parameter=value]&_include=InsurancePlan:owned-by
    GET [base]/InsurancePlan?[parameter=value]&_include=InsurancePlan:coverage-area
Search Parameters:
Conformance Parameter Type Example
SHALLaadministered-byreferenceGET [base]/InsurancePlan?administered-by=[administered-by]
SHALLowned-byreferenceGET [base]/InsurancePlan?owned-by=[owned-by]
SHALLcoverage-areareferenceGET [base]/InsurancePlan?coverage-area=[coverage-area]
SHALLnamestringGET [base]/InsurancePlan?name=[name]
SHALLplan-typetokenGET [base]/InsurancePlan?plan-type=[system]|[code]
SHALLidentifiertokenGET [base]/InsurancePlan?identifier=[system]|[code]
SHALL_idtokenGET [base]/InsurancePlan?_id=[id]
SHALL_lastUpdateddateGET [base]/InsurancePlan?_lastUpdated=[_lastUpdated]
SHALLtypetokenGET [base]/InsurancePlan?type=[system]|[code]
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.
The DaVinci PDEX Plan-Net Location profile is based on the core FHIR US Core Location resource.
Fetch and Search Criteria:
  • The HAP FHIR server SHALL be capable of returning a Location resource using:
    GET [base]/Location/[id]
  • The HAP FHIR server SHOULD be capable of returning a Location resource using:
    GET [base]/Location/[id]/_history/vid
  • The HAP FHIR server SHALL be capable of supporting the following _includes:
    GET [base]/Location?[parameter=value]&_include=Location:organization
    GET [base]/Location?[parameter=value]&_include=Location:partof
  • The HAP FHIR server SHALL be capable of supporting the following _revincludes:
    GET [base]/Location?[parameter=value]&_revinclude=HealthcareService:location
    GET [base]/Location?[parameter=value]&_revinclude=InsurancePlan:coverage-area
    GET [base]/Location?[parameter=value]&_revinclude=OrganizationAffiliation:location
    GET [base]/Location?[parameter=value]&_revinclude=PractitionerRole:location
Extensions:
Search Parameters:
Conformance Parameter Type Example
SHALLpartofreferenceGET [base]/Location?partof=[partof]
SHALLorganizationreferenceGET [base]/Location?organization=[organization]
SHALLaddress-citystringGET [base]/Location?address-city=[address-city]
SHALLaddress-statestringGET [base]/Location?address-state=[address-state]
SHALLaddress-postalcodestringGET [base]/Location?address-postalcode=[address-postalcode]
SHALLaddressstringGET [base]/Location?address=[address]
SHALLtypetokenGET [base]/Location?type=[system]|[code]
SHALL_idtokenGET [base]/Location?_id=[id]
SHALL_lastUpdateddateGET [base]/Location?_lastUpdated=[_lastUpdated]
Organization
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.
An Organization refers to a formally or informally recognized grouping of people or organizations formed for the purpose of achieving some form of collective action. Includes companies, institutions, corporations, departments, community groups, healthcare practice groups, payer/insurer, etc.
The DaVinci PDEX Plan-Net Network profile is based on the core FHIR Organization resource. The DaVinci PDEX Plan-Net Organization profile is based on the core FHIR US Core Organization resource .
Fetch and Search Criteria:
  • The HAP FHIR server SHALL be capable of returning a Organization resource using:
    GET [base]/Organization/[id]
  • The HAP FHIR server SHOULD be capable of returning a Organization resource using:
    GET [base]/Organization/[id]/_history/vid
  • The HAP FHIR server SHALL be capable of supporting the following _includes:
    GET [base]/Organization?[parameter=value]&_include=Organization:partof
    GET [base]/Organization?[parameter=value]&_include=Organization:coverage-area
  • The HAP FHIR server SHALL be capable of supporting the following _revincludes:
    GET [base]/Organization?[parameter=value]&_revinclude=HealthcareService:organization
    GET [base]/Organization?[parameter=value]&_revinclude=InsurancePlan:administered-by
    GET [base]/Organization?[parameter=value]&_revinclude=InsurancePlan:owned-by
    GET [base]/Organization?[parameter=value]&_revinclude=OrganizationAffiliation:primary-organization
    GET [base]/Organization?[parameter=value]&_revinclude=PractitionerRole:organization
    GET [base]/Organization?[parameter=value]&_revinclude=PractitionerRole:network
    GET [base]/Organization?[parameter=value]&_revinclude=OrganizationAffiliation:participating-organization
Extensions:
Search Parameters:
Conformance Parameter Type Example
SHALLpartofreferenceGET [base]/Organization?partof=[partof]
SHALLaddressstringGET [base]/Organization?address=[address]
SHALLnamestringGET [base]/Organization?name=[name]
SHALL_idtokenGET [base]/Organization?_id=[id]
SHALL_lastUpdateddateGET [base]/Organization?_lastUpdated=[_lastUpdated]
SHALLtypetokenGET [base]/Organization?type=[system]|[code]
SHALLcoverage-areareferenceGET [base]/Organization?coverage-area=[coverage-area]
Practitioner
A Practitioner is a person who is directly or indirectly involved in the provisioning of healthcare.
The DaVinci PDEX Plan-Net Practitioner profile is based on the core FHIR US Core Practitioner resource.
Fetch and Search Criteria:
  • The HAP FHIR server SHALL be capable of returning a Practitioner resource using:
    GET [base]/Practitioner/[id]
  • The HAP FHIR server SHOULD be capable of returning a Practitioner resource using:
    GET [base]/Practitioner/[id]/_history/vid
  • The HAP FHIR server SHALL be capable of supporting the following _revincludes:
    GET [base]/Practitioner?[parameter=value]&_revinclude=PractitionerRole:practitioner
Search Parameters:
Conformance Parameter Type Example
SHALLnamestringGET [base]/Practitioner?name=[name]
SHALL_idtokenGET [base]/Practitioner?_id=[id]
SHALL_lastUpdateddateGET [base]/Practitioner?_lastUpdated=[_lastUpdated]
SHALLfamilystringGET [base]/Practitioner?family=[family]
SHALLgivenstringGET [base]/Practitioner?given=[given]
PractitionerRole
A specific set of Roles/Locations/specialties/services that a practitioner may perform at an organization for a period of time.
The DaVinci PDEX Plan-Net PractitionerRole profile is based on the core FHIR PractitionerRole resource.
Fetch and Search Criteria:
  • The HAP FHIR server SHALL be capable of returning a PractitionerRole resource using:
    GET [base]/PractitionerRole/[id]
  • The HAP FHIR server SHOULD be capable of returning a PractitionerRole resource using:
    GET [base]/PractitionerRole/[id]/_history/vid
  • The HAP FHIR server SHALL be capable of supporting the following _includes:
    GET [base]/PractitionerRole?[parameter=value]&_include=PractitionerRole:practitioner
    GET [base]/PractitionerRole?[parameter=value]&_include=PractitionerRole:organization
    GET [base]/PractitionerRole?[parameter=value]&_include=PractitionerRole:location
    GET [base]/PractitionerRole?[parameter=value]&_include=PractitionerRole:service
    GET [base]/PractitionerRole?[parameter=value]&_include=PractitionerRole:network
Extensions:
Search Parameters:
Conformance Parameter Type Example
SHALLpractitionerreferenceGET [base]/PractitionerRole?practitioner=[practitioner]
SHALLorganizationreferenceGET [base]/PractitionerRole?organization=[organization]
SHALLlocationreferenceGET [base]/PractitionerRole?location=[location]
SHALLservicereferenceGET [base]/PractitionerRole?service=[service]
SHALLnetworkreferenceGET [base]/PractitionerRole?network=[network]
SHALLroletokenGET [base]/PractitionerRole?role=[system]|[code]
SHALLspecialtytokenGET [base]/PractitionerRole?specialty=[system]|[code]
SHALL_idtokenGET [base]/PractitionerRole?_id=[id]
SHALL_lastUpdateddateGET [base]/PractitionerRole?_lastUpdated=[_lastUpdated]