VSAC API Resources

UMLS License Requirement and Terms of Service

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.

Authentication

The FHIR Terminology Service for VSAC Resources authentication service requires a free UMLS account. Use basic authentication with your UMLS API Key.

For example, if you are using a RESTful client platform such as Postman, choose:

Authorization Type = Basic Auth
username = ‘apikey’ or leave it blank
password = user’s actual UMLS API Key

For software developers, here is a Java example of embedding a VSAC FHIR API call within a program.

You can find your API Key in the My Profile area of the UMLS Terminology Services (UTS) 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.

Base URI, Capability Statement, Sample Queries

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

Base URLs

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/

Authentication URL: https://vsac.nlm.nih.gov/vsac/ws (Deprecated and discontinued by November 2023. This URL was for use with the TGT/STS authentication method.)

Authentication

The VSAC SVS API authentication service requires a free 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

For software developers, here is a Java example of embedding a VSAC SVS API call within a program.

NOTE:The Ticket Granting Ticket authentication for the VSAC SVS API has been deprecated. The VSAC SVS API authentication method will switch exclusively to the API key authentication method by the end of November 2023. If you have a need to use this deprecated TGT/ST authentication method between now and the end of November 2023, see Ticket-Granting Ticket and Service Ticket Documentation and remember to append "&ticket={ST}" to each of your VSAC SVS API calls.

Endpoint Calls and Related Utility Calls

Endpoints to search and retrieve VSAC content

Use basic authentication with your UMLS API Key.

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
Basic URL https://vsac.nlm.nih.gov/vsac/svs
GET	/RetrieveMultipleValueSets?id={oid}	Retrieve Most Recent Value Set Expansions: includes value set metadata and concept list.
GET	/RetrieveValueSet?id={oid}	Retrieve Most Recent Value Set Expansions: includes only value set concept list, no metadata.
GET	/RetrieveMultipleValueSets?id={oid}&release={releaseName}	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}	Retrieve Value Set Expansion for a Specified Expansion Version	https://vsac.nlm.nih.gov/vsac/oid/{oid}/versions
GET	/RetrieveMultipleValueSets?id={oid}&profile={profileName}	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	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}	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}	Retrieve a Value Set Expansion Published on or before a Specific Date
GET	/RetrieveMultipleValueSets?id={oid}&effectiveDate={yyyymmdd}&programType=eCQM	Retrieve a Value Set Expansion Published on or before a Specific Date in the most recent eCQM program release.

Parameter Descriptions

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
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

HTTP Binding

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: September 7, 2023

VSAC Support Center