Building Your Own Claims API

Sam Gensburg
6 min readJul 16, 2018


Earlier this year, CMS launched the Blue Button 2.0 project with the help of the U. S. Digital Service, allowing developers and Medicare beneficiaries across the country to begin accessing their medical history via API. This represents a huge step forward for the 53 million Medicare beneficiaries that can access the API, but leaves everyone else empty-handed, whether they’re Medicaid recipients or using private health insurance. Because of this, CMS has announced that it intends to start requiring that certain types of insurance plans begin providing similar services. Even before this announcement though, we often got questions from state health agencies and other payers asking, how can I build something like this?

The team has open-sourced all of our code at, and while this is a great place to start, much of the work comes down to the specifics of your databases and other internal systems.

So, how do you get started? How do you determine how much a system like this will cost or how long it will take to build? For me, it starts with a simple principle.

Data + Identity = API

Building your claims API really comes down to three approachable steps:

1. Find or build a data source that has the right information and is API-ready.

2. Incorporate an identity source that allows you to securely match users to their data.

3. And finally, connect it all together with an API server that’s internet-ready.

Each of these steps can be easy or challenging, depending on what you already have in place inside your organization. It’s up to you to look at the specifics of what you already have in place and to determine how easily it can be reused. Below, we’ll dive into each of these components, talk about what we built for Blue Button, and go over the key components you’ll need for your claims API.

1. The Database

Every API begins with a database, and a claims API is no different. For an existing payer, you’ll definitely have one of these — in fact, you may have several that you’ll need to use. While it’s better to have a single database, as long as all of your databases can be queried in parallel, it shouldn’t cause a problem. In the end, what you’re looking for is a database or small number of databases that meet the following criteria:

  • Has 100%, 24/7 uptime. No monthly maintenance windows or random outages. Your API will likely get called in the middle of the night and on weekends, so your daytime analytics database probably won’t work.
  • Responds to queries for an average medical record in a couple seconds or less. APIs generally need to respond in under ten seconds, so you can’t have your database eating up too much of that time. If your database is well-indexed and designed, this shouldn’t be a problem.
  • Has a well-known, unique identifier that we can match to the identity system in step two. First and last name will be insufficient.
  • Has enough information to represent a patient’s claims history.

And how did we do this at CMS? CMS had an existing analytics database called the Chronic Conditions Warehouse (, but it was too slow, and didn’t have the uptime we wanted. So, we built our own read-only version, and built scripts that could import data from the CCW on a recurring basis.

In general, read replicas of analytics warehouses are a good choice for many organizations unless you feel comfortable building directly on top of your claims processing database.

Finally, assuming you want to use FHIR for your API output, you’ll need to map your database fields to the FHIR standard. This can be a lot of manual work, and your database is likely unique in many ways, so you’ll have to do this yourself. You can check out our work in a detailed spreadsheet in our GitHub repo.

2. The Identity Source

The next thing you’ll need to build is a way for your beneficiaries to log in. Hopefully you already have one of these, otherwise getting all of the accounts set up will be very difficult. Because of this, I strongly suggest reusing any existing system you may have, even if it’s not ideal. In the end, you only need three things from your identity source:

  • Confidence that the person signing in is who they say they are. This can mean identity proofing everyone online or creating accounts in person. But it’s worth some extra attention before giving out health information.
  • A unique identifier. At CMS, this meant a HICN or MBI, but you likely have your own system. As long as it uniquely identifies patients and also exists in your database above, you should be fine.
  • An ability to connect to a new system, such as the API you’re building.

For Blue Button 2.0, we built on top of CMS’s account system, which already included identity proofing and the user’s HICN or MBI. From there, we worked with that team to create a new OpenID Connect interface so that we could use them as an external identity source. We securely hashed the user’s HICN and used that to match them with the data in our new database.

3. The API

Once you have your data and identity systems together, now it’s just a matter of connecting all the pieces and making it public. This is where open source tools such as HAPI and our own server can be useful. There’s a lot of discussion in other places around the exact details of how you implement an API, but here are some good defaults:

  • Use JSON and FHIR for your data format.
  • Use OAuth to determine permissions
  • Only give out API keys to companies you’ve spoken to and have some trust in. You’ll never be perfect, but don’t give a key to just anyone, and definitely don’t give it out automatically.
  • Have a public sandbox version of your API with synthetic data.

Other than that, it’s just a matter of building those mappings out by hand and making sure your server doesn’t collapse when it starts getting some traffic.

4. The Community

I said this was a simple three step process, right? But, while we may have a working API now, there is one last step that government agencies often forget. There’s not much point in building an API if no developers are going to use it. We often approach building systems with a, “build and they will come, but even if you build a great API and make it free, you aren’t guaranteed that anyone will ever use it. If you want developers on your platform, you’ll need to seek them out, and do the hard work of convincing them to come onboard.

This means doing outreach in your local and national communities, finding the companies that already work in this space, and helping them connect to your API. You need to put the time in to address their concerns, provide detailed documentation, and get people excited about your platform. If you have a great tool, this won’t necessarily be difficult, but expect a lot of phone calls as you bring developers on one at a time.


Overall, this doesn’t need to be a difficult process, but it can definitely become time consuming if you don’t have any of the pieces already in place. However, building great infrastructure will have payoffs far beyond this project, so the effort will be well worth it.

Most of all, I’m looking forward to seeing other people start building similar tools to Blue Button 2.0. Hopefully, we’ll soon have dozens of examples to point to for how this can be done. Success may look different in different places, and I’m looking forward to seeing what others achieve in this space.

Do you have specific questions about your individual situation? Feel free to reach out to me directly, or to any of my USDS and Blue Button colleagues. Want to learn about Blue Button 2.0? Check out the site at, and feel free to ask any specific questions in our Google Group. And, if you’re deeply committed to helping the Federal Government build incredible, forward-thinking software, I strongly encourage you to join the US Digital Service and submit an application at My two years with the USDS at HHS have been an incredible learning experience and opportunity to help our country move forward, and I encourage you to consider joining if it’s an option for you.



Sam Gensburg

Software engineer making important things work just a little better, focused on healthcare and government