NLM logo

We welcome your feedback on our customer service form. Please use "UMLS REST API feedback" in your subject line.

Check out the Postman sample collection to help you get started using the UMLS REST API.

API Terms of Service

Ticket-Granting Ticket and Service Ticket Authentication

We have preserved this documentation for those users who have implemented Ticket-Granting Tickets / Service Ticket authentication. New users should not use this authentication method.

The UMLS REST API requires a UMLS account for the authentication described below. If you do not have a UMLS account, you may apply for a license on the UMLS Terminology Services (UTS) website.

Authentication involves 3 steps and requires you to generate and submit forms using POST calls. You may find Postman or a number of other tools useful for making these POST calls. You can also check out the Postman sample collections, or code samples in Python, Java, and Perl on Github to help you.

For help with making authentication calls using Postman, see our tutorial: UMLS REST API: Authentication and Calling.

Step 1: Get your API key from your UTS profile.

**NOTE**: Use of username and password with any API that requires UTS authentication is now deprecated.

Step 2: Get a Ticket-Granting Ticket (TGT). The TGT is valid for 8 hours. You do not need a new TGT for each REST API call.

Use your API key:

Type of Request URI Key Names Key Values Description
POST apikey Your UMLS API key Retrieves a TGT to be used repeatedly for getting Service Tickets.

curl example:

curl -X POST -H 'content-type: application/x-www-form-urlencoded' -d apikey={your_api_key_here}

Sample response to the POST call for getting a TGT (your TGT of course will be unique):

<title>201 The request has been fulfilled and resulted in a new resource being created</title></head>
<body><h1>TGT Created</h1>
<form action="" method="POST">Service:<input type="text" name="service" value="">
<br><input type="submit" value="Submit"></form>

<!--take the 'action' attribute of the form element and re-use it as your URI to get a service ticket as in call #2 above.-->

Step 3: Get a Service Ticket. A Service Ticket expires after one use or five minutes from the time of generation, whichever comes first. Each REST API call requires a new Service Ticket.

Getting a Service Ticket

Type of Request URI Key Name Key Value Description
POST{TGT} service Retrieves a single-use service ticket for the UMLS REST API.

curl example:

curl -X POST{your_TGT_here} -H 'content-type: application/x-www-form-urlencoded' -d

Sample Response to a POST call for a Service Ticket:


Making use of your Service Tickets

Validating your service ticket