Skip to main content
By default, the FHIR Extraction endpoint produces every resource it finds in a note, with any code that fits. Two optional request fields let you narrow that down:
  • resourceGroups chooses what the endpoint produces. For example: Conditions and Procedures, but no Observations.
  • filters restricts which codes the endpoint may assign. For example: only body sites under the knee.
The two fields work independently. You can use one, both, or neither. This guide shows an example for each common case. Filter reference lists every field, operator, and validation rule.

​
When to filter

  • You already have the data in structured form. Lab results from your lab system or vital signs from monitors are more reliable than the same values read from a note. Turn those categories off. Reduce extraction errors explains why.
  • Your workflow only needs part of the result. A problem-list app has no use for exam findings. A smaller response is easier to process, and Observation categories you leave out are not extracted at all, so the request uses fewer tokens.
  • Your downstream system only accepts some codes. A diabetes registry only takes diabetes diagnoses, and an orthopedic app only cares about knee structures.
A filter limits which codes the endpoint may choose. It does not make the endpoint find more. When no allowed code fits a mention, the endpoint leaves the resource out rather than assign a code that does not fit. A tight filter can therefore remove resources you expected to see.

​
Choose which resources to produce

List the resource groups you want in resourceGroups. A group you leave out is not produced. To narrow a group further, add categories:
Patient and Encounter are always produced, so you do not need to list them. Categories per resource group lists the categories of each group.
Your lab system and monitors already send lab results and vital signs. Produce everything else.
The endpoint skips the laboratory and vital-signs extraction. “HbA1c 7.2 %” and “BP 150/90” produce no Observation, so the values from your lab system and monitors stay the only source. “Smokes 10 cigarettes a day” still produces a social-history Observation.
Produce only the diagnoses that belong on a problem list.
The response holds the Patient, the Encounter, and the Conditions with category problem-list-item. A chronic condition such as “Type 2 diabetes for 10 years” stays. A diagnosis that only concerns this visit, such as “Acute bronchitis”, has category encounter-diagnosis, so the endpoint drops it. No Observations, Procedures, allergies, or family history appear.

​
Restrict which codes the endpoint assigns

Each entry in filters applies to one coding system, named in systemId. It allows codes with include, removes codes with exclude, and can narrow where it applies with scope:
Without a scope, a filter applies to the code field of every resource group that uses the coding system. The examples below go from the widest scope to the narrowest.
Do not assign codes under “Mental disorder” (74732009) anywhere.
Use this when your application must not store a sensitive kind of diagnosis. “Generalized anxiety disorder” produces no Condition, and “Mother has depression” produces no FamilyMemberHistory. “Known asthma” still produces a Condition.The filter leaves bodySite and valueCodeableConcept alone, because a filter without a scope only applies to code.
Only allow disorders as Condition codes.
Condition codes always come from SNOMED CT disorders, findings, and events. This filter narrows that built-in scope to disorders, so “Chest pain on exertion” (a finding) produces no Condition.
Only allow the two HbA1c LOINC codes for laboratory results.
The filter leaves the other Observation categories alone.
Only allow knee structures as the body site of a Condition.
The filter leaves the Condition code field alone.

​
Combine filters

When several filters apply to the same field, a code must match every include and no exclude. A filter can also only narrow the built-in scope of a field, never widen it. How filters combine lists the rules.
Allow a short list of LOINC codes for all Observations, and narrow laboratory results further.
Both filters apply to laboratory Observations, so a laboratory code must match both includes. Only the HbA1c codes pass. The other Observation categories only need to match the first include.

​
Fix a rejected filter

The endpoint checks every filter before it starts. A filter that could never change the response, such as a filter on a field the resource does not have, returns a 400 instead of being ignored. The error message names the part of the filter that failed. For a value outside a fixed list, such as an unknown category or op, details names the field instead. Check it against Validation rules.
An AllergyIntolerance bodySite filter fails, because the resource has no body site field.
The request scopes a SNOMED CT filter to the bodySite field of AllergyIntolerance. A FHIR R4 AllergyIntolerance has no bodySite field, so the filter could never change the response. The endpoint returns a 400 instead of ignoring the filter.

​
Next steps

FHIR filter reference

Look up every field, operator, category, and validation rule.

Observation resource group

See how each Observation category looks in the response.
Please contact us if you need help configuring your filters.