How to Query the CMS Open Payments API (Without Downloading Multi-GB CSVs)

#python #api #opendata #healthcare

What is CMS Open Payments?

CMS Open Payments (the Sunshine Act transparency program) publishes payments and transfers of value from drug and device manufacturers to physicians, non-physician practitioners, and teaching hospitals. Data is released as large public files and also exposed through the official Open Payments datastore query API on openpaymentsdata.cms.gov.

If you only need filtered rows — for example consulting fees in one state, or payments tied to a specific manufacturer — you usually do not need to download the entire yearly CSV.

Official API pattern (high level)

Resolve the dataset UUID for the program year and payment type (general, research, or ownership).
POST (or GET) to the datastore query endpoint for that dataset with limit, offset, and conditions (state, NPI, nature of payment, etc.).
Map the returned rows into the fields your pipeline needs.

CMS documents the metastore and datastore query interfaces on the Open Payments site. Always prefer the federal source of truth for schema changes.

Faster path: ready-made JSON Actors / APIs

If you want filtered JSON without writing the client yourself:

Apify Actor (free): CMS Open Payments Scraper — wraps the official API; filter by state, NPI, manufacturer, nature, amount; export JSON/CSV.
HTTP API: CMS Healthcare Data API on Zyla — GET /v1/open-payments with plan key.

Example Apify input

{
  "paymentType": "general",
  "year": 2024,
  "recipientState": "RI",
  "natureOfPayment": "Consulting Fee",
  "maxItems": 100
}

Example Zyla-style query

GET /v1/open-payments?recipientState=RI&year=2024&natureOfPayment=Consulting%20Fee&limit=25

Common pitfalls

Unfiltered dumps of a full program year are huge. Always pass at least one selective filter (state, NPI, manufacturer, or nature).
Payment amounts are often stored as text in the source files; normalize to numbers in your client.
Research and ownership files share many columns with general payments but not all filters apply equally.

Related datasets

Disclaimer

This article describes public federal open data. It is not legal advice. Review CMS terms and applicable privacy law for your use case.

Disclosure: Theta Tech built the free Apify Actors and the CMS Healthcare Data API linked in this article.

DEV Community