Please note: The information on this page refers to the original VSAC SVS API v1, which was replaced by a new API, VSAC SVS API v2, on January 27, 2015. We will continue to support the original API until further notice..

The VSAC API offers a REST service to obtain CAS Ticket Granting Tickets (TGT) and Service Tickets.

To make API calls, 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 a POST request for a single-use service ticket 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 call.
3. Use your service tickets to make GET requests as specified in the methods below.

If you already know a Value Set Object Identifier (OID), or a Measure's NQF number or a CMS Measure ID, the API calls are the most straightforward method of retrieving and downloading value set data in XML format.
There are 2 methods available for API calls:

• RetrieveValueSet

  RetrieveValueSet takes a Value Set Object Identifier (id) as a parameter. The Value Set Repository returns an expanded value set in XML format. It does not return any metadata associated with a measure that uses the value set. Example 1: no version or effectiveDate provided with id parameter. Latest version 20130401 returned. https://vsac.nlm.nih.gov/vsac/ws/RetrieveValueSet?id=2.16.840.1.113883.3.666.5.1738&ticket=xxxx Example 2: version 20121025 provided with id. Exact version 20121025 returned. https://vsac.nlm.nih.gov/vsac/ws/RetrieveValueSet?id=2.16.840.1.113883.3.666.5.1738&version=20121025&ticket=xxxx Example 3: effectiveDate 20121231 provided with id. Version 20121025 returned. https://vsac.nlm.nih.gov/vsac/ws/RetrieveValueSet?id=2.16.840.1.113883.3.666.5.1738&effectiveDate=20121231&ticket=xxxx

• RetrieveMultipleValueSets

  RetrieveMultipleValueSets not only returns an expanded value set, but also returns all metadata associated with the value set(s) such as a CQM or other higher level construct, as well as associated metadata. RetrieveMultipleValueSets can take one the following as parameters:

  • OID

    For use if you already know the object identifier for a value set. The OID parameter returns, in XML format, every expanded value set contained within this OID (including all terms, codes and code systems for each value set) along with the metadata for the each value set. Example: https://vsac.nlm.nih.gov/vsac/ws/RetrieveMultipleValueSets?id=1.3.6.1.4.1.33895.1.3.0.31&ticket=<ServiceTicket>

  • CMS eMeasure Identifier

    Use this to retrieve all value sets for a given CMS eMeasure ID. The returned XML contains every expanded value set for the eCQM (including all terms, codes and code systems for each value set) along with the metadata for the each value set. Example: https://vsac.nlm.nih.gov/vsac/ws/RetrieveMultipleValueSets?cmsemeasureid=CMS100v1&ticket=<ServiceTicket>

  • NQFNumber

    Use this if you want to retrieve all value sets that support a particular National Quality Forum endorsed Clinical Quality Measure. The returned XML contains every expanded value set contained within this NQFNumber, including all terms, codes and code systems for each value set along with the metadata for each value set Example: https://vsac.nlm.nih.gov/vsac/ws/RetrieveMultipleValueSets?NQFNumber=0002&ticket=<ServiceTicket>

  • Measure ID

    Use this to retrieve value sets that support a given ID assigned by the Measure Authoring Tool (MAT). Example: https://vsac.nlm.nih.gov/vsac/ws/RetrieveMultipleValueSets?measureid=146&ticket=<ServiceTicket>

Last Reviewed: October 29, 2015