CMS.gov Getting Started: API Access & First Request (2026)

Getting started overview

Accessing the CMS.gov APIs enables developers, researchers, and analysts to programmatically retrieve a wide range of public healthcare data. This includes information on Medicare enrollment, Medicaid and CHIP programs, healthcare provider directories, and quality measures. The APIs are designed to support transparency, research, and the development of applications that utilize public health data. All CMS.gov APIs are free to use and are primarily focused on providing data for public information and policy analysis. The process typically involves registering for an API key, understanding the specific API endpoints, and constructing HTTP requests to retrieve desired datasets.

The CMS.gov data APIs are designed to be RESTful, utilizing standard HTTP methods (GET) and returning data primarily in JSON format. Some APIs may also support CSV or XML. Understanding HTTP methods and JSON data structures is beneficial for efficient integration. Data compliance, particularly with HIPAA regulations, is a cornerstone of CMS.gov's data handling, though the public APIs generally provide de-identified or aggregated data.

Here's a quick reference table outlining the initial steps:

Create an account and get keys

To begin using the CMS.gov APIs, you must register for an API key. This key authenticates your requests and ensures proper usage of the public data resources. The registration process is straightforward and typically involves providing basic contact information. There are no associated costs for obtaining or using these keys, as all CMS.gov public data APIs are free to access.

1. Navigate to the API Documentation: Start by visiting the official CMS.gov API documentation page. This page serves as the central hub for all API-related information, including links to registration.
2. Locate the Registration Section: On the API documentation page, look for a section or link specifically for "Get an API Key" or "Register for API Access." This might be prominently displayed or found within a "Getting Started" guide.
3. Complete the Registration Form: You will be prompted to fill out a form requiring details such as your name, email address, and possibly your organization. Ensure all required fields are accurately completed. The purpose of this registration is primarily for usage tracking and communication regarding API updates or changes.
4. Receive Your API Key: Upon successful submission of the registration form, your API key will typically be displayed on the screen or sent to your registered email address. This key is a unique alphanumeric string that you will include in your API requests. It is important to treat your API key as confidential to prevent unauthorized use, even for public data, as it is tied to your registration.
5. Store Your Key Securely: Once you have your API key, store it in a secure location. Avoid embedding it directly into client-side code that could be publicly exposed. For server-side applications, consider using environment variables or a secure configuration management system to manage your API keys.

Each API key is generally valid for all public CMS.gov APIs, simplifying access across various datasets. If you encounter any issues during registration or do not receive your key, consult the CMS.gov API support resources listed on their documentation page.

Your first request

After acquiring your API key, you can make your first request to a CMS.gov API endpoint. For this example, we'll use a hypothetical public data endpoint that provides information about healthcare providers, as it's a common and accessible type of data offered.

Example API Endpoint Structure:

While specific endpoints vary, a typical CMS.gov API request might look like this (replace with an actual endpoint from the CMS.gov API catalog once available):

GET https://data.cms.gov/api/v1/providers?state=CA&apiKey=YOUR_API_KEY

In this example:

• https://data.cms.gov/api/v1/providers is the base URL for the provider data API.
• ?state=CA is a query parameter to filter providers by the state of California.
• &apiKey=YOUR_API_KEY is where you will insert the API key you received during registration.

Using cURL for a quick test

cURL is a command-line tool and library for transferring data with URLs, commonly used for testing API endpoints. To make your first request, open your terminal or command prompt and execute the following, replacing YOUR_API_KEY with your actual key and adjusting the endpoint if necessary:

curl "https://data.cms.gov/api/v1/providers?state=NY&apiKey=YOUR_API_KEY"

Upon successful execution, the terminal should display a JSON response containing provider data filtered by New York state. The structure of the JSON will depend on the specific API endpoint queried, but it will typically be an array of objects, where each object represents a data record (e.g., a healthcare provider).

Example Python request

