HIN Document Query

The HIN query provides a FHIR-based method to retrieve clinical documents directly from connected health information networks, without requiring custom Patient360 operations.

It enables applications, especially those with existing FHIR capabilities, to query for available documents across networks your organization is licensed to access using standard FHIR requests. This approach is particularly useful for systems that already support document-based workflows and want to integrate network data access using familiar FHIR patterns.

This method serves as an alternative to the standard Patient360 retrieval workflow ($p360-retrieve) for document-based access.

Overview

Health Gorilla supports two primary patterns for accessing patient data, each designed for different use cases.

• Network queries provide real-time access to clinical documents from external data exchange networks
• Local queries provide access to data that has already been retrieved, processed, and stored in your tenant

The HIN query is used for network-based document retrieval, allowing you to discover and retrieve documents directly from connected networks. In contrast, standard FHIR queries return previously retrieved and processed data that is already available within your tenant.

Patient Identity Requirement

The patient parameter must reference a valid Health Gorilla patient ID.

This identifier is created and managed within Health Gorilla and is required for all patient-scoped queries. It is not interchangeable with external identifiers such as MRNs. Before using the HIN query, patient identity must be established through appropriate workflows, such as patient creation or identity resolution.

Key Concept: Network vs. Local Data

The distinction between querying external networks and querying locally stored data is central to understanding how the HIN query works.

Network Query (HIN)

/fhir/R4/hin/DocumentReference?patient={hg_patient_id}

When the /hin/ path element is included, the request is routed through Health Gorilla’s network access layer.

• Queries external networks your organization is licensed to access
• Returns a list of available clinical documents
• Does not store or process data within your Health Gorilla tenant

Local Query (Standard FHIR)

/fhir/R4/DocumentReference?patient={hg_patient_id}

When the /hin/ path element is omitted, the request is executed against your tenant’s stored dataset.

• Queries only data that has been previously retrieved and stored in your tenant
• Returns processed and normalized data when available

How the HIN Query Works

The HIN query uses standard FHIR resources to represent document-based exchange while abstracting the underlying network protocols.

Resources Used

• DocumentReference returns metadata describing available clinical documents, such as C-CDA files
• Binary provides access to the document content itself

Binary resources provide access to document content retrieved through Health Gorilla as a proxy to the originating systems. Health Gorilla handles the network communication and retrieval, allowing clients to interact through a consistent FHIR interface without needing to manage network-specific endpoints or identifiers.

Example Workflow

1. Query for available documents:

GET /fhir/R4/hin/DocumentReference?patient={hg_patient_id}

2. Retrieve a document:

GET /fhir/R4/hin/Binary/{binary_id}

This two-step pattern mirrors traditional document exchange workflows while using standard FHIR resources.

Record Location and Query Execution

Health Gorilla uses network-specific record location services (RLS) and exchange mechanisms to determine where patient data is available.

Rather than broadcasting queries indiscriminately, requests are directed to systems that are likely to have data for the patient. The results returned depend on several factors, including:

• Whether participating organizations have data for the patient
• Which networks your organization is licensed to access
• Consent policies and access controls enforced by responding systems

Because of this, results may vary between queries and are not guaranteed to be complete across all sources.

Key Characteristics and Limitations

HIN queries are document-based and are designed to return source-native clinical documents.

• Documents are typically C-CDA but may vary depending on the source system
• Document formats and content depend on the responding systems and may vary
• No normalization or transformation into structured FHIR resources is performed
• No deduplication or reconciliation occurs across sources
• No longitudinal patient record is created
• Retrieved data is not stored in your tenant

HIN queries return results synchronously, meaning responses are provided immediately based on available network data. For patients with large volumes of documents, results may be paginated according to standard FHIR search behavior.

Relationship to Patient360 Operations

While the HIN query provides direct access to documents, Patient360 operations support more comprehensive data workflows.

$p360-search is part of a multi-step workflow that identifies available documents across networks. $p360-retrieve extends this process by retrieving documents, extracting structured data, normalizing it, and storing it within your tenant.

Unlike HIN queries, $p360-retrieve is asynchronous. After the operation is initiated, processing occurs in the background and results become available once complete.

Patient Chart (Viewer) Considerations

The Patient Chart presents a longitudinal, structured view of patient data. To support this, it requires data that has been retrieved, normalized, deduplicated, and stored in your tenant.

HIN queries return raw documents only and do not perform any of these processing steps. As a result, HIN queries alone do not populate the Patient Chart.

To make data available in the Patient Chart, you must use the $p360-retrieve operation. This operation retrieves documents from connected networks, processes them through Health Gorilla’s data pipelines, and stores the resulting structured FHIR data in your tenant.

Retrieval can be initiated programmatically through the API or automatically through configured workflows, such as HL7 v2 ADT message triggers during patient registration.

When to Use Each Approach

Choosing between HIN queries and Patient360 operations depends on how your application uses clinical data.

Use HIN Query when:

• You need direct access to clinical documents
• Your system supports document-based workflows such as C-CDA ingestion
• You do not require structured or normalized data
• You prefer to use standard FHIR queries instead of custom operations

Use $p360-retrieve when:

• You need structured FHIR data
• You are using the Patient Chart
• You require normalized, deduplicated, and reconciled data
• You want data to be stored and reused within your tenant

Use Standard FHIR Queries when:

• You want to access data that has already been retrieved and processed
• You are working with the existing dataset stored in your tenant

Interoperability Context

The HIN query provides a FHIR-based abstraction over traditional document exchange standards, allowing clients to use a consistent API regardless of the underlying network protocols.

These approaches represent equivalent operations across different interoperability frameworks, with HIN enabling FHIR-native access to document exchange.

Key Takeaways

• Adding /hin/ to the request path enables network-based document queries
• Omitting /hin/ queries only data stored in your tenant
• HIN queries return document-based data and do not produce structured FHIR resources
• HIN queries do not store or process data within your tenant
• $p360-retrieve is required to normalize, deduplicate, store data, and populate the Patient Chart
• FHIR resources outside of HIN queries return data that has already been retrieved, processed, and stored