Skip to main content

​
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

ParameterTypeRequiredDescription
systemuriYes (type-level)FHIR code system URI
codecodeYesThe code to look up
versionstringNoVocabulary version
propertycodeNo (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

FieldDescription
systemEchoes the requested code system URI
nameCodeSystem name (OMOP Concepts)
versionVocabulary version used
codeThe looked-up code
displayPrimary concept name
designationSynonyms and alternate names (one entry per synonym)
propertyOMOP 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

HTTPIssue CodeCause
400invalidMissing code parameter, or missing system for type-level $lookup
403forbiddenRestricted vocabulary (CPT4)
404not-foundCode not found in the specified code system