FHIRfly
Dashboard

SNOMED CT Search API

Search SNOMED CT IPS (International Patient Set) clinical concepts by text, category, or semantic tag.

Endpoint

GET /v1/snomed/search

Quick Start

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

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

// Search for heart-related conditions
const results = await client.snomed.search({
  q: "heart failure",
});

console.log(`Found ${results.count} concepts`);
for (const concept of results.results) {
  console.log(`${concept.concept_id}: ${concept.preferred_term}`);
}

Parameters

Text Search

Parameter Description Example
q Text search across preferred terms, FSN, and synonyms q=heart failure

Filters

Parameter Type Description Example
ips_category string Filter by IPS category condition
semantic_tag string Filter by semantic tag disorder
active boolean Filter by active status (default: true) true

Pagination

Parameter Default Max Description
limit 100 500 Maximum results to return
skip 0 — Offset for pagination

At least one of q, ips_category, or semantic_tag is required.

Example Response

{
  "count": 12,
  "results": [
    {
      "concept_id": "84114007",
      "active": true,
      "fsn": "Heart failure (disorder)",
      "preferred_term": "Heart failure",
      "synonyms": ["Cardiac failure", "Heart failure, NOS"],
      "ips_category": "condition",
      "semantic_tag": "disorder"
    },
    {
      "concept_id": "42343007",
      "active": true,
      "fsn": "Congestive heart failure (disorder)",
      "preferred_term": "Congestive heart failure",
      "synonyms": ["CHF", "Congestive cardiac failure"],
      "ips_category": "condition",
      "semantic_tag": "disorder"
    }
  ],
  "meta": {
    "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."
    }
  }
}

Use Cases

Browse Conditions

Node.js
const conditions = await client.snomed.search({
  ips_category: "condition",
  limit: 20,
});

Find Substances for Allergy Lists

Node.js
const substances = await client.snomed.search({
  q: "penicillin",
  ips_category: "substance",
});

Search Procedures

Node.js
const procedures = await client.snomed.search({
  ips_category: "procedure",
  q: "bypass",
});

Paginate Through Results

Node.js
// Get page 1
const page1 = await client.snomed.search({
  ips_category: "condition",
  limit: 10,
  skip: 0,
});

// Get page 2
const page2 = await client.snomed.search({
  ips_category: "condition",
  limit: 10,
  skip: 10,
});

IPS Categories

Use the ips_category filter with any of these values:

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
event Events
environment Environmental/geographic
social Social context, occupations

You can also retrieve this list programmatically via GET /v1/snomed/categories.

Response Format Notes

SNOMED search does not use response shapes or facets. All results return the same full concept structure. Unlike other search APIs, SNOMED search uses count and results instead of total, items, and has_more.

Required Scope

snomed.search

See Also