Patient Search and Pagination

Prerequisites

DDFS does not support SMART on FHIR authorization or launch workflows. Use an OAuth 2.0 access token issued by OCI Identity Domains with the DDFS resource scopes required for the request. Configure the client and token by following Create an Integrated Application and DDFS Authentication Reference.

• An OAuth access token with Patient search permission. When configuring the client grant and token request, use ddfssystem/Patient.s for search-only access or ddfssystem/Patient.rs for Patient read and search access.
• A reverse include of Provenance requires Provenance read permission, such as ddfssystem/Provenance.r. A separate Observation search requires Observation search permission, such as ddfssystem/Observation.s or ddfssystem/Observation.rs.
• The DDFS endpoint origin represented by {base}.
• A Patient identifier or other supported filter value appropriate for your workflow.
• Confirmation from GET {base}/api/fhir/r4/metadata that Patient and the parameters used by the request are advertised.

Overview

This scenario uses the FHIR R4 (4.0.1) Patient search endpoint. A successful search returns a Bundle whose type is searchset. Search support is version-specific, so do not copy parameters to another resource or version unless its capability statement advertises them.

Search URLs can contain protected health information (PHI). Apply the handling guidance in Protect Sensitive Search Data.

Supported Search Parameters

The R4 Patient endpoint advertises common controls such as _count, _total, _id, _lastUpdated, _profile, and _tag. Patient-specific parameters include birthdate, death-date, family, given, identifier, and name.

See Search Patient for the deployed parameter details and supported comparators, modifiers, chains, includes, and reverse includes.

Run Basic Searches

Search by family and given name:

GET {base}/api/fhir/r4/Patient?family=Doe&given=Jane
Accept: application/fhir+json

Search by identifier token:

GET {base}/api/fhir/r4/Patient?identifier=http%3A%2F%2Fhospital.example.org%2Fmrn%7C12345
Accept: application/fhir+json

Search a birthdate range by repeating the parameter with supported FHIR prefixes:

GET {base}/api/fhir/r4/Patient?birthdate=ge2020-01-01&birthdate=le2025-12-31
Accept: application/fhir+json

Request Provenance resources that target a matching Patient by using the advertised reverse include:

GET {base}/api/fhir/r4/Patient?_id={patient_id}&_revinclude=Provenance:target
Accept: application/fhir+json

To retrieve related Observations, search the Observation endpoint using its advertised Patient reference parameter:

GET {base}/api/fhir/r4/Observation?patient=Patient/{patient_id}
Accept: application/fhir+json

Page Through Results

Use _count to request a page size. Treat it as the requested maximum number of matches in a page, not a guarantee that every page contains that many entries.

GET {base}/api/fhir/r4/Patient?_count=50&family=Doe
Accept: application/fhir+json

A search response can include a Bundle.link entry whose relation is next:

(application/fhir+json; excerpt)
{
  "resourceType": "Bundle",
  "type": "searchset",
  "link": [
    {
      "relation": "self",
      "url": "{base}/api/fhir/r4/Patient?_count=50&family=Doe"
    },
    {
      "relation": "next",
      "url": "{server-provided-next-url}"
    }
  ]
}

Request the server-provided next URL verbatim. Do not construct it, edit its query parameters, or combine it with parameters from the original request.

GET {server-provided-next-url}
Accept: application/fhir+json

Bundle.total is optional. If your workflow needs a total and the endpoint advertises _total, request the supported total mode and handle a response that omits Bundle.total. Use the presence or absence of the server-provided next link, rather than a calculated page number, to continue or stop paging.

Use _lastUpdated

Filter by a last-update instant:

GET {base}/api/fhir/r4/Patient?_lastUpdated=ge2025-01-01T00:00:00Z
Accept: application/fhir+json

Combine the filter with paging:

GET {base}/api/fhir/r4/Patient?_lastUpdated=ge2025-01-01T00:00:00Z&_count=100
Accept: application/fhir+json

Client-side Caching Notes

Do not assume that search-set entries contain response metadata. Use HTTP headers returned for the operation only as documented by the endpoint. For a specific resource version, use the advertised versioned-read interaction and the resource version ID.

Errors

• 400: The request contains a malformed or unsupported parameter or value.
• 401: Credentials are missing or invalid.
• 403: The OAuth access token is valid, but it does not grant a permission required by the search, such as Patient search permission or read permission for a requested related resource.

See OperationOutcome Reference for FHIR-formatted error guidance.

References

• Search Patient
• OperationOutcome Reference
• DDFS Authentication Reference
• FHIR R4 Search
• FHIR R4 Patient

Status Codes