FHIR CodeSystem/$lookup for OMOP concept details

const options = {method: 'GET'};

fetch('https://fhir.omophub.com/fhir/{version}/CodeSystem/$lookup', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "system", "valueUri": "http://snomed.info/sct" },
    { "name": "name", "valueString": "OMOP Concepts" },
    { "name": "version", "valueString": "latest" },
    { "name": "code", "valueCode": "44054006" },
    { "name": "display", "valueString": "Type 2 diabetes mellitus" },
    {
      "name": "designation",
      "part": [
        { "name": "language", "valueCode": "en" },
        { "name": "value", "valueString": "Diabetes mellitus type 2" }
      ]
    },
    {
      "name": "designation",
      "part": [
        { "name": "language", "valueCode": "en" },
        { "name": "value", "valueString": "Type II diabetes mellitus" }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "concept-id" },
        { "name": "value", "valueInteger": 201826 }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "source-concept-code" },
        {
          "name": "value",
          "valueCoding": {
            "system": "http://snomed.info/sct",
            "code": "44054006"
          }
        }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "domain-id" },
        { "name": "value", "valueCode": "Condition" }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "vocabulary-id" },
        { "name": "value", "valueCode": "SNOMED" }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "concept-class-id" },
        { "name": "value", "valueCode": "Disorder" }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "standard-concept" },
        { "name": "value", "valueCode": "S" }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "inactive" },
        { "name": "value", "valueBoolean": false }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "valid-start-date" },
        { "name": "value", "valueDate": "2002-01-31" }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "valid-end-date" },
        { "name": "value", "valueDate": "2099-12-31" }
      ]
    }
  ]
}

const options = {method: 'GET'};

fetch('https://fhir.omophub.com/fhir/{version}/CodeSystem/$lookup', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "system", "valueUri": "http://snomed.info/sct" },
    { "name": "name", "valueString": "OMOP Concepts" },
    { "name": "version", "valueString": "latest" },
    { "name": "code", "valueCode": "44054006" },
    { "name": "display", "valueString": "Type 2 diabetes mellitus" },
    {
      "name": "designation",
      "part": [
        { "name": "language", "valueCode": "en" },
        { "name": "value", "valueString": "Diabetes mellitus type 2" }
      ]
    },
    {
      "name": "designation",
      "part": [
        { "name": "language", "valueCode": "en" },
        { "name": "value", "valueString": "Type II diabetes mellitus" }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "concept-id" },
        { "name": "value", "valueInteger": 201826 }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "source-concept-code" },
        {
          "name": "value",
          "valueCoding": {
            "system": "http://snomed.info/sct",
            "code": "44054006"
          }
        }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "domain-id" },
        { "name": "value", "valueCode": "Condition" }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "vocabulary-id" },
        { "name": "value", "valueCode": "SNOMED" }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "concept-class-id" },
        { "name": "value", "valueCode": "Disorder" }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "standard-concept" },
        { "name": "value", "valueCode": "S" }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "inactive" },
        { "name": "value", "valueBoolean": false }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "valid-start-date" },
        { "name": "value", "valueDate": "2002-01-31" }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "valid-end-date" },
        { "name": "value", "valueDate": "2099-12-31" }
      ]
    }
  ]
}

Overview

Returns detailed information about a concept from a code system. This is the most commonly used FHIR terminology operation. Supports both GET (query parameters) and POST (FHIR Parameters body), and both type-level (by system URI) and instance-level (by CodeSystem resource ID).

Contract Parameters

string

default:"r4"

string

OMOP vocabulary release; defaults to the active release.

string

Header alternative to vocab_release; the header takes precedence.

FHIR wire version (r4, r4b, r5, or r6).

string

Code-system URI; required for the type-level operation.

string

required

Code to look up.

string

Vocabulary release selector.

array

Repeatable property code; defaults to all properties.

Request

Type-level (by system URI)

# By vocabulary-specific code (ETL developers)
curl "https://fhir.omophub.com/fhir/r4/CodeSystem/\$lookup?\
system=http://snomed.info/sct&code=44054006" \
  -H "Authorization: Bearer YOUR_API_KEY"

# By OMOP concept_id (FHIR-compatible)
curl "https://fhir.omophub.com/fhir/r4/CodeSystem/\$lookup?\
system=https://fhir-terminology.ohdsi.org&code=201826" \
  -H "Authorization: Bearer YOUR_API_KEY"

Instance-level (by CodeSystem ID)

curl "https://fhir.omophub.com/fhir/r4/CodeSystem/omop-v20260227/\$lookup?\
code=201826" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST with FHIR Parameters body

curl -X POST "https://fhir.omophub.com/fhir/r4/CodeSystem/\$lookup" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Parameters",
    "parameter": [
      { "name": "system", "valueUri": "http://snomed.info/sct" },
      { "name": "code", "valueCode": "44054006" }
    ]
  }'

With property filter

