FHIRfly
Dashboard

SNOMED CT API

Look up SNOMED CT clinical concepts from the IPS (International Patient Set) free set.

Overview

SNOMED CT is the world's most comprehensive clinical terminology. FHIRfly provides access to the IPS Free Set — approximately 12,000 curated concepts used in International Patient Summary implementations, licensed under CC BY 4.0.

Unlike other FHIRfly APIs, SNOMED does not use response shapes (compact/standard/full). All lookups return a single consistent format.

Endpoints

Method Path Description
GET /v1/snomed/:concept_id Single concept lookup
POST /v1/snomed/_batch Batch lookup (up to 100)
GET /v1/snomed/search Search IPS concepts
GET /v1/snomed/categories List IPS categories
GET /v1/snomed/:concept_id/mappings Reverse mappings from other terminologies

Single Lookup

Look up Diabetes mellitus

Request
Node.js
import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

const result = await client.snomed.lookup("73211009");
console.log(result.data);
Response
JSON
{
  "data": {
    "concept_id": "73211009",
    "active": true,
    "fsn": "Diabetes mellitus (disorder)",
    "preferred_term": "Diabetes mellitus",
    "synonyms": [
      "DM - Diabetes mellitus",
      "Diabetes mellitus, NOS"
    ],
    "ips_category": "condition",
    "semantic_tag": "disorder"
  },
  "meta": {
    "source": {
      "name": "SNOMED CT IPS Free Set",
      "url": "https://www.snomed.org/our-standards/ips-terminology",
      "version": "IPS 1.1.0"
    },
    "legal": {
      "license": "CC BY 4.0",
      "attribution_required": true,
      "source_name": "SNOMED CT IPS Free Set",
      "citation": "SNOMED CT IPS Free Set. SNOMED International. Licensed under CC BY 4.0."
    }
  }
}

Concept ID Format

SNOMED concept IDs are numeric strings (digits only). Non-numeric values return a 400 error.

Input Valid Description
73211009 Yes Diabetes mellitus
84114007 Yes Heart failure
E11.9 No ICD-10 format — not a SNOMED ID
abc No Non-numeric

Batch Lookup

Look up multiple SNOMED concepts in a single request (up to 100):

Look up multiple clinical concepts

Request
Node.js
import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

const result = await client.snomed.lookupMany(["73211009","84114007","invalid"]);
console.log(result.data.results);
Response
JSON
{
  "count": 3,
  "results": [
    {
      "input": "73211009",
      "concept_id": "73211009",
      "status": "ok",
      "data": {
        "concept_id": "73211009",
        "preferred_term": "Diabetes mellitus",
        "ips_category": "condition"
      }
    },
    {
      "input": "84114007",
      "concept_id": "84114007",
      "status": "ok",
      "data": {
        "concept_id": "84114007",
        "preferred_term": "Heart failure",
        "ips_category": "condition"
      }
    },
    {
      "input": "invalid",
      "concept_id": "invalid",
      "status": "invalid",
      "error": "Invalid SNOMED concept ID format (must be numeric)"
    }
  ],
  "meta": {
    "legal": {
      "license": "CC BY 4.0",
      "attribution_required": true,
      "source_name": "SNOMED CT IPS Free Set"
    }
  }
}

IPS Categories

The IPS organizes concepts into 15 clinical categories. Use GET /v1/snomed/categories to list them:

Category Description
substance Substances (for allergies, medications)
product Medicinal products
condition Disorders, clinical findings
finding Clinical findings
procedure Procedures, therapies
body_structure Body structures, anatomical sites
organism Organisms (allergens, pathogens)
qualifier Qualifier values, attributes
device Medical devices
observable Observable entities (lab results)
specimen Specimen types
situation Situational concepts (e.g., "no known allergies")
event Events
environment Environmental/geographic
social Social context, occupations

Reverse Mappings

Find what codes from other terminologies (ICD-10, RxNorm, NDC) map to a SNOMED concept:

Find codes that map to Diabetes mellitus

Request
Node.js
import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

const result = await client.snomed.lookup("73211009/mappings");
console.log(result.data);
Response
JSON
{
  "data": {
    "snomed_code": "73211009",
    "snomed_display": "Diabetes mellitus",
    "mappings": [
      {
        "source_system": "icd10_cm",
        "source_code": "E11.9",
        "map_type": "narrower",
        "mapping_source": "snomed-extended-map"
      },
      {
        "source_system": "rxnorm",
        "source_code": "173",
        "map_type": "related",
        "mapping_source": "umls-rxnrel"
      }
    ]
  },
  "meta": {
    "legal": {
      "license": "CC BY 4.0",
      "attribution_required": true
    }
  }
}

Mapping Types

Type Description
equivalent Direct semantic equivalence
broader SNOMED concept is broader than the source
narrower SNOMED concept is narrower than the source
related Related but not equivalent

Cross-Terminology Enrichment

When SNOMED mappings exist, they appear automatically in other API responses. For example, looking up ICD-10 code E11.9 with shape=standard includes a snomed array:

{
  "data": {
    "code": "E119",
    "display": "Type 2 diabetes mellitus without complications",
    "snomed": [
      {
        "concept_id": "44054006",
        "display": "Diabetes mellitus type 2",
        "map_type": "equivalent",
        "map_source": "snomed-extended-map"
      }
    ]
  }
}

This enrichment is available on:

  • ICD-10 (CM only) — standard and full shapes
  • RxNorm — standard and full shapes
  • NDC — standard and full shapes (derived via RxNorm)

License Notice

SNOMED CT IPS Free Set data requires attribution under the CC BY 4.0 license. The meta.legal field in every response provides the required citation text.

Required Scopes

  • snomed.read — Single lookup, batch lookup, categories, and reverse mappings
  • snomed.search — Search endpoint

See Also