Skip Navigation Bar

VSAC Support Center

VSAC SVS API v2


This document describes the VSAC SVS API v2, based on the IHE Sharing Value Sets (SVS) Technical Framework. We no longer provide support for the deprecated API. One key difference from the deprecated VSAC API implementation is that each use case (represented by a unique HTTP URL and parameter combination) has a mandatory parameter requirement with no default implementation available.


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 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/
Call # Call Type HTTP Request Type URL-Path Parameters Use Case
1 Authentication POST https://vsac.nlm.nih.gov/vsac/ws/Ticket Specify username={username}&password={password} in the POST request body. Use your UMLS account credentials to retrieve a CAS Ticket Granting Ticket that lasts for 8 hours. There is no need to repeat this more often than every 8 hours.
2 Authentication POST https://vsac.nlm.nih.gov/vsac/ws/Ticket/{ticket-granting-ticket} Specify http://umlsks.nlm.nih.gov as the service in the POST request. Use the Ticket Granting Ticket received from call #1 to retrieve a Service Ticket. You will need an individual Service Ticket for each call made to the VSAC SVS API (except authentication calls). A Service Ticket expires after one use and 5 minutes of its generation.
3 Content GET https://vsac.nlm.nih.gov/vsac/svs/RetrieveMultipleValueSets or https://vsac.nlm.nih.gov/vsac/svs/RetrieveValueSet ?id={oid}&ticket={serviceTicket} Retrieve the most recent value set expansion of an OID based on the latest code system versions available in VSAC (the Most Recent Code System Versions in VSAC profile).
4 Content GET https://vsac.nlm.nih.gov/vsac/svs/RetrieveMultipleValueSets or https://vsac.nlm.nih.gov/vsac/svs/svs/RetrieveValueSet ?id={oid}&version={version}&ticket={serviceTicket} Retrieve the value set expansion of an OID based on the specified expansion version label, such as 'MU2 EP Update 2015-05-01' or '20141020'. See Utility calls for more information on how to retrieve all available OID expansion version labels.
5 Content GET https://vsac.nlm.nih.gov/vsac/svs/RetrieveMultipleValueSets ?id={oid}&effectiveDate={yyyymmdd}&ticket={serviceTicket} Retrieve the value set expansion of an OID, from the available set of Most Recent Code System Versions in VSAC versions, available on or before the specified date. If you use the effectiveDate parameter by itself, without combining it with the programType parameter, you will retrieve the Most Recent Code System Versions in VSAC as of your supplied effectiveDate. We do not anticipate many use cases for employing the effectiveDate parameter without combining it with the programType parameter.
6 Content GET https://vsac.nlm.nih.gov/vsac/svs/RetrieveMultipleValueSets ?id={oid}&effectiveDate={yyyymmdd}&programType={programType}&ticket={serviceTicket} Retrieve a value set expansion published in the most recent program release, specified by programType, available on or before the specified effective date. Available programs at this time are MU2 (the CMS eCQM value sets) and VSAC (value set expansions based on the Most Recent Code System Versions in VSAC profile).
7 Content GET https://vsac.nlm.nih.gov/vsac/svs/RetrieveMultipleValueSets ?id={oid}&effectiveDate={yyyymmdd}&programType={programType}&subType={subType}&ticket={serviceTicket} Retrieve a value set expansion published in the most recent program release specified by programType and subtype, available on or before the specified effective date. Available programs at this time are MU2 (the CMS eCQM value sets) and VSAC (value set expansions based on the Most Recent Code System Versions in VSAC profile). Available subTypes for the MU2 program are EH (eligible hospitals) and EP (eligible professionals).
8 Content GET https://vsac.nlm.nih.gov/vsac/svs/RetrieveMultipleValueSets ?id={oid}&profile={profileName}&ticket={serviceTicket} Retrieve the latest published value set expansion associated with the specified expansion profile. If the specified value set OID has not been published, then no results will be returned by the API. See Utility calls for more information on how to retrieve all available expansion profileNames.
9 Content GET https://vsac.nlm.nih.gov/vsac/svs/RetrieveMultipleValueSets ?id={oid}&profile={profileName}&ticket={serviceTicket} Retrieve the latest published value set expansion associated with the specified expansion profile. If the specified value set OID has not been published then the call retrieves the most recent draft definition of the specified value set OID, if available, calculated with the specified expansion profile.
10 Content GET https://vsac.nlm.nih.gov/vsac/svs/RetrieveMultipleValueSets ?tagName={tagName}&tagValue={tagValue}&ticket={serviceTicket} Combine 'tagName' with 'tagValue' to specify a value set expansion based on some kind of property. For example, tagName 'CMS eMeasure ID' combined with tagValue 'CMS100v3' would retrieve all value sets used in CMS100v3. See Utility calls for more information on how to retrieve all supported values for the tagNames and tagValue parameters.
11 Utility GET https://vsac.nlm.nih.gov/vsac/tagNames ?ticket={serviceTicket} Retrieve supported tagNames. Currently this list contains 'CMS eMeasure ID', 'eMeasure Identifier', and 'NQF Number'.
12 Utility GET https://vsac.nlm.nih.gov/vsac/tagName/{tagName}/tagValues ?ticket={serviceTicket} Retrieve list of tagValues for a given tagName. For example, you could retrieve the entire list of CMS eMeasure ID values, using /tagName=CMS eMeasure ID/tagValue?ticket={serviceTicket}.
13 Utility GET https://vsac.nlm.nih.gov/vsac/oid/{oid}/versions ?ticket={serviceTicket} Retrieve list of expansion version labels available for a given OID.
14 Utility GET https://vsac.nlm.nih.gov/vsac/profiles ?ticket={serviceTicket} Return the list of available expansion profiles.

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.

