Skip Navigation Bar
NLM logo

VSAC API Resources

UMLS License Requirement

The VSAC APIs require a UMLS account. If you do not have a UMLS account, you may apply for a license on the UMLS Terminology Services (UTS) website.

Terms of Service

In order to avoid overloading our servers, NLM requires that users send no more than 20 requests per second per IP address. Requests that exceed this limit may not be serviced, and service will not be restored until the request rate falls beneath the limit. To limit the number of requests that you send to the APIs, NLM recommends caching results for a 12-24 hour period. This policy is in place to ensure that the service remains available and accessible to all users. If you have a specific use case that requires you to send a large number of requests to one of our APIs, and thus exceed the request rate limit outlined in this policy, please contact us. NLM staff will evaluate your request and determine if an exception may be granted. We invite you to develop computer and mobile applications using National Library of Medicine (NLM) resources. We request that any application that makes use of NLM data include the following statement: "This product uses publicly available data from the U.S. National Library of Medicine (NLM), National Institutes of Health, Department of Health and Human Services; NLM is not responsible for the product and does not endorse or recommend this or any other product."   Developers may not use the NLM name and/or logo in conjunction with their applications.

DISCLAIMER: It is not the intention of NLM to provide specific medical advice, but rather to provide users with information to better understand their health and their medications. NLM urges you to consult with a qualified physician for medical advice.

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.

The FHIR Terminology Service for VSAC Resources requires a UMLS account

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 UTS My Profile area after signing in. If the API Key field in your UTS profile is blank, click Edit Profile, select the Generate New API Key checkbox, then scroll down and click Save Profile. Your new API Key is now available for use. An API Key remains active as long as the associated UTS account is active. Documentation for implementing API Key authentication is available here: https://documentation.uts.nlm.nih.gov/rest/authentication.html.



VSAC SVS API

The VSAC SVS API is based on the IHE SVS Technical Framework, section 2.2.21 Sharing Value Set Integration Profile (SVS), and the IHE SVS XML Schema

Authentication URL https://vsac.nlm.nih.gov/vsac/ws

Content (SVS API) URL https://vsac.nlm.nih.gov/vsac/svs

Two Available VSAC SVS API Content Requests

  • RetrieveValueSet
    Use this request to retrieve only the value set concept list. This request does not retrieve value set metadata content.
  • RetrieveMultipleValueSets
    Use this request to retrieve value set metadata content as well as the value set concept list.
Utility API URL https://vsac.nlm.nih.gov/vsac/

The VSAC SVS API authentication service requires a UMLS account for the two-step authentication described below. Authentication allows you to retrieve a ticket granting ticket (TGT) that you will re-use to obtain each single-use service ticket (ST) for each GET request you make to the VSAC SVS API. Each service ticket is good for 5 minutes and expires after each GET request.

Use your UMLS API Key for authentication. You can find your API Key in the UTS My Profile area after signing in. If the API Key field in your UTS profile is blank, click Edit Profile, select the Generate new API Key checkbox, then scroll down and click Save Profile. Your new API Key is now available for use. An API Key remains active as long as the associated UTS account is active. Documentation for implementing API Key authentication is available here: https://documentation.uts.nlm.nih.gov/rest/authentication.html. Use of username and password with any API that requires UTS authentication is now deprecated.

Basic URL    https://vsac.nlm.nih.gov/vsac/ws
Request Method Path Description
POST /Ticket Step 1: Retrieve a Ticket Granting Ticket (TGT), good for 8 hours.
Put apikey={apikey} in the POST request body.
POST /Ticket/{TGT} Step 2: Use your TGT to obtain a single-use service ticket (ST), good for 5 minutes, expires after each GET request.
Put service=http://umlsks.nlm.nih.gov in the POST request body.

Endpoints to search and retrieve VSAC content

Use your service tickets to make GET requests as specified below.

Basic URL    https://vsac.nlm.nih.gov/vsac/svs
Request Method Path

Click to view use cases, sample calls and output

Description Related Utility Calls

Click to view use cases, sample calls and output

GET /RetrieveMultipleValueSets?id={oid}&ticket={ST} Retrieve Most Recent Value Set Expansions: includes value set metadata and concept list.
GET /RetrieveValueSet?id={oid}&ticket={ST} Retrieve Most Recent Value Set Expansions: includes only value set concept list, no metadata.
GET /RetrieveMultipleValueSets?id={oid}&release={releaseName}&ticket={ST} Retrieve Value Set Expansions Published by a Program Release https://vsac.nlm.nih.gov/vsac/programs

https://vsac.nlm.nih.gov/vsac/program/{programName}

https://vsac.nlm.nih.gov/vsac/oid/{oid}/programs

https://vsac.nlm.nih.gov/vsac/oid/{oid}/program/{programName}
GET /RetrieveMultipleValueSets?id={oid}&version={version}&ticket={ST} Retrieve Value Set Expansion for a Specified Expansion Version https://vsac.nlm.nih.gov/vsac/oid/{oid}/versions
GET /RetrieveMultipleValueSets?id={oid}&profile={profileName}&ticket={ST} Retrieve Value Set Expansion Calculated with Expansion Profile: Use the utility call https://vsac.nlm.nih.gov/vsac/program/{programName}/latest profile to retrieve a specified program's (example: "CMS eCQM and Hybrid Measure") latest expansion profile. https://vsac.nlm.nih.gov/vsac/profiles

