FHIR CodeSystem/$lookup for OMOP concept details

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).

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.

{
  "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

​Request

​Type-level (by system URI)

​Instance-level (by CodeSystem ID)

​POST with FHIR Parameters body

​With property filter

​Parameters

​Response

​Response fields

​Phoebe Concept Recommendations (OMOPHub-Exclusive)

​Errors

Overview

Request

Type-level (by system URI)

Instance-level (by CodeSystem ID)

POST with FHIR Parameters body

With property filter

Parameters

Response

Response fields

Phoebe Concept Recommendations (OMOPHub-Exclusive)

Errors