NLM logo

UMLS API Technical Documentation

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

Check out the Postman sample collections, or code samples in Python, Java, and Perl on Github to help you get started using the UMLS REST API.

API Terms of Service

User Authentication

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. We also offer an authentication demo.

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

Authentication Demo

Request a Ticket Granting Ticket (TGT)

Enter your API key. You can get your API key by visiting your profile at


Method POST
Headers Content-Type=application/x-www-form-urlencoded
Parameters username={yourusername}&password={yourpassword}



Extracted URL with TGT for obtaining Service Tickets:


Your Ticket-Granting Ticket will be valid for 8 hours.

down arrow

Request a Service Ticket (ST)

You must request a Ticket-Granting Ticket above before requesting a service ticket.


Method POST
Headers Content-Type=application/x-www-form-urlencoded
Parameters service=


down arrow

Request Data

To request data, append your Service Ticket to your request URL. For example:{yourServiceTicket}. Each new request requires a new Service Ticket.