Patient Access API
Overview
The Patient Access API can be used to build applications that enable HAP customers to access their claims and encounter information, along with a subset of their clinical data. You can create an application to access this data using read-only RESTful API GET calls.
Below you will find the FHIR profiles, resource, and RESTful capabilities the HAP Patient Access 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 Patient Access FHIR server maintains patient-specific records which could be exposed by malicious actors. For this reason, all transactions using the Patient Access API must be secured as directed by regulation. Access is limited to only authorized individuals. Furthermore, HAP requires that data be protected in transit, and any company building an application based on the HAP Patient Access API must implement appropriate audit and notification procedures.
Developers of third-party applications SHOULD be aware of these security considerations associated with FHIR transactions, particularly those related to:
The purpose of HAP's Implementation Guide, security conformance requirements are as follows:
  • Systems SHALL establish a risk analysis and management regime that conforms with HIPAA security regulatory requirements. In addition, US Federal systems SHOULD conform with the risk management and mitigation requirements defined in NIST 800 series documents. This SHOULD include security category assignment in accordance with NIST 800-60 vol. 2 Appendix D.14. The coordination of risk management and the related security and privacy controls - policies, administrative practices, and technical controls - SHOULD be defined in the Business Associate Agreement when available.
  • Systems SHALL reference a single time source to establish a common time base for security auditing, as well as clinical records, among computing systems, The selected time SHOULD be documented in the Business Associate Agreement.
  • Systems SHALL keep audit logs of the various transactions.
  • Systems SHALL use TLS version 1.2 or higher for transmissions not taking place over a secure network connection. (Using TLS even within a secured network environment is still encouraged to provide defense depth.) US Federal systems SHOULD conform with FIPS PUB 140-2.
  • Systems SHALL conform to FHIR Communications Security requirements.
  • For Authentication and Authorization, Systems SHALL support the SMART App Launch Framework for client <-> server interactions.
    • Note: The SMART on FHIR specifications include the required OAuth 2.0 scopes for enabling security decisions.
  • Systems SHALL implement consent requirements per their state, local, and institutional policies. The Business Associate Agreements SHOULD document systems mutual consent requirements.
Authorization, Authentication, and Registration
Client applications and systems of record SHALL support the standalone launch sequence of the SMART App Launch framework for user authorization and client authentication. Systems of record SHALL publish their authorization and token endpoints for discovery in accordance with the SMART App Launch framework.
Health Alliance Plan FHIR server supports only Proof Key for Code Exchange (PKCE) authorization flow. PKCE provides important security enhancement to applications by mitigating the risk of authorization code being stolen by malicious applications installed on the device.
Your application will need to query either the [.well-known] or [metadata] endpoints to fetch the authorization and token service endpoints. Using [.well-known] endpoint, your application can read Patient Access API capabilities such as token auth methods, scopes, and response types. Your application can then use this information to connect to the Patient Access API using OAuth 2.0 authorization code flow with PKCE.
The [.well-known] and [metadata] endpoints are given below:
/[baseUrl]/.well-known/smart-configuration
/[baseUrl]/metadata

Proof Key for Code Exchange (PKCE)
FHIR RESTful API Capabilities
HAP has implemented and supports RESTful behaviors according to the FHIR specification.
The HAP FHIR server supports JSON source formats for all US Core interactions.
The HAP FHIR server returns the following http status codes:
HTTP Status Code Description
200 Successful Request
400 Invalid Parameter
401 Not Authorized
403 Insufficient Scope
404 Unknown Resource
410 Deleted 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/[patientguid]")
    • 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.
Patient Access Resources
Below you will find the resources and endpoints supported by the HAP Patient Access 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 Patient Access API:
Condition
A clinical condition, problem, diagnosis, or other event, situation, issue, or clinical concept that has risen to a level of concern.
The US Core Condition Profile is based upon the core FHIR Condition Resource.
Fetch and Search Criteria:
  • The HAP FHIR server SHALL be capable of returning a Condition resource using:
    GET [base]/Condition/[id]
Search Parameters:
Conformance Parameter Type Example
MAY category token GET [base]/Condition?category=[system]|[code]
MAY clinical-status token GET [base]/Condition?clinical-status=[system]|[code]
SHALL patient reference GET [base]/Condition?patient=[patient]
MAY onset-date date GET [base]/Condition?onset-date=[onset-date]
MAY code token GET [base]/Condition?code=[system]|[code]
Combined Search Parameters:
Conformance Parameter Type Example
SHOULD patient+onset-date reference+date GET [base]/Condition?patient=[patient]&onset-date=[onset-date]
SHOULD patient+category reference+token GET [base]/Condition?patient=[patient]&category=[system]|[code]
SHOULD patient+clinical-status reference+token GET [base]/Condition?patient=[patient]&clinical-status=[system]|[code]
SHOULD patient+code reference+token GET [base]/Condition?patient=[patient]&code=[system]|[code]
Coverage
The Coverage resource is intended to provide the high-level identifiers and descriptors of an insurance plan, typically the information which would appear on an insurance card, which may be used to pay, in part or in whole, for the provision of health care products and services.
The CARIN BB Coverage Profile is based on the core FHIR Coverage Resource.
Fetch and Search Criteria:
  • The HAP FHIR server SHALL be capable of returning a Coverage resource using:
    GET [base]/Coverage/[id]
  • The HAP FHIR server SHALL be capable of supporting the following _include parameter:
    GET [base]/Coverage?[parameter=value]&_include=Coverage:payor
