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 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
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.)
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.
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.
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.
Endpoints to search and retrieve VSAC content
Use basic authentication with your UMLS API Key.
| 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} | 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 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:
|
| programs | Retrieve all program name values for programs supported by VSAC. | VSAC Utility API Calls: 'programs' and 'latest profile' for
program:
|
| 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 |
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