Release 4

Vocabulary Work Group Maturity Level: NNormative (from v4.0.1) Compartments: N/A
This page has been approved as part of an ANSI standard. See the Conformance Package for further details.

Given a code/system, or a Coding, get additional details about the concept, including definition, status, designations, and properties. One of the products of this operation is a full decomposition of a code from a structured terminology.

When invoking this operation, a client SHALL provide both a system and a code, either using the system+code parameters, or in the coding parameter. Other parameters are optional.

The official URL for this operation definition is

Formal Definition (as a OperationDefinition).

URL: [base]/CodeSystem/$lookup

This is an idempotent operation

In Parameters:
ИмяКардинальное множествоТипПривязкаПрофильДокументация

The code that is to be located. If a code is provided, a system must be provided


The system for the code that is to be located


The version of the system, if one was provided in the source data


A coding to look up


The date for which the information should be returned. Normally, this is the current conditions (which is the default value) but under some circumstances, systems need to acccess this information as it would have been in the past. A typical example of this would be where code selection is constrained to the set of codes that were available when the patient was treated, not when the record is being edited. Note that which date is appropriate is a matter for implementation policy.


The requested language for display (see $expand.displayLanguage)


A property that the client wishes to be returned in the output. If no properties are specified, the server chooses what to return. The following properties are defined for all code systems: url, name, version (code system info) and code information: display, definition, designation, parent and child, and for designations, lang.X where X is a designation language code. Some of the properties are returned explicit in named parameters (when the names match), and the rest (except for lang.X) in the property parameter group

Out Parameters:
ИмяКардинальное множествоТипПривязкаПрофильДокументация

A display name for the code system


The version that these details are based on


The preferred display for this concept


Additional representations for this concept


The language this designation is defined for


A code that details how this designation would be used


The text value for this designation


One or more properties that contain additional information about the code, including status. For complex terminologies (e.g. SNOMED CT, LOINC, medications), these properties serve to decompose the code


Identifies the property returned

property.value0..1code | Coding | string | integer | boolean | dateTime | decimal

The value of the property returned


Human Readable representation of the property value (e.g. display for a code)


Nested Properties (mainly used for SNOMED CT decomposition, for relationship Groups)


Identifies the sub-property returned

property.subproperty.value1..1code | Coding | string | integer | boolean | dateTime | decimal

The value of the sub-property returned


Human Readable representation of the property value (e.g. display for a code)

Note that the $lookup operation is more than just a code system search - the server finds the concept, and gathers the return information from the underlying code system definitions.

Request: Looking up a code/system

GET [base]/CodeSystem/$lookup?system=

Request: Lookup using a Coding

POST [base]/CodeSystem/$lookup
[other headers]

<Parameters xmlns="">
    <name value="coding"/>
    <system value=""/>
    <code value="1963-8"/>

Response: When the request can be processed ok

HTTP/1.1 200 OK
[other headers]

  "resourceType" : "Parameters",
  "parameter" : [
    "name" : "name",
    "valueString" : "LOINC"
    "name" : "version",
    "valueString" : "2.48"
    "name" : "display",
    "valueString" : "Bicarbonate [Moles/volume] in Serum"
    "name" : "abstract",
    "valueString" : "false"
      "name" : "designation",
    "part" : [
      "name" : "value",
      "valueString" : "Bicarbonate [Moles/volume] in Serum"

Response: An error - e.g. the requested code is not known

HTTP/1.1 400 Bad Request
[other headers]

  "resourceType": "OperationOutcome",
  "id": "exception",
  "text": {
    "status": "additional",
    "div": "<div xmlns=\"\">Code "ABC-23" not found</div>"
  "issue": [
      "severity": "error",
      "code": "not-found",
      "details": {
        "text": "Code "ABC-23" not found"


For more information about operations, including how they are invoked, see Operations.