Request only specific properties to reduce response size:

curl "https://fhir.omophub.com/fhir/r4/CodeSystem/\$lookup?\
system=http://snomed.info/sct&code=44054006&\
property=concept-id&property=domain-id&property=standard-concept" \
  -H "Authorization: Bearer YOUR_API_KEY"

Parameters

Parameter	Type	Required	Description
`system`	uri	Yes (type-level)	FHIR code system URI
`code`	code	Yes	The code to look up
`version`	string	No	Vocabulary version
`property`	code	No (repeatable)	Which properties to return (default: all)

Response

The response echoes the requested system and code, includes display and any known designation entries (synonyms), then lists the OMOP properties.

Response Fields

string

Always Parameters.

array

FHIR output parameters.

string

Parameter name: system, name, version, code, display, designation, or property.

string | null

URI-valued parameter.

string | null

String-valued parameter.

string | null

Code-valued parameter.

array

Designation or property parts.

string

Part name.

string | null

Code-valued part.

string | null

String-valued part.

integer | null

Integer-valued part.

boolean | null

Boolean-valued part.

string | null

Date-valued part.

object | null

Coding-valued part with system, code, and optional display.

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "system", "valueUri": "http://snomed.info/sct" },
    { "name": "name", "valueString": "OMOP Concepts" },
    { "name": "version", "valueString": "latest" },
    { "name": "code", "valueCode": "44054006" },
    { "name": "display", "valueString": "Type 2 diabetes mellitus" },
    {
      "name": "designation",
      "part": [
        { "name": "language", "valueCode": "en" },
        { "name": "value", "valueString": "Diabetes mellitus type 2" }
      ]
    },
    {
      "name": "designation",
      "part": [
        { "name": "language", "valueCode": "en" },
        { "name": "value", "valueString": "Type II diabetes mellitus" }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "concept-id" },
        { "name": "value", "valueInteger": 201826 }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "source-concept-code" },
        {
          "name": "value",
          "valueCoding": {
            "system": "http://snomed.info/sct",
            "code": "44054006"
          }
        }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "domain-id" },
        { "name": "value", "valueCode": "Condition" }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "vocabulary-id" },
        { "name": "value", "valueCode": "SNOMED" }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "concept-class-id" },
        { "name": "value", "valueCode": "Disorder" }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "standard-concept" },
        { "name": "value", "valueCode": "S" }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "inactive" },
        { "name": "value", "valueBoolean": false }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "valid-start-date" },
        { "name": "value", "valueDate": "2002-01-31" }
      ]
    },
    {
      "name": "property",
      "part": [
        { "name": "code", "valueCode": "valid-end-date" },
        { "name": "value", "valueDate": "2099-12-31" }
      ]
    }
  ]
}

Response fields

Field	Description
`system`	Echoes the requested code system URI
`name`	CodeSystem name (`OMOP Concepts`)
`version`	Vocabulary version used
`code`	The looked-up code
`display`	Primary concept name
`designation`	Synonyms and alternate names (one entry per synonym)
`property`	OMOP properties (see overview for the full list)

Phoebe Concept Recommendations (OMOPHub-Exclusive)

Request property=recommended to include Phoebe-recommended related concepts. These are clinically relevant concepts associated with the looked-up code - a feature unique to OMOPHub.

curl "https://fhir.omophub.com/fhir/r4/CodeSystem/\$lookup?\
system=http://snomed.info/sct&code=44054006&property=recommended" \
  -H "Authorization: Bearer YOUR_API_KEY"

Each recommendation appears as a property entry with a valueCoding and a subproperty describing the relationship:

{
  "name": "property",
  "part": [
    { "name": "code", "valueCode": "recommended" },
    {
      "name": "value",
      "valueCoding": {
        "system": "http://snomed.info/sct",
        "code": "80394007",
        "display": "Hyperglycemia"
      }
    },
    {
      "name": "subproperty",
      "part": [
        { "name": "code", "valueCode": "relationship" },
        { "name": "value", "valueString": "Has finding" }
      ]
    }
  ]
}

Recommendations are only returned when explicitly requested via property=recommended. Standard lookups without this property have no performance impact.

Errors

HTTP	Issue Code	Cause
400	`invalid`	Missing `code` parameter, or missing `system` for type-level `$lookup`
404	`not-found`	Code not found in the specified code system

​Overview

​Contract Parameters

​Request

​Type-level (by system URI)

​Instance-level (by CodeSystem ID)

​POST with FHIR Parameters body

​With property filter

​Parameters

​Response

​Response Fields

​Response fields

​Phoebe Concept Recommendations (OMOPHub-Exclusive)

​Errors

Overview

Contract Parameters

Request

Type-level (by system URI)

Instance-level (by CodeSystem ID)

POST with FHIR Parameters body

With property filter

Parameters

Response

Response Fields

Response fields

Phoebe Concept Recommendations (OMOPHub-Exclusive)

Errors