Skip to main content

CodeSystem Operations

The terminology service provides operations to look up codes, validate codes, test subsumption relationships, and manage CodeSystem resources.

$lookup​

Retrieves detailed information about a code, including its display name, definition, designations (translations), and properties.

For CodeSystems that store concept hierarchy, the response also includes one parent property per direct is-a parent (a concept can have more than one -- e.g. SNOMED CT) and one child property per direct child, plus abstract and inactive flags derived from concept properties. For SNOMED CT, $lookup additionally returns non-is-a clinical attribute relationships (e.g. Finding site, Associated morphology) as property entries, resolved from the imported Relationship data.

GET Request​

curl 'http://localhost:9090/fhir/r4/CodeSystem/$lookup?system=http://loinc.org&code=100011-6'

POST Request​

curl -X POST http://localhost:9090/fhir/r4/CodeSystem/$lookup \
-H "Content-Type: application/fhir+json" \
-d '
{
"resourceType": "Parameters",
"parameter": [
{
"name": "coding",
"valueCoding": {
"system": "http://loinc.org",
"code": "100012-4"
}
}
]
}

Response​

{
"resourceType": "Parameters",
"parameter": [
{
"name": "abstract",
"valueBoolean": false
},
{
"valueCode": "100012-4",
"name": "code"
},
{
"name": "designation",
"part": [
{
"valueCode": "en-US",
"name": "language"
},
{
"name": "use",
"valueCoding": {
"system": "http://loinc.org",
"code": "LONG_COMMON_NAME"
}
},
{
"name": "value",
"valueString": "Participates in decisions affecting the patient's plan of care"
}
]
},
{
"name": "display",
"valueString": "Participates in decisions affecting the patient's plan of care"
},
{
"name": "name",
"valueString": "LOINC"
},
...
{
"name": "system",
"valueUri": "http://loinc.org"
},
{
"name": "version",
"valueString": "2.82"
}
]
}

Parameters​

ParameterTypeDescription
systemuriThe code system URL
codecodeThe code to look up
versionstringSpecific version of the code system
codingCodingAlternative to system+code
propertycodeSpecific properties to return

$validate-code​

Checks whether a specific code is valid for a CodeSystem, optionally verifying its display value.

GET Request​

curl 'http://localhost:9090/fhir/r4/CodeSystem/$validate-code?url=http://hl7.org/fhir/sid/icd-10-cm&code=E11.1'

Validate with version​

curl 'http://localhost:9090/fhir/r4/CodeSystem/$validate-code?url=http://snomed.info/sct&version=http://snomed.info/sct/900000000000207008/version/20260401&code=44029006&display=Left%20lung'

POST Request​

Accepts a coding, codeableConcept, or code (combined with url), checked against either a url referencing an already-persisted CodeSystem or an inline codeSystem resource in the request body -- including one that was never separately uploaded.

curl -X POST http://localhost:9090/fhir/r4/CodeSystem/$validate-code \
-H "Content-Type: application/fhir+json" \
-d '{
"resourceType": "Parameters",
"parameter": [
{ "name": "url", "valueUri": "http://snomed.info/sct" },
{ "name": "code", "valueCode": "181216001" },
{ "name": "display", "valueString": "Entire lung (body structure)" }
]
}'

Response​

{
"resourceType": "Parameters",
"parameter": [
{
"name": "result",
"valueBoolean": true
},
{
"name": "system",
"valueUri": "http://snomed.info/sct"
},
{
"valueCode": "181216001",
"name": "code"
},
{
"name": "version",
"valueString": "http://snomed.info/sct/900000000000207008/version/20260401"
},
{
"name": "display",
"valueString": "Entire lung"
}
]
}

If a supplied display doesn't match the concept's display or any of its designations (synonyms count as a match), the response instead returns result: false with a message explaining the mismatch.

Parameters​

ParameterTypeDescription
urluriCanonical URL of the CodeSystem to validate against
codecodeThe code to validate
codingCodingAlternative to code + url
codeableConceptCodeableConceptAlternative carrying one or more codings
codeSystemCodeSystemInline CodeSystem to validate against, instead of url
versionstringSpecific version of the code system
displaystringExpected display value to verify against the matched concept

$subsumes​

Determines hierarchical relationships between two codes (is-a relationships). This is particularly useful for code systems with hierarchical structure, such as SNOMED CT and ICD-10-CM.

GET Request​

curl 'http://localhost:9090/fhir/r4/CodeSystem/$subsumes?system=http://snomed.info/sct&codeA=138875005&codeB=73211009'

POST Request​

curl -X POST http://localhost:9090/fhir/r4/CodeSystem/$subsumes \
-H "Content-Type: application/fhir+json" \
-d '{
"resourceType": "Parameters",
"parameter": [
{
"name": "system",
"valueUri": "http://snomed.info/sct"
},
{
"name": "codingA",
"valueCoding": {
"system": "http://snomed.info/sct",
"code": "138875005"
}
},
{
"name": "codingB",
"valueCoding": {
"system": "http://snomed.info/sct",
"code": "73211009"
}
}
]
}'

Response​

{
"resourceType": "Parameters",
"parameter": [
{
"valueCode": "subsumes",
"name": "outcome"
}
]
}

Possible Outcomes​

OutcomeMeaning
equivalentCodes represent the same concept
subsumesCode A subsumes (is broader than) Code B
subsumed-byCode A is subsumed by (is narrower than) Code B
not-subsumedNo hierarchical relationship

Search CodeSystems​

Retrieve CodeSystems matching search criteria.

curl 'http://localhost:9090/fhir/r4/CodeSystem?url=http://loinc.org'

Returns a FHIR Bundle of matching CodeSystem resources.

Create a CodeSystem​

Upload a new CodeSystem resource.

curl -X POST http://localhost:9090/fhir/r4/CodeSystem \
-H "Content-Type: application/fhir+json" \
-d '{
"resourceType": "CodeSystem",
"id": "demo-manual-codesystem",
"url": "http://example.org/fhir/CodeSystem/demo-manual-codesystem",
"version": "1.0.0",
"name": "DemoManualCodeSystem",
"title": "Demo CodeSystem created via plain POST",
"status": "active",
"content": "complete",
"caseSensitive": true,
"concept": [
{ "code": "A", "display": "Concept A" },
{ "code": "B", "display": "Concept B" }
]
}'

Returns 201 Created on success.

Standard Code Systems​

Common code systems used in FHIR:

Code SystemURIUse
LOINChttp://loinc.orgLab observations, clinical measurements
SNOMED CThttp://snomed.info/sctClinical findings, procedures
ICD-10-CMhttp://hl7.org/fhir/sid/icd-10-cmDiagnoses
RxNormhttp://www.nlm.nih.gov/research/umls/rxnormMedications
CPThttp://www.ama-assn.org/go/cptProcedures
UCUMhttp://unitsofmeasure.orgUnits of measure

LOINC, SNOMED CT, and ICD-10-CM can be loaded into the service directly from their standard release formats -- see Upload Operations.