Health Record Retrieval ($everything)

This workflow demonstrates how to retrieve a user's data connections and each of their associated health records. The workflow combines GraphQL queries to access connection details through SubscriptionStatus resources and the Patient $everything REST API for comprehensive health record retrieval from each connected data source.

Prerequisites

• End-User Authentication - User must be authenticated
• Account Creation and Consent - User account and consent must be completed
• Established Data Connections - At least one connection must be established through Search for & Establish Connections or Locate & Establish Connections with Network Record Locator Service

Environment URLs:

• Client-Sandbox: https://api.client-sandbox.icanbwell.com/v1/graphql

Workflow Steps

Step 1: Retrieve Connection Details

Use the subscriptionStatuses GraphQL query to retrieve SubscriptionStatus resources containing the user's data connection details.

GraphQL Query:

query ($security: SearchToken) { 
  subscriptionStatuses(_security: $security) { 
    entry { 
      resource {
        extension { 
          id 
          url 
          valueString 
        }
        notificationEvent { 
          id 
          timestamp 
        }
        error { 
          coding { 
            system 
            code 
            display 
          } 
        }
      } 
    } 
  } 
}

Response Properties:

The response returns a bundle of SubscriptionStatus FHIR resources with the following key properties:

Step 2: Extract Source Patient ID

From the SubscriptionStatus response, extract the source_patient_id for retrieving health records associated with a specific connection. This identifier is used in the FHIR $everything operation in Step 3.

Step 3: Retrieve Health Records Using FHIR $everything

Once you have the source_patient_id, use the FHIR $everything operation to retrieve all health records associated with that connection. This operation uses the following REST endpoint:

REST Endpoint:

GET {baseURL}/v1/Patient/{source_patient_id}/$everything

Optional Query Parameters:

Examples:

• Clinical resources only: GET /v1/Patient/{id}/$everything?_includePatientLinkedOnly=true
• Specific resource types: GET /v1/Patient/{id}/$everything?_type=Observation,Encounter
• Recent updates: GET /v1/Patient/{id}/$everything?_since=2024-01-01T00:00:00Z

Resource Coverage:

The $everything operation returns a FHIR bundle containing:

• Clinical Resources - Observation, Condition, Procedure, MedicationStatement, AllergyIntolerance, and other clinical data
• Non-Clinical Resources - Practitioner, Location, Organization, and supporting data
• Encounter Information - Healthcare visits and events
• Patient Demographics - Patient demographic information
• Referenced Resources - Related resources based on query parameters

Enriched Data Resources:

Some resource types may include data derived from multiple sources:

MedicationStatement Resources: May aggregate data from multiple Medication, MedicationRequest, or MedicationStatement resources from the same data provider. Data provenance and meta.source values are retained, and a derivedFrom field references the original resources.

Composition Resources: Aggregate multiple resources but are not returned by the patient $everything operation, so no special handling is required.

Other Enriched Resources: Have a 1:1 relationship with the original unenriched resource (e.g., a single Observation with normalized units).

Fetch Updated Resources:

The _since parameter retrieves only resources added or updated after the specified date-time. If no resources have been updated since the provided date, an empty bundle is returned.

Example:

GET /v1/Patient/{id}/$everything?_since=2024-11-01T00:00:00Z

Note: The _type parameter is recommended when testing in interactive API playgrounds to manage response payload size and prevent browser performance issues.