Search Parameters:
There are no Search Parameters for Coverage
DiagnosticReport
A diagnostic report, which can be a combination of request information, atomic results, images, interpretation, as well as formatted reports.
The US Core Diagnostic Report Profile is based upon the core FHIR DiagnosticReport Resource and created to meet the 2015 Edition Common Clinical Data Set 'Laboratory test(s) and Laboratory value(s)/result(s)' requirements, and supports the US Core DiagnosticReport Profile for Laboratory Results Reporting.
Fetch and Search Criteria:
  • The HAP FHIR server SHOULD be capable of returning a DiagnosticReport resource using:
    GET [base]/DiagnosticReport/[logicalID]
Search Parameters:
Conformance Parameter Type Example
MAY status token GET [base]/DiagnosticReport?status=[system]|[code]
SHALL patient reference GET [base]/DiagnosticReport?patient=[patient]
MAY category token GET [base]/DiagnosticReport?category=[system]|[code]
MAY code token GET [base]/DiagnosticReport?code=[system]|[code]
MAY date date GET [base]/DiagnosticReport?date=[date]
Combined Search Parameters:
Conformance Parameter Type Example
SHALL patient+category+date reference+token+date GET [base]/DiagnosticReport?patient=[patient]&category=[system]|[code]&date=[date]
SHOULD patient+status reference+token GET [base]/DiagnosticReport?patient=[reference]&status=[system]|[code]
SHOULD patient+code+date reference+token+date GET [base]/DiagnosticReport?patient=[reference]&code=[system]|[code]&date=[date]
SHALL patient+code reference+token GET [base]/DiagnosticReport?patient=[reference]&code=[system]|[code]
SHALL patient+category reference+token GET [base]/DiagnosticReport?patient=[reference]&category=[system]|[code]
ExplanationOfBenefit
This resource provides claim details and adjudication details from the processing of a Claim.
The ExplanationOfBenefit resources can represent a Patient, Provider, Insurer, Care Team, Facility and Coverage with references to Patient, Organization, Practitioner, PractitionerRole, Location and Coverage resources. The HAP FHIR server can return all Patient, Practitioner, Organization, PractitionerRole, Location and Coverage resources for an ExplanationOfBenefit via the _id of the referenced resource.
The HAP FHIR server supports the _include parameter for search parameters defined on the named reference elements. Your application must also support the _include parameter for search parameters defined on these elements.
Fetch and Search Criteria:
  • The HAP FHIR server SHALL be capable of returning an Explanation of Benefit resource using:
    GET [base]/ExplanationOfBenefit/[patient]
  • The HAP FHIR server SHALL be capable of supporting the following _include parameters:
    GET [base]/ExplanationOfBenefit?[parameter=value]&_include=ExplanationOfBenefit:patient
    GET [base]/ExplanationOfBenefit?[parameter=value]&_include=ExplanationOfBenefit:provider
    GET [base]/ExplanationOfBenefit?[parameter=value]&_include=ExplanationOfBenefit:coverage
    GET [base]/ExplanationOfBenefit?[parameter=value]&_include=ExplanationOfBenefit:insurer
    GET [base]/ExplanationOfBenefit?[parameter=value]&_inlude=ExplanationOfBenefit:*
Search Parameter Summary:
Search Parameters must be used in combination with the patient search parameter.
Conformance Parameter Type Example
SHALL _id token GET [base]/ExplanationOfBenefit?_id=[id]
SHALL patient reference GET [base]/ExplanationOfBenefit?patient=[patient]
SHALL _lastUpdated date GET [base]/ExplanationOfBenefit?_lastUpdated=[_lastUpdated]
SHALL type token GET [base]/ExplanationOfBenefit?type=[system]|[code]
SHALL identifier token GET [base]/ExplanationOfBenefit?identifier=[system]|[code]
SHALL service-date date GET [base]/ExplanationOfBenefit?service-date=[service-date]
Goal
Describes the intended objective(s) for a patient, group or organization.
The US Core Goal Profile is based upon the core FHIR Goal resource and created to meet the 2015 Edition Common Clinical Data Set 'Goals' requirements.
Fetch and Search Criteria:
  • The HAP FHIR server SHALL be capable of returning a Goal resource using:
    GET [base]/Goal/[id]
