Skip Navigation Bar
NLM logo

VSAC Support Center

FHIR Terminology Service for VSAC Resources



The FHIR Terminology Service for VSAC Resources is a RESTful 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.


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.
Documentation for implementing API Key authentication is available here: https://documentation.uts.nlm.nih.gov/rest/authentication.html.

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 FHIR version 3.1.0
Base URI: https://cts.nlm.nih.gov/fhir/r4/
Base URI for Testing: https://uat-cts.nlm.nih.gov/fhir/r4/
Contact us for permissions to use the User Acceptance Testing (UAT) server.
Base URI: https://cts.nlm.nih.gov/fhir/r3/
Capability Statement (public): JSON | XML
Capability Statement (UAT): JSON | XML
Capability Statement: JSON | XML
FHIR Code Systems FHIR Code Systems


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/r4/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/r4/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/r4/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/r4/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/r4/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/r4/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/r4/CodeSystem/$lookup?system=http://loinc.org&code=1963-8 Retrieve details of code from code system.
  $lookup https://cts.nlm.nih.gov/fhir/r4/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/r4/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/r4/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/r4/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/r4/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/r4/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/r4/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/r4/CodeSystem/$lookup?system=http://www.nlm.nih.gov/research/umls/rxnorm&code=1000000 Retrieve details of a specified code from RxNorm.

Last Reviewed: September 14, 2021