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

SNOMED CT API

Overview

Endpoints

Single Lookup

Look up Diabetes mellitus

Concept ID Format

Batch Lookup

Look up multiple clinical concepts

IPS Categories

Reverse Mappings

Find codes that map to Diabetes mellitus

Mapping Types

Cross-Terminology Enrichment

License Notice

Required Scopes

See Also

Cookie Preferences