Last updated

FHIR R4 Query Guide

Table of Contents

Patient Resource

Overview

The Patient resource contains demographic and administrative information about individuals receiving healthcare services.

Key Elements

  • Demographics (name, birthdate, gender)
  • Contact information
  • Language preferences
  • Primary care provider
  • Communication preferences
  • Marital status
  • Address history

Basic Queries

# Search by name
GET [base]/Patient?name=Smith

# Search by birth date
GET [base]/Patient?birthdate=1970-01-01

# Search by identifier (e.g., SSN, MRN)
GET [base]/Patient?identifier=12345

# Combined demographic search
GET [base]/Patient?
  given=John&
  family=Smith&
  gender=male&
  birthdate=ge1960-01-01

Common Filter Options

  • name: Full, given, or family name
  • birthdate: Exact date or range
  • gender: male, female, other, unknown
  • address: City, state, postal code
  • active: true/false
  • language: Preferred language
  • identifier: Various ID types

Coverage Resource

Overview

The Coverage resource details insurance or payment information for healthcare services.

Key Elements

  • Coverage status
  • Subscriber information
  • Benefit period
  • Payor details
  • Network information
  • Cost-sharing details
  • Coverage type

Basic Queries

# Active coverage for patient
GET [base]/Coverage?
  patient=12345&
  status=active

# Coverage with specific payor
GET [base]/Coverage?
  patient=12345&
  payor=Organization/789

# Coverage within date range
GET [base]/Coverage?
  patient=12345&
  period=ge2023-01-01&
  period=le2023-12-31

Common Filter Options

  • status: active, cancelled, draft
  • type: Insurance type (medical, dental, etc.)
  • period: Coverage dates
  • payor: Insurance company
  • subscriber: Primary insurance holder
  • beneficiary: Covered individual
  • class: Coverage classification

CarePlan Resource

Overview

The CarePlan resource documents the intended care strategy and goals for a patient.

Key Elements

  • Care goals
  • Planned activities
  • Care team members
  • Treatment protocols
  • Progress notes
  • Status updates
  • Care instructions

Basic Queries

# Active care plans
GET [base]/CarePlan?
  patient=12345&
  status=active

# Care plans by condition
GET [base]/CarePlan?
  patient=12345&
  condition=Condition/567

# Care plans by date
GET [base]/CarePlan?
  patient=12345&
  date=ge2023-01-01&
  _sort=-date

Common Filter Options

  • status: draft, active, completed, cancelled
  • category: Type of care plan
  • condition: Related health conditions
  • date: Plan creation or update date
  • author: Care plan creator
  • care-team: Involved healthcare providers
  • goal: Treatment goals

Common Query Parameters

Search Result Control

  • _count: Number of results per page
  • _sort: Sort order of results
  • _include: Include related resources
  • _revinclude: Include referring resources
  • _summary: Return only summary information

Date Parameters

  • eq: Equals
  • ne: Not equals
  • gt: Greater than
  • lt: Less than
  • ge: Greater than or equals
  • le: Less than or equals

String Parameters

  • :exact: Exact match
  • :contains: Contains substring
  • :text: Text search

Advanced Query Techniques

Chained Parameters

# Patient with specific condition
GET [base]/Patient?
  _has:Condition:patient:code=http://snomed.info/sct|73211009

Combined Resources

# Patient with coverage and care plan
GET [base]/Patient?
  _id=12345&
  _include=Patient:general-practitioner&
  _revinclude=Coverage:patient&
  _revinclude=CarePlan:patient

Composite Parameters

# Search by name and birthdate combination
GET [base]/Patient?
  given-family-birthdate=John$Smith$1970-01-01
# Find all resources for a patient
GET [base]/Patient/12345/$everything

Filtering Extensions

# Search using custom extensions
GET [base]/Coverage?
  patient=12345&
  extension-custom-benefit-type=dental

Resource References

# Find care plans referencing specific practitioners
GET [base]/CarePlan?
  patient=12345&
  performer:Practitioner=Practitioner/789

Pagination

Overview

The API implements pagination using two key parameters:

  • _count: Specifies the number of results per page
  • _page_token: Token for accessing subsequent pages

Response Structure

The API returns pagination information in the link array of the response:

{
    "link": [
        {
            "relation": "search",
            "url": "[base]/Patient/?_count=1"
        },
        {
            "relation": "next",
            "url": "[base]/Patient/?_count=1&_page_token=AUAcb7bUcVAqcd..."
        },
        {
            "relation": "first",
            "url": "[base]/Patient/?_count=1"
        },
        {
            "relation": "self",
            "url": "[base]/Patient/?_count=1"
        }
    ]
}
  • search: Base search URL
  • next: URL for the next page of results (includes page token)
  • first: URL for the first page
  • self: Current page URL

Pagination Examples

Initial Query

GET [base]/Patient?_count=1

Next Page Query

GET [base]/Patient?_count=1&_page_token=AUAcb7bUcVAqcd...

Best Practices

  1. Always specify _count to control page size
  2. Store the complete _page_token for subsequent requests
  3. Handle cases where next link might not be present (last page)
  4. Don't modify other query parameters while paginating
  5. Page tokens are opaque and should not be modified

Implementation Example

async function fetchAllPatients() {
    let url = '[base]/Patient?_count=100';
    let allResults = [];
    
    while (url) {
        const response = await fetch(url);
        const data = await response.json();
        
        // Add results to collection
        allResults = allResults.concat(data.entry || []);
        
        // Find next page URL
        const nextLink = data.link.find(link => link.relation === 'next');
        url = nextLink ? nextLink.url : null;
    }
    
    return allResults;
}

Common Pagination Scenarios

Large Dataset Navigation

# First page
GET [base]/Patient?_count=100

# Use next link from response for subsequent pages
GET [base]/Patient?_count=100&_page_token=[token]

Filtered Results with Pagination

# First page of filtered results
GET [base]/Patient?_count=50&name=Smith

# Subsequent pages maintain filters
GET [base]/Patient?_count=50&name=Smith&_page_token=[token]
Previous page
Next page