https://vsac.nlm.nih.gov/vsac/program/{programName}/latest profile
GET /RetrieveMultipleValueSets?id={oid}&profile={profileName}&includeDraft=yes&ticket={ST} Retrieve Value Set Expansion of a Draft Value Set Definition: Use the includeDraft parameter to retrieve a temporary expansion of draft value set content. Only VSAC authors and stewards, who are members of at least one VSAC author or steward group, have permissions to retrieve any draft content. https://vsac.nlm.nih.gov/vsac/profiles

https://vsac.nlm.nih.gov/vsac/program/{programName}/latest profile
GET /RetrieveMultipleValueSets?tagName={tagName}&tagValue={tagValue}&ticket={ST} Retrieve Expansions for All Value Sets Specified by a CMS eMeasure ID, or eMeasure Identifier, or NQF Number https://vsac.nlm.nih.gov/vsac/tagNames

https://vsac.nlm.nih.gov/vsac/tagName/{tagName}/tagValues
GET /RetrieveMultipleValueSets?id={oid}&effectiveDate={yyyymmdd}&ticket={ST} Retrieve a Value Set Expansion Published on or before a Specific Date
GET /RetrieveMultipleValueSets?id={oid}&effectiveDate={yyyymmdd}&programType=eCQM&ticket={ST} Retrieve a Value Set Expansion Published on or before a Specific Date in the most recent eCQM program release.
Parameter

Click to view use cases, sample calls and output

Description Use Case
effectiveDate A date on or before which a published value set expansion is published and available in the VSAC public repository. Retrieve a Value Set Expansion Published on or before a Specific Date
id Value set object unique identifier (OID).
includeDraft Allows retrieval of a non-published draft value set definition. Value is 'yes' or 'no'. Retrieve Value Set Expansion of a Draft Value Set Definition
latest profile A specified program's latest expansion profile label that defines a calculation algorithm that applies predetermined code system versions and legacy codes. Example: 'eCQM Update 2020-05-07'. Retrieve Value Set Expansion Calculated with Expansion Profile
profile An expansion profile label that defines a calculation algorithm that applies predetermined code system versions and legacy codes. Examples: 'eCQM Update 2019-05-10', or 'Most Recent Code System Versions in VSAC'. Retrieve Value Set Expansion Calculated with Expansion Profile
program "Program" is the word VSAC applies to the administrative organization and/or application that sponsors, authors and stewards a published release of value sets that together serve a purpose. A program has a pre-arranged agreement with VSAC to publish their value sets as a group. VSAC Utility API Calls: 'programs' and 'latest profile' for program:
  • Retrieve all release names and releaseDates for a given program name
  • Retrieve all published program releases (release names) for a given value set OID and program name
  • Return the value of the most recently available expansion profile to be used by the specified program in an upcoming VSAC program release of that program's value set content. Value of latest profile is subject to change according to the goals of the program it represents
programs Retrieve all program name values for programs supported by VSAC. VSAC Utility API Calls: 'programs' and 'latest profile' for program:
  • Retrieve available values for programs that will enable you to then retrieve release name values for a program of interest.
programType The name of a program that contains the requested OID. Available value: eCQM Retrieve a Value Set Expansion Published on or before a Specific Date: by a specified program.
release Name of a program release. A program release contains multiple pre-selected value sets designated by the program's release manager. Retrieve Value Set Expansions Published by a Program Release
tagName A tag for a collection of value sets, for example: 'CMS eMeasure ID'. Must be used together with 'tagValue'. Retrieve Expansions for All Value Sets Specified by a CMS eMeasure ID, or eMeasure Identifier, or NQF Number
tagNames Retrieves all supported tagNames. Retrieve Expansions for All Value Sets Specified by a CMS eMeasure ID, or eMeasure Identifier, or NQF Number
tagValue The value of a member within a collection (tagName) of value sets. For example, 'CMS68v9' is one of the valid values (tagValue) within the tagName CMS eMeasure ID. Retrieve Expansions for All Value Sets Specified by a CMS eMeasure ID, or eMeasure Identifier, or NQF Number
tagValues Retrieves all supported tagValues. Retrieve Expansions for All Value Sets Specified by a CMS eMeasure ID, or eMeasure Identifier, or NQF Number
ticket A single-use service ticket (ST) is required for each call to the VSAC SVS API.
version A release version label that uniquely identifies a specific value set expansion. For example: 'eCQM Update 2017-05-05' or '20170505'. Retrieve Value Set Expansion for a Specified Expansion Version

All the value set transactions described in this document are represented by a RESTful URL and one or more request parameters. The HTTP request uses the GET method for RetrieveValueSet and RetrieveMultipleValueSets. Encode each parameter as an HTTP Get parameter. The Content-Type field of the HTTP header shall be 'text/xml'. The HTTP request returns an error code if the request parameters are invalid, or if the specified parameter combination is not supported. The request returns an HTTP status code of 404, with an HTTP Warning header containing warning code 111, and warning text 'INV: Invalid search parameters'. A request with valid parameters and parameter combinations that finds no matching value set is not an error. It will return an empty body with HTTP status code of 200.

Last Reviewed: May 26, 2022