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

SNOMED CT Search API

Endpoint

Quick Start

Parameters

Text Search

Filters

Pagination

Example Response

Use Cases

Browse Conditions

Find Substances for Allergy Lists

Search Procedures

Paginate Through Results

IPS Categories

Response Format Notes

Required Scope

See Also

Cookie Preferences