The FHIR Terminology Service for VSAC Resources is a REST API service for accessing the VSAC value sets and supported code systems. This service requires a free Unified Medical Language System® Metathesaurus License, due to usage restrictions on some of the codes included in the value sets.
The VSAC FHIR API is subject to change as we update it according to the developing HL7 Quality Measure Implementation Guide (QMIG) specifications and CMS requirements. Please refer to our Capability Statement for full documentation of the VSAC FHIR API.
Authentication
Use basic authentication with your UMLS API Key. For
example, if you are using a platform such as Postman, choose:
Authorization Type = Basic Auth;
Username = ‘apikey’ or leave it blank;
Password = user’s actual UMLS API Key.
You can find your API Key in the My
Profile area after signing in to the
UMLS.
Additional Information
- Using the VSAC FHIR API assumes your familiarity with the HL7 FHIR Terminology Module resources and the operations outlined in the VSAC FHIR Capability Statement.
- VSAC value set identifiers must be specified as a VSAC value set object identifier (OID). Value set names are not unique in VSAC.
- Due to performance and resource size concerns, VSAC FHIR does not display hierarchy information for CodeSystem definitions. Additionally, VSAC FHIR displays the complete code list only if the total number of code system codes is less than 1200. If the number of codes exceeds 1200, VSAC FHIR returns just one example code. You can explore each code system's full hierarchy and complete code list in the Browse Code System functionality in the VSAC web browser.
- Mapping of Value Set Review Statuses between VSAC and FHIR
- VSAC Value Set Name, FHIR Value Set Name and FHIR Value Set Title
FHIR version 4.0.1
| Base URI: https://cts.nlm.nih.gov/fhir/ Base URI for Testing: https://uat-cts.nlm.nih.gov/fhir/ Contact us for permissions to use the User Acceptance Testing (UAT) server. |
| Capability Statement (public): JSON | XML Capability Statement (UAT): JSON | XML |
If you need to access the previous FHIR version 3.0, use the MIME-type parameter fhirVersion in your Accept header to indicate which version of the FHIR release you intend to use. If you do not specify a FHIR version in the Accept header, then the default FHIR 4.0.1 shall be used. Any other Accept fhirVersion value shall return an error.
Sample Queries
Study the Capability Statements above to discover all supported parameters.
| FHIR Resource | FHIR Operation | Examples | Use Case |
|---|---|---|---|
| ValueSet | https://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.11.20.9.46 | Retrieve FHIR compose statement (VSAC definition) for specified intensional (logically defined) value set. | |
| https://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.113.11.1090 | Retrieve the FHIR compose statement (VSAC definition) for specified extensional value set. | ||
| $expand | https://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.113.11.1090/$expand | Retrieve expansion for specified extensional value set. | |
| $expand | https://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.113.11.1090/$expand?filter=spine | Retrieve expansion of codes and descriptors matching filter=spine within specified extensional value set. | |
| $expand | https://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.11.20.9.46/$expand | Retrieve expansion for specified intensional (logically defined) value set. | |
| $validate-code | https://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.113.11.1090/$validate-code?system=http://hl7.org/fhir/sid/icd-10-cm&code=M45.0 | Validate that a coded value is in the set of codes allowed by specified value set. | |
| CodeSystem | https://cts.nlm.nih.gov/fhir/CodeSystem/CDCREC | Retrieve details of a code system. | |
| $lookup | https://cts.nlm.nih.gov/fhir/CodeSystem/$lookup?system=http://loinc.org&code=1963-8 | Retrieve details of a code from a code system. | |
| $lookup | https://cts.nlm.nih.gov/fhir/CodeSystem/$lookup?system=http://loinc.org&code=1963-8&version=2.56 | Retrieve details of a code from a code system version. | |
| $lookup | https://cts.nlm.nih.gov/fhir/CodeSystem/$lookup?system=http://loinc.org&code=1963-8&date=20150501 | Retrieve details of a code from a code system as of specified date. | |
| $subsumes | https://cts.nlm.nih.gov/fhir/CodeSystem/$subsumes?system=http://snomed.info/sct&codeA=29857009&codeB=10000006 | Test subsumption relationship between code A and code B. | |
| $subsumes | https://cts.nlm.nih.gov/fhir/CodeSystem/$subsumes?system=http://hl7.org/fhir/sid/icd-10-cm&version=2018&codeA=A01.01&codeB=A00-A09 | Test subsumption relationship between code A and code B, given a code system version. |
Special Cases with No UMLS Authentication Requirement
| FHIR Resource | FHIR Operation | Examples | Use Case |
|---|---|---|---|
| ValueSet | https://cts.nlm.nih.gov/fhir/ValueSet?usage=VSAC$covid | Retrieve the current list of COVID-19 value sets designated by authors in VSAC. More information. | |
| https://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113762.1.4.1114.13 | Retrieve FHIR compose statement (VSAC definition) for specified COVID-19 value set. | ||
| $expand | https://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113762.1.4.1114.13/$expand | Retrieve expansion for specified COVID-19 value set. | |
| CodeSystem | $lookup | https://cts.nlm.nih.gov/fhir/CodeSystem/$lookup?system=http://www.nlm.nih.gov/research/umls/rxnorm&code=1000000 | Retrieve details of a specified code from RxNorm. |
Last Reviewed: August 20, 2024