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.
URIs | Query Parameters | Sample Output
URIs with /ancestors or /descendants support the following use cases:
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.
The base URI is https://uts-ws.nlm.nih.gov/rest
| Sample URI | Description | Returned JSON Object classType |
|---|---|---|
| /content/current/source/SNOMEDCT_US/9468002/ancestors | Retrieves ancestors of a source-asserted identifier | SourceAtomCluster* |
| /content/current/source/SNOMEDCT_US/9468002/descendants | Retrieves descendants of a source-asserted identifier | SourceAtomCluster* |
Python example - Retrieve ancestors, descendants, parents, or children
Calls using codes from HL7V2.5 and HL7V3.0 return output with an “Atom” JSON Object classType.
| 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 |
| pageNumber | N | Whole number that specifies which page of results to fetch. | 1,2,3, etc | 1 | n/a |
| pageSize | N | Whole number that specifies the number of results to include per page. | 1,2,3, etc | 25 | n/a |
Sample output for https://uts-ws.nlm.nih.gov/rest/content/current/source/SNOMEDCT_US/9468002/descendants?apiKey=YOUR_APIKEY…
{
"pageSize" : 25,
"pageNumber" : 1,
"pageCount" : 2,
"result" : [{
"classType" : "SourceAtomCluster",
"ui" : "10934241000119100",
"suppressible" : false,
"obsolete" : false,
"rootSource" : "SNOMEDCT_US",
"atomCount" : 2,
"cVMemberCount" : 0,
"attributes" : "https://uts-ws.nlm.nih.gov/rest/content/2016AA/source/SNOMEDCT_US/10934241000119100/attributes",
"atoms" : "https://uts-ws.nlm.nih.gov/rest/content/2016AA/source/SNOMEDCT_US/10934241000119100/atoms",
"descendants" : "NONE",
"ancestors" : "https://uts-ws.nlm.nih.gov/rest/content/2016AA/source/SNOMEDCT_US/10934241000119100/ancestors",
"parents" : "https://uts-ws.nlm.nih.gov/rest/content/2016AA/source/SNOMEDCT_US/10934241000119100/parents",
"children" : "NONE",
"relations" : "https://uts-ws.nlm.nih.gov/rest/content/2016AA/source/SNOMEDCT_US/10934241000119100/relations",
"definitions" : "NONE",
"concepts" : "https://uts-ws.nlm.nih.gov/rest/search/2016AA?string=10934241000119100&sabs=SNOMEDCT_US&searchType=exact&inputType=sourceUi",
"defaultPreferredAtom" : "https://uts-ws.nlm.nih.gov/rest/content/2016AA/source/SNOMEDCT_US/10934241000119100/atoms/preferred",
"name" : "Closed fracture of pisiform bone of left wrist"
}, {
"classType" : "SourceAtomCluster",
"ui" : "10934281000119105",
"suppressible" : false,
"obsolete" : false,
"rootSource" : "SNOMEDCT_US",
"atomCount" : 3,
"cVMemberCount" : 0,
"attributes" : "https://uts-ws.nlm.nih.gov/rest/content/2016AA/source/SNOMEDCT_US/10934281000119105/attributes",
"atoms" : "https://uts-ws.nlm.nih.gov/rest/content/2016AA/source/SNOMEDCT_US/10934281000119105/atoms",
"descendants" : "NONE",
"ancestors" : "https://uts-ws.nlm.nih.gov/rest/content/2016AA/source/SNOMEDCT_US/10934281000119105/ancestors",
"parents" : "https://uts-ws.nlm.nih.gov/rest/content/2016AA/source/SNOMEDCT_US/10934281000119105/parents",
"children" : "NONE",
"relations" : "https://uts-ws.nlm.nih.gov/rest/content/2016AA/source/SNOMEDCT_US/10934281000119105/relations",
"definitions" : "NONE",
"concepts" : "https://uts-ws.nlm.nih.gov/rest/search/2016AA?string=10934281000119105&sabs=SNOMEDCT_US&searchType=exact&inputType=sourceUi",
"defaultPreferredAtom" : "https://uts-ws.nlm.nih.gov/rest/content/2016AA/source/SNOMEDCT_US/10934281000119105/atoms/preferred",
"name" : "Closed fracture of capitate bone of right wrist"
}, {
"classType" : "SourceAtomCluster",
"ui" : "10934321000119100",
"suppressible" : false,
"obsolete" : false,
"rootSource" : "SNOMEDCT_US",
"atomCount" : 3,
"cVMemberCount" : 0,
"attributes" : "https://uts-ws.nlm.nih.gov/rest/content/2016AA/source/SNOMEDCT_US/10934321000119100/attributes",
"atoms" : "https://uts-ws.nlm.nih.gov/rest/content/2016AA/source/SNOMEDCT_US/10934321000119100/atoms",
"descendants" : "NONE",
"ancestors" : "https://uts-ws.nlm.nih.gov/rest/content/2016AA/source/SNOMEDCT_US/10934321000119100/ancestors",
"parents" : "https://uts-ws.nlm.nih.gov/rest/content/2016AA/source/SNOMEDCT_US/10934321000119100/parents",
"children" : "NONE",
"relations" : "https://uts-ws.nlm.nih.gov/rest/content/2016AA/source/SNOMEDCT_US/10934321000119100/relations",
"definitions" : "NONE",
"concepts" : "https://uts-ws.nlm.nih.gov/rest/search/2016AA?string=10934321000119100&sabs=SNOMEDCT_US&searchType=exact&inputType=sourceUi",
"defaultPreferredAtom" : "https://uts-ws.nlm.nih.gov/rest/content/2016AA/source/SNOMEDCT_US/10934321000119100/atoms/preferred",
"name" : "Closed fracture of capitate bone of left wrist"
},
...
]
}