Search Parameters:
Conformance Parameter Type Example
SHALL patient reference GET [base]/Goal?_patient=[patient]
Combined Search Parameters:
Conformance Parameter Combination Types
SHOULD patient+ target-date reference+date
SHOULD patient+ lifecycle-status reference+token
List
The DaVinci PDex CoveragePlan profile is based on the core FHIR List resource and represents a health plan’s prescription benefits, containing links to administrative information, a list of formulary drugs covered under that plan, and a definition of drug tiers and their associated cost-sharing models.
Extensions:
Search Parameters
There are no Search Parameters for List.
Location
Details and position information for a physical place where services are provided and resources and participants may be stored, found, contained, or accommodated.
The US Core Location Profile is based upon the core FHIR Location resource.
Fetch and Search Criteria:
  • The HAP FHIR server SHALL be capable of returning a Location resource using:
    GET [base]/Location/[id]
Search Parameters:
Conformance Parameter Type
SHALL name string
SHALL address string
SHOULD address-city string
SHOULD address-state string
SHOULD address-postalcode string
MedicationKnowledge
The DaVinci PDex FormularyDrug profile is based on the core FHIR MedicationKnowledge resource and provides plan-specific information about a prescription drug identified by an RxNORM identifier. The resource describes drugs by providing the RxNorm code, the PlanID of the formulary, and information on prescription limits.
Fetch and Search Criteria:
  • The HAP FHIR Server SHALL be capable of returning a MedicationKnowledge resource using:
    GET [base]/MedicationKnowledge/[id]
Extensions:
Search Parameters:
Conformance Parameter Type Example
SHALL DrugName string GET [base]/MedicationKnowledge?DrugName=[DrugName]
SHALL DrugTier string GET [base]/MedicationKnowledge?DrugTier=[system]|[code]
SHALL DrugPlan string GET [base]/MedicationKnowledge?DrugPlan=[DrugPlan]
SHALL code string GET [base]/MedicationKnowledge?code=[system]|[code]
SHALL _id string GET [base]/MedicationKnowledge?_id=[id]
Observation
Used for simple observations such as device measurements, laboratory atomic results, vital signs, height, weight, smoking status, comments, etc. Other resources are used to provide context for observations such as laboratory reports, etc.
For laboratory results, the HAP FHIR server supports the US Core Laboratory Result Observation Profile.
For vital signs, the HAP FHIR server supports:
Fetch and Search Criteria:
  • The HAP FHIR Server SHALL be capable of returning an Observation resource using:
    GET [base]/Observation/[id]
Combined Search Parameters:
Conformance Parameter Combination Types
SHALL patient+ code reference+token
SHOULD patient+ category+ status reference+token+token
SHALL patient+ category+ date reference+token+date
SHOULD patient+ code+ date reference+token+date
SHALL patient+ category reference+token
Organization
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 CARIN BB Organization Profile is based on the US Core Organization Profile, itself based on the core FHIR Organization resource.
Fetch and Search Criteria:
  • The HAP FHIR server SHALL be capable of returning an Organization resource using:
    GET [base]/Organization/[id]
Search Parameters:
Conformance Parameter Type
SHALL name string
SHALL address string
Patient
Information about an individual or animal receiving health care services. The CARIN BB Patient Profile is based on the US Core Patient Profile , itself based upon the core FHIR Patient resource and designed to meet the applicable patient demographic data elements from the 2015 Edition Common Clinical Data Set.
Fetch and Search Criteria:
  • The HAP FHIR Server SHALL be capable of returning a Patient resource using:
    GET [base]/Patient/[id]
Search Parameters:
Conformance Parameter Type
SHALL _id string
SHALL identifier string
SHALL name string
Combined Search Parameters:
Conformance Parameter Combination Types
SHALL gender+ name token+string
SHOULD birthdate+ family date+string
SHALL birthdate+ name date+string
SHOULD family+ gender string+token
Practitioner
A person with a formal responsibility in the provisioning of healthcare or related services.
The CARIN BB Practitioner Profile is based on the US Core Practitioner Profile, itself based on the core FHIR Practitioner resource.
Fetch and Search Criteria:
  • The HAP FHIR Server SHALL be capable of returning a Practitioner resource using:
    GET [base]/Practitioner/[id]
Search Parameters:
Conformance Parameter Type
SHALL name string
SHALL identifier token
PractitionerRole
A specific set of Roles/Locations/specialties/services that a practitioner may perform at an organization for a period of time.
The US Core 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]
Search Parameters:
Conformance Parameter Type
SHALL name string
SHALL identifier token