The VSAC API offers a REST service to obtain CAS Ticket Granting Tickets (TGT) and Service Tickets. See the REST Protocol documentation for more details on obtaining Ticket Granting Tickets and Service Tickets. In order to make API calls to the VSAC, do the following:

  1. Obtain a TGT using your UMLS username and password by making a POST request to https://vsac.nlm.nih.gov/vsac/ws/Ticket. The TGT can be re-used to make calls to obtain single-use service tickets and is good for 8 hours.
  2. Use your TGT to make POST requests for single-use service tickets at the URL https://vsac.nlm.nih.gov/vsac/ws/Ticket/<TicketGrantingTicket>. Specify the URL http://umlsks.nlm.nih.gov as the service in the POST request. Each service ticket is good for 5 minutes but expires after one use.
  3. Use your service tickets to make GET requests as specified in the methods below.
Parameter Description Note
ticket A single-use Service Ticket for the API request
id Value set object unique identifier (OID)
version A release version label that uniquely identifies a specific value set expansion. For example: 'MU2 EP Update 2015-05-01' or '20150501'
effectiveDate A date on or before which a published value set expansion is available in the VSAC public repository. For example: 20160401. When you use the effectiveDate parameter, you are trying to retrieve the most recent version of a value set that was available up to and including the effectiveDate you supplied as your parameter value.
programType The name of a program that contains the requested OID. Examples: MU2, VSAC
subType The name of a subtype designated by a program, such as MU2. Examples: EP, EH Must be used together with programType. Currently can only be used with the MU2 programType.
profile Expansion profile of program-determined code system versions and allowed legacy codes used for VSAC calculation of a requested value set. For example: 'MU2 EP Update 2014-07-01'
tagName The name of a grouping tag for multiple value sets, for example: 'CMS eMeasure ID' Must be used together with 'tagValue'.
tagNames Retrieves all supported tagNames Used only in this example call: https://vsac.nlm.nih.gov/vsac/tagNames?ticket={serviceTicket}
tagValue The value of a grouping tag for multiple value sets, for example, CMS100v1 Must be used together with 'tagName'.
tagValues Retrieves all supported tagValues Used only in this example call: https://vsac.nlm.nih.gov/vsac/tagName/{tagName}/tagValues?ticket={serviceTicket}
includeDraft If specified, allows retrieval of a non-published draft value set definition. Value is 'yes' or 'no' Must be used together with 'profile' parameter. The VSAC SVS API will allow draft value set retrieval only by the draft value set's assigned author or steward group members. The includeDraft parameter should only be used by value set authors or their proxies and VSAC does not guarantee that a draft will ever reach a published status which is required for use in external systems.