For programmatic access, Python is a popular choice due to its simplicity and robust libraries. Here's how you might make the same request using Python's requests library:

import requests
import json

api_key = "YOUR_API_KEY" # Replace with your actual API key
base_url = "https://data.cms.gov/api/v1/providers" # Replace with actual base URL

params = {
    "state": "TX",
    "apiKey": api_key
}

try:
    response = requests.get(base_url, params=params)
    response.raise_for_status() # Raise an HTTPError for bad responses (4xx or 5xx)
    data = response.json()
    print(json.dumps(data, indent=2))
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")
except json.JSONDecodeError:
    print("Failed to decode JSON response.")
    print(f"Raw response: {response.text}")

This Python script will print a formatted JSON output of healthcare providers in Texas. Remember to replace the placeholder API key and verify the endpoint URL against the current CMS.gov API specifications.

Common next steps

Once you've successfully made your first API call, consider these next steps to further integrate with CMS.gov data:

1. Explore More Endpoints: The CMS.gov API catalog offers various datasets beyond the initial example. Review the full API documentation to identify other relevant data, such as Medicare enrollment statistics, Medicaid claims data, or quality measure outcomes. Each API will have its own specific parameters and response structures.
2. Understand Data Filtering and Paging: Many APIs support parameters for filtering results (e.g., by state, year, provider type) and paging through large datasets to manage response size. Familiarize yourself with these capabilities to retrieve exactly the data you need efficiently. The CMS.gov developer guide will detail these options.
3. Implement Error Handling: As you develop more robust applications, implement comprehensive error handling. This includes checking HTTP status codes (e.g., 200 for success, 400 for bad request, 401 for unauthorized, 500 for server errors) and parsing API-specific error messages. The MDN Web Docs on HTTP status codes provide a general reference.
4. Rate Limiting Awareness: While CMS.gov APIs are free, they may have rate limits to prevent abuse and ensure fair access for all users. Check the API usage policies for details on request limits and how to handle them (e.g., using exponential backoff).
5. Data Storage and Processing: For larger datasets or frequent analysis, consider how you will store and process the retrieved data. This might involve setting up a local database, using data warehousing solutions, or integrating with data analysis tools.
6. Stay Updated: APIs evolve. Regularly check the CMS.gov API news and updates section for changes, new endpoints, or deprecations that might affect your application.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

• Invalid API Key (401 Unauthorized): Double-check that you have copied your API key correctly and that it is included in your request as specified in the documentation (usually as a query parameter). Ensure there are no extra spaces or incorrect characters. If your key is new, it might take a few minutes for it to become active.
• Incorrect Endpoint URL (404 Not Found): Verify the exact URL of the API endpoint against the CMS.gov API documentation. Typos in the base URL, version number, or resource path can lead to a 404 error.
• Missing or Incorrect Parameters (400 Bad Request): Ensure all required query parameters are present and correctly formatted. For example, if an API expects a "state" parameter, make sure it's included and its value is valid (e.g., "CA" instead of "California" if the API expects abbreviations). Refer to the specific API's parameter documentation.
• Network Issues: Confirm your internet connection is stable. If you are behind a corporate firewall or proxy, ensure it's configured to allow outbound HTTP/HTTPS requests to data.cms.gov.
• JSON Parsing Errors: If your code reports issues parsing the JSON response, it might be due to an incomplete or malformed response from the API. First, check the HTTP status code. If it's not 200 OK, the "JSON" might actually be an HTML error page. If the status is 200, inspect the raw response content to identify any unexpected formatting.
• Rate Limit Exceeded (429 Too Many Requests): If you make too many requests in a short period, the API might temporarily block you. Wait for a few minutes and try again. For production applications, implement proper rate limiting strategies and exponential backoff.
• Server-Side Errors (5xx): A 5xx status code indicates an issue on the API server's side. These are typically out of your control. If these persist, check the CMS.gov API status page or contact their support.