22.12.01 Bi-weekly Release: Updated Endpoint: Performance Improvements to GET insurancepackages API Endpoint


The GET insurancepackages API endpoint can now return more than 15 responses, and the stateofcoverage parameter should no longer be used.


athenaCollector, athenaCollector for Hospitals & Health Systems




December 1, 2022

Is this a breaking change

No, this is not a breaking change

Endpoints affected

  • GET insurancepackages

New Endpoints

  • N/A


Refer to the following endpoint documentation in the Developer Portal:

What is changing

  1. The GET insurancepackages API endpoint can now return more than 15 responses.
  • We removed the insurancepackageid sorting - this was limiting the search results.
  • The default number of results returned is 15 (for continuity of workflows), but you can now get up to 500 results max.
  • This also fixes an issue where the limit/offset parameters were not able to be used due to the hard limit of 15 responses being returned.
  • You should now be able to see URLs which can be used to quickly pull the next or previous set of data, depending on how the limit/offset were set.
  1. The stateofcoverage field remains but should NOT be used
  • This field is sparsely populated and provides suboptimal search results for cases where a state name or abbreviation overlaps with the package name.
  • For now, we will leave the field in tact to avoid a breaking change, but this field should be considered deprecated.
  • Users can still pass a state abbreviation such as “Medicare-NY” in the ‘insuranceplanname’ field, which will be considered in the search.

Why we’re making the change

We’re making this change to improve the functionality of the GET /insurancepackages search.


  • GET/insurancepackages only returned 15 responses, regardless of what the limit is set to.
  • If you didn't get a match within those 15 responses, you couldn’t view further responses with the offset parameter.
  • Passing a value in the stateofcoverage field didn't change the API responses.

The insurancepackageid is required in order to make a POST /{patientid}/insurance call, so not being able to effectively retrieve the correct package id with this endpoint added significant developer and workflow challenges in order to add patient insurance information via API.

What will current users of the endpoint need to update in their code

  • Current users of the endpoint do not need to update anything in their code.
  • Current users of the endpoint who are including the stateofcoverage input parameter should remove that parameter for now.

What will happen if users of the endpoint do not update their code

  • The default API response will still return 15 results.
  • The ordering of packages returned may change slightly based on optimized search parameters, but will return more accurate results.
  • You may now see ‘previous’ and ‘next’ URLs when using the limit and offset parameters.

Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others

On this Page