Searching the UMLS

URIs with /search support the following use cases:

Return a list of CUIs and their names when searching a human readable term.
Return a list of source-asserted identifiers (codes) and their names when searching a human readable term.
Map source-asserted identifiers to UMLS CUIs.

Note that ‘current’ in the URI can always be used to search against the latest UMLS publication.
You may use any valid UMLS release back to 2008AA in your URI if you would like to search against a particular version of the UMLS.
Each search request returns a single page of up to 200 results; pagination is no longer supported.

TRY SEARCHING USING OUR INTERACTIVE INTERFACE

URIs

The base URI is https://uts-ws.nlm.nih.gov/rest

Sample URI	Description	Returned JSON Object classType
/search/current?string=fracture of carpal bone	Retrieves CUIs for a search term - python example	searchResults
/search/current?string=fracture of carpal bone&searchType=exact	Uses ‘exact’ searching	searchResults
/search/current?string=fracture of carpal bone&sabs=SNOMEDCT_US&returnIdType=code	Returns SNOMEDCT concepts associated with a search term	searchResults
/search/current?string=9468002&inputType=sourceUi&searchType=exact&sabs=SNOMEDCT_US	Returns UMLS CUIs associated with a SNOMEDCT_US concept - python example	searchResults
/search/current?string=C0009044&sabs=SNOMEDCT_US&returnIdType=code	Returns SNOMED CT concepts associated with a UMLS CUI - python example	searchResults
/search/current?string=fever&semanticTypes=A2.2	Limits results using a semantic type tree number prefix	searchResults
/search/current?string=depression&semanticTypes=T047\|T046	Limits results to one or more semantic types by TUI	searchResults
/search/current?string=insulin&semanticTypes=Gene or Genome\|Amino Acid, Peptide, or Protein	Limits results using semantic type names	searchResults
/search/current?string=fracture&semanticGroups=Disorders	Limits results to a semantic group	searchResults

Query Parameters

Parameter name	Required? Y/N	Description	Valid Values	Default value	Usage Note
apiKey	Y	An API key is required for each call to the API. Visit your UTS profile to obtain your API key.	n/a	n/a	n/a
string	Y	A human readable term, such as ‘gestational diabetes’, or a code from a source vocabulary, such as 11687002 from SNOMEDCT_US.	Any term or code in the UMLS.	n/a	n/a
inputType	N	Specifies the data type you are using as your search parameter.	‘atom’, ‘code’,‘sourceConcept’,‘sourceDescriptor’,‘sourceUi’,‘tty’	‘atom’	Use ‘sourceUi’ if you aren’t sure if the identifier you’re providing is a code, source concept, or source descriptor. Using ‘tty’ is for advanced use cases and will extract codes from a specified vocabulary according to term type.
includeObsolete	N	Return content that is a result of matches on obsolete terms.	true or false	false	n/a
includeSuppressible	N	Return content that is a result of matches on suppressible terms.	true or false	false	n/a
returnIdType	N	Specifies the type of identifier you wish to retrieve.	‘aui’,‘concept’,‘code’,‘sourceConcept’,‘sourceDescriptor’, ‘sourceUi’	‘concept’	Use ‘code’,‘sourceConcept’, ‘sourceDescriptor’, or ‘sourceUi’ if you prefer source-asserted identifiers rather than CUIs in your search results.
sabs	N	Comma-separated list of source vocabularies to include in your search	Any root source abbreviation in the UMLS. See the “Abbreviation” column for a list of UMLS source vocabulary abbreviations.	All UMLS source vocabularies	Use a comma between each source abbreviation to specify more than one.
searchType	N	Type of search you wish to use.	‘exact’,‘words’,‘leftTruncation’, ‘rightTruncation’, ‘normalizedString’, ‘normalizedWords’	‘words’	Use ‘exact’ when using inputType = ‘code’, ‘sourceConcept’, ‘sourceDescriptor’, or ‘sourceUi’. More information…
semanticTypes	N	Restricts results to one or more semantic types.	Semantic type tree number prefixes such as ‘A2.2’, TUIs such as ‘T046’, or semantic type names such as ‘Disease or Syndrome’. Visit the Semantic Network Browser to browse the semantic type tree and view all semantic types, TUIs, and tree numbers.	All semantic types	Use pipes to separate tree number prefixes, TUIs, or semantic type names. More information…
semanticGroups	N	Restricts results to a semantic group.	Semantic group names such as ‘Disorders’. Use the second column in SemGroups.txt.	All semantic groups	More information…
partialSearch	N	Return partial matches for your query.	true or false	false	n/a
pageSize	N	Whole number that specifies the number of results to include.	200	200	Fixed value; pagination is not supported.

Expected Behaviors for the searchType Parameter

words: default searchType. Retrieves results where all words in the query appear in a particular name.
exact: retrieves only concepts that include a synonym that exactly matches the search term.
normalizedString: use with English language terms only. Removes lexical variations such as plural and upper case text and compares search terms to the Metathesaurus normalized string index to retrieve relevant concepts.
normalizedWords: use with English language terms only. Removes lexical variations such as plural and upper case text, and compares search terms to the Metathesaurus normalized word index to retrieve relevant concepts.
rightTruncation: retrieves concepts with synonyms that begin with the letters of the search term. For example, a right truncation search for “bronch” retrieves concepts that contain synonyms such as bronchitis, bronchiole, bronchial artery.
leftTruncation: retrieves concepts with synonyms that end with the letters of the search term. For example, a left truncation search for “itis” retrieves concepts that contain synonyms such as colitis, bronchitis, pancreatitis.

Expected Behaviors for the semanticTypes Parameter

Use semanticTypes to restrict search results to one or more semantic types.

Supported input formats:

Tree number prefixes: pipe-delimited semantic type tree number prefixes such as A2.2|B2.2.1.2
TUIs: pipe-delimited semantic type identifiers such as T047|T046
Semantic type names: pipe-delimited semantic type names such as Gene or Genome|Amino Acid, Peptide, or Protein

The API matches tree numbers by prefix. If you supply a tree number, the filter includes semantic types assigned to that tree number and all descendant semantic types beneath it in the Semantic Network. The API resolves TUIs by identifier and treats other pipe-delimited values as semantic type names.

Examples:

A2.2

Includes descendant semantic types under that tree number prefix, not just the exact tree node.

Browse this tree number and its descendants in the Semantic Network Browser.

Will return concepts with any of the following semantic types:

A2.2   Finding
|- A2.2.1   Laboratory or Test Result
`- A2.2.2   Sign or Symptom

Example: https://uts-ws.nlm.nih.gov/rest/search/current?string=fever&semanticTypes=A2.2&apiKey=YOUR_APIKEY

A2.2|B2.2.1.2

Combines both tree number prefixes and includes descendants under each branch.

Browse these tree number branches in the Semantic Network Browser.

Includes Finding, Laboratory or Test Result, and Sign or Symptom under A2.2.

Includes Disease or Syndrome and Pathologic Function under B2.2.1.2.

Example: https://uts-ws.nlm.nih.gov/rest/search/current?string=depression&semanticTypes=A2.2|B2.2.1.2&apiKey=YOUR_APIKEY

T047|T046

Behaves like Disease or Syndrome|Pathologic Function.

Example: https://uts-ws.nlm.nih.gov/rest/search/current?string=depression&semanticTypes=T047|T046&apiKey=YOUR_APIKEY

Gene or Genome|Amino Acid, Peptide, or Protein

Applies those semantic types by name.

Example: https://uts-ws.nlm.nih.gov/rest/search/current?string=insulin&semanticTypes=Gene or Genome|Amino Acid, Peptide, or Protein&apiKey=YOUR_APIKEY

For more information about semantic types, see the UMLS Semantic Network documentation and the UTS Semantic Network Browser.

Expected Behaviors for the semanticGroups Parameter

Use semanticGroups to restrict search results to a semantic group.

Supply a semantic group name. For example:

semanticGroups=Disorders

For more information about semantic groups, see the UMLS Semantic Network semantic groups documentation.

Sample Output

The default search parameters will return CUIs and their names. The first example below shows a concept search filtered by semanticTypes. If you ask for codes, sourceConcept, or sourceDescriptor as your returnIdType, you will get back source-asserted identifiers instead of CUIs.

Sample output for https://uts-ws.nlm.nih.gov/rest/search/current?string=fracture of carpal bone&pageSize=25&apiKey=YOUR_APIKEY…

{
  "pageSize": 25,
  "pageNumber": 1,
  "result": {
    "classType": "searchResults",
    "results": [
      {
        "ui": "C0016644",
        "rootSource": "MTH",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C0016644",
        "name": "Fracture of carpal bone",
        "semanticTypes": [
          "Injury or Poisoning"
        ]
      },
      {
        "ui": "C0009044",
        "rootSource": "MTH",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C0009044",
        "name": "Closed fracture of carpal bone",
        "semanticTypes": [
          "Injury or Poisoning"
        ]
      },
      {
        "ui": "C0159765",
        "rootSource": "MTH",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C0159765",
        "name": "Open fracture of carpal bone, unspecified",
        "semanticTypes": [
          "Injury or Poisoning"
        ]
      },
      {
        "ui": "C3669927",
        "rootSource": "SNOMEDCT_VET",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C3669927",
        "name": "Fracture of accessory carpal bone of equine limb",
        "semanticTypes": [
          "Injury or Poisoning"
        ]
      },
      {
        "ui": "C0840635",
        "rootSource": "ICD10AM",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C0840635",
        "name": "Fracture of carpal bone, unspecified",
        "semanticTypes": [
          "Injury or Poisoning"
        ]
      },
      {
        "ui": "C3670076",
        "rootSource": "SNOMEDCT_VET",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C3670076",
        "name": "Fracture of third carpal bone",
        "semanticTypes": [
          "Injury or Poisoning"
        ]
      },
      {
        "ui": "C3669570",
        "rootSource": "SNOMEDCT_VET",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C3669570",
        "name": "Fracture of fourth carpal bone of equine limb",
        "semanticTypes": [
          "Injury or Poisoning"
        ]
      },
      {
        "ui": "C3669936",
        "rootSource": "SNOMEDCT_VET",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C3669936",
        "name": "Fracture of ulnar carpal bone of equine limb",
        "semanticTypes": [
          "Injury or Poisoning"
        ]
      },
      {
        "ui": "C3669572",
        "rootSource": "SNOMEDCT_VET",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C3669572",
        "name": "Fracture of radial carpal bone of equine limb",
        "semanticTypes": [
          "Injury or Poisoning"
        ]
      },
      {
        "ui": "C3669573",
        "rootSource": "SNOMEDCT_VET",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C3669573",
        "name": "Fracture of intermediate carpal bone of equine limb",
        "semanticTypes": [
          "Injury or Poisoning"
        ]
      },
      {
        "ui": "C0478305",
        "rootSource": "ICD10",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C0478305",
        "name": "Fracture of other carpal bone(s)",
        "semanticTypes": [
          "Injury or Poisoning"
        ]
      },
      {
        "ui": "C2213932",
        "rootSource": "MEDCIN",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C2213932",
        "name": "malunion of fracture of carpal bone",
        "semanticTypes": [
          "Pathologic Function"
        ]
      },
      {
        "ui": "C2214345",
        "rootSource": "MEDCIN",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C2214345",
        "name": "nonunion of fracture of carpal bone",
        "semanticTypes": [
          "Pathologic Function"
        ]
      },
      {
        "ui": "C5405554",
        "rootSource": "CPT",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C5405554",
        "name": "Open reduction of fracture of carpal bone (other than carpal scaphoid bone)",
        "semanticTypes": [
          "Therapeutic or Preventive Procedure"
        ]
      },
      {
        "ui": "C3669940",
        "rootSource": "SNOMEDCT_VET",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C3669940",
        "name": "Slab fracture of radial carpal bone of equine limb",
        "semanticTypes": [
          "Injury or Poisoning"
        ]
      },
      {
        "ui": "C3669935",
        "rootSource": "SNOMEDCT_VET",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C3669935",
        "name": "Slab fracture of third carpal bone of equine limb",
        "semanticTypes": [
          "Injury or Poisoning"
        ]
      },
      {
        "ui": "C3669937",
        "rootSource": "SNOMEDCT_VET",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C3669937",
        "name": "Slab fracture of intermediate carpal bone of equine limb",
        "semanticTypes": [
          "Injury or Poisoning"
        ]
      },
      {
        "ui": "C3669938",
        "rootSource": "SNOMEDCT_VET",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C3669938",
        "name": "Chip fracture of intermediate carpal bone of equine limb",
        "semanticTypes": [
          "Injury or Poisoning"
        ]
      },
      {
        "ui": "C3669934",
        "rootSource": "SNOMEDCT_VET",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C3669934",
        "name": "Chip fracture of third carpal bone of equine limb",
        "semanticTypes": [
          "Injury or Poisoning"
        ]
      },
      {
        "ui": "C3669939",
        "rootSource": "SNOMEDCT_VET",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C3669939",
        "name": "Chip fracture of radial carpal bone of equine limb",
        "semanticTypes": [
          "Injury or Poisoning"
        ]
      },
      {
        "ui": "C0187429",
        "rootSource": "MTH",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C0187429",
        "name": "Open treatment of carpal bone fracture (other than carpal scaphoid [navicular]), each bone",
        "semanticTypes": [
          "Therapeutic or Preventive Procedure"
        ]
      },
      {
        "ui": "C3701495",
        "rootSource": "CPT",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C3701495",
        "name": "Closed treatment of carpal bone fracture (excluding carpal scaphoid [navicular])",
        "semanticTypes": [
          "Therapeutic or Preventive Procedure"
        ]
      },
      {
        "ui": "C3163901",
        "rootSource": "SNOMEDCT_US",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C3163901",
        "name": "Debridement of open fracture of carpal bone",
        "semanticTypes": [
          "Therapeutic or Preventive Procedure"
        ]
      },
      {
        "ui": "C2733517",
        "rootSource": "SNOMEDCT_US",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C2733517",
        "name": "Open reduction of fracture of carpal bone",
        "semanticTypes": [
          "Therapeutic or Preventive Procedure"
        ]
      },
      {
        "ui": "C0272654",
        "rootSource": "SNOMEDCT_US",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2025AB/CUI/C0272654",
        "name": "Fracture of scaphoid bone",
        "semanticTypes": [
          "Injury or Poisoning"
        ]
      }
    ],
    "recCount": 170
  }
}

Specifying returnIdType = ‘code’,‘sourceConcept’,or ‘sourceDescriptor’ will result in output as follows:

Sample output for https://uts-ws.nlm.nih.gov/rest/search/current?string=fracture of carpal bone&returnIdType=sourceConcept&apiKey=YOUR_APIKEY…

{

    "pageSize": 200,
    "result":

{

    "classType": "searchResults",
    "results": 

[

{

    "ui": "9468002",
    "rootSource": "SNOMEDCT_US",
    "uri": "https://uts-ws.nlm.nih.gov/rest/content/2015AA/source/SNOMEDCT_US/9468002",
    "name": "Closed fracture carpal bone"

},
{

    "ui": "C34488",
    "rootSource": "NCI",
    "uri": "https://uts-ws.nlm.nih.gov/rest/content/2015AA/source/NCI/C34488",
    "name": "Closed Fracture of Carpal Bone"

},
{

    "ui": "34696",
    "rootSource": "MEDCIN",
    "uri": "https://uts-ws.nlm.nih.gov/rest/content/2015AA/source/MEDCIN/34696",
    "name": "closed fracture of carpal bone"

},
...
        ]
    }

}

We welcome your feedback on our customer service form. Please use "UMLS REST API feedback" in your subject line.

Check out the Postman sample collection to help you get started using the UMLS REST API.

API Terms of Service

UMLS API Technical Documentation