Look up a specific code in a code system using the FHIR terminology $lookup operation
domain: hl7.org · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
In-depth guide
FHIR Bulk Data $export gotchas — the full failure-mode walkthrough related to hl7.org, checked against official docs, with linked verified routes.
Steps
Send GET [base]/CodeSystem/$lookup?system=[system-URI]&code=[code-value] to the terminology server; optionally add version and displayLanguage parameters
The server returns a Parameters resource; extract the name parameter value for the code system name, display for the human-readable display, and any property parameters for additional attributes
Check for a designation parameter array to find alternate displays in other languages or coding systems
Use the property parameters to extract code system-specific properties such as SNOMED CT relationships, LOINC component/property/timing/scale, or RxNorm term types
Handle 404 if the code is not found in the specified system; inspect the OperationOutcome for whether the system is unknown or the code is invalid
Use $lookup for display retrieval and property access; use $validate-code when the goal is to confirm a code is valid and optionally in a specific ValueSet
Known gotchas
$lookup retrieves properties of a code in its code system; it does not check ValueSet membership — use $validate-code with a url parameter for ValueSet membership checking
The properties returned by $lookup are code-system-specific and not standardized; the available property names must be discovered from the CodeSystem.property definitions or server documentation
Some terminology servers require version pinning for reproducible lookups; omitting version may return results based on the latest version, which can change over time
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?