FHIR Search Parameters

Query DDFS FHIR R4 and R6 resources with the parameter names, value syntax, and result controls advertised for the deployed endpoint.

DDFS provides version-specific search endpoints for FHIR R4 (4.0.1) and FHIR R6 ballot4 (6.0.0-ballot4). Use the endpoint for the selected version:

FHIR R4: GET https://<ddfs-instance-id>.ddfs.<region>.oci.oraclecloud.com/api/fhir/r4/{Resource}
FHIR R6 ballot4: GET https://<ddfs-instance-id>.ddfs.<region>.oci.oraclecloud.com/api/fhir/r6-ballot4/{Resource}

For a supported resource type, a successful search returns a FHIR Bundle whose type is searchset.

Search support can vary by version and resource. Before adding a filter, confirm it in the CapabilityStatement returned by the deployed metadata endpoint and in the applicable published SearchParameter definition. See also the Supported Search and Control Parameters.

Common Search Controls

Use a control only when it is advertised for the target resource:


Parameter	Type	Description
`_count`	number or result control	Requests the maximum page size. A returned page can contain fewer matches.
`_total`	result control	Requests a supported total-handling mode. `Bundle.total` remains optional, so clients must handle its absence.
`_id`	token	Filters by logical resource ID.
`_lastUpdated`	date	Filters by the resource last-updated instant.
`_profile`	uri (R4); reference (R6)	Filters by canonical profile URL. The advertised search parameter type differs by FHIR version.
`_tag`	token	Filters by a resource tag token.

For paging, follow the URL in Bundle.link whose relation is next verbatim. Do not construct a paging URL or alter the server-provided query.

Empty Search Results

A successful search with no entries still returns a Bundle with type=searchset. The response omits entry instead of returning an empty array. Clients must handle an absent entry as an empty collection.

The following response excerpt shows the empty result. Other response fields are omitted from the excerpt.

{
  "resourceType": "Bundle",
  "type": "searchset"
}

Bundle.total is optional. Its presence depends on the supported total-handling mode; do not require it to process an empty result.

Value Types and Syntax

Use the value shape defined for the advertised search parameter.


Type	Syntax	Example
date	A FHIR date, dateTime, or instant, optionally preceded by a supported comparator.	`birthdate=ge2020-01-01`
string	A string, optionally followed by a supported modifier on the parameter name.	`name:exact=smith`
token	`code` or `system\|code`.	`status=active`
reference	A FHIR reference, supported reference modifier, or supported chain.	`patient=Patient/{rid}`
uri	A URI value.	`url=https://example.com/topic`
number	A numeric value.	`_count=20`

Comparators, Modifiers, and Chains

Use only the comparators, modifiers, and chains advertised for the parameter, resource, and FHIR version.

A date parameter can advertise comparators such as eq, ne, gt, lt, ge, le, sa, eb, and ap.
A string parameter can advertise a supported modifier such as :exact.
A reference parameter can advertise :identifier or chains such as patient.identifier, device.manufacturer, or practitioner.name.
When the endpoint permits a bounded range, repeat the actual parameter name, for example date=ge2026-01-01&date=le2026-12-31.

Examples

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

GET /api/fhir/r6-ballot4/Observation?patient=Patient/{rid}&code=http%3A%2F%2Floinc.org%7C8867-4&_count=20
Accept: application/fhir+json

GET /api/fhir/r6-ballot4/Observation?device.manufacturer=Acme
Accept: application/fhir+json

GET /api/fhir/r6-ballot4/Observation?_count=20
Accept: application/fhir+json

Keep Sensitive Search Values Out of the URL

Use GET for ordinary searches. When sensitive search values should not appear in the request URL, use the supported resource's POST /_search endpoint. Send the search parameters in the request body with Content-Type: application/x-www-form-urlencoded.

Putting search values in a POST body keeps them out of the request URL, but does not by itself protect PHI. Continue to use HTTPS and apply the logging, access-control, and retention safeguards in the following section.

Use POST search only for resource types and search parameters supported on the selected FHIR API surface. The following examples search for a Patient on the R4 API surface. The access token must grant 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. See Create Integrated Applications for DDFS OAuth for OAuth setup and Authentication and Scopes for scope syntax. A successful request returns 200 OK with a searchset Bundle.

curl -sS -X POST \
  -H "Authorization: Bearer <access-token>" \
  -H "Accept: application/fhir+json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "identifier=<identifier-system>|<identifier-value>" \
  "https://<ddfs-instance-id>.ddfs.<region>.oci.oraclecloud.com/api/fhir/r4/Patient/_search"

$headers = @{
  Authorization = "Bearer <access-token>"
  Accept = "application/fhir+json"
}
$body = @{
  identifier = "<identifier-system>|<identifier-value>"
}

Invoke-RestMethod `
  -Method Post `
  -Uri "https://<ddfs-instance-id>.ddfs.<region>.oci.oraclecloud.com/api/fhir/r4/Patient/_search" `
  -Headers $headers `
  -ContentType "application/x-www-form-urlencoded" `
  -Body $body

Protect Sensitive Search Data

FHIR search query strings can contain identifiers, names, dates, codes, references, and other protected health information (PHI). Treat the entire URL as sensitive data.

Use HTTPS and percent-encode parameter values with a standards-compliant URL library. Do not encode the parameter separators added by the library a second time.
Do not record complete search URLs or POST search bodies in application, proxy, access, analytics, or support logs. Redact or omit search values before logging.
Do not paste unredacted search URLs into tickets, chat, or diagnostics. Share only the minimum data needed to investigate a request.
Apply access controls and retention requirements to any approved diagnostic data that can contain PHI.

Oracle Cloud Infrastructure Documentation