> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omophub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FHIR CodeSystem/$lookup for OMOP concept details

> Look up OMOP concept details by code and system with FHIR $lookup - return display, designations, properties, and version info for any concept.

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

```bash theme={null}
# 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)

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

### POST with FHIR Parameters body

```bash theme={null}
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:

```bash theme={null}
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.

```json theme={null}
{
  "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](/api-reference/fhir-terminology/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.

```bash theme={null}
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:

```json theme={null}
{
  "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" }
      ]
    }
  ]
}
```

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

## 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                            |