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