Skip to main content
U.S. flag

An official website of the United States government

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

VSAC Support Center

VSAC Support Center Home

FHIR Terminology Service for VSAC Resources


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.

Notice

  • VSAC value set identifiers must be specified as a VSAC value set OID. Value set names are not unique in VSAC.
  • Using the VSAC FHIR API assumes your familiarity with the HL7 FHIR resources and the operations outlined in the Capability Statement.


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.
Accept:   application/fhir+json; fhirVersion=3.0


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 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 $lookup https://cts.nlm.nih.gov/fhir/CodeSystem/$lookup?system=http://loinc.org&code=1963-8 Retrieve details of code from code system.
  $lookup https://cts.nlm.nih.gov/fhir/CodeSystem/$lookup?system=http://loinc.org&code=1963-8&version=2.56 Retrieve details of code from code system version.
  $lookup https://cts.nlm.nih.gov/fhir/CodeSystem/$lookup?system=http://loinc.org&code=1963-8&date=20150501 Retrieve details of code from 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: March 29, 2024