Leveraging the API for reporting integrations
Written by Shawn Price
Updated at February 6th, 2025
Table of Contents
Reporting
A common use-case for API integrations is to extract data for use in external reporting tools such as Tableau, Power BI or other third party solutions. While it's certainly possible to pull data from a myriad of endpoints available via the API, there are a handful of endpoints designed specifically for this task that simplify the work involved dramatically.
Core-Concepts:
Data-Sources
The reporting functionality within the Healthy Roster system leverages pre-packaged groups of data called Data-Sources. These data-sources combine the data related to specific areas of functionality within the application in a manner that is easier to consume by reporting engines. Patient demographic information, meta data, and other important information are flattened into row based data making them easier to group, filter and manipulate. These same data-sources can be leveraged via the API to help export the appropriate information as needed.
A list of available data-sources can be viewed within the application (more information available here). Or can be accessed via the API using the /HealthcareProvider/{id}/Datasources endpoint. The endpoint provides a description of each data source. More information about a specific data source, including what fields are included and what parameters are available for filtering can be retrieved via the /HealthcareProvider/{id}/Reporting/DataSources/{datasourceid} endpoint.
Fetching Data
Once you have identified the appropriate data-source, the associated data can be retrieved via the /HealthcareProvider/{id}/Reporting/Datasources/{datasourceid}/Data endpoint. While the verb for this endpoint is POST, that is due to functional limitations around passing parameters via the query string and the endpoint can be viewed as a GET endpoint without fear of modifying data.
The list of available parameters can be fetched for each data source using the endpoint listed under “Data-Sources” above.
A Note on Patient-Organization relationships
Many of the data sources attempt to utilize the date range intelligently to help avoid providing incorrect or misleading data with regards to patient membership within certain organizations. A common scenario in the sports medicine setting is for an athlete to be adding to a fall sport in the fall and then moved to a winter sport once the winter season starts. If you are attempting to pull injury related metrics for winter sports you would not want to include injuries that were entered during the fall season, prior to the athlete's participation within that team.
While this can be helpful, it is not always the desirable behavior. For instance, if you are not entering patient records until after an injury has occurred then the injury will be filtered due to it occurring before the patient was created (and therefore before the patient was added to the organization). To prevent this filtering you can pass the ignorePatientOrganizationMembershipDates parameter with a value of true. This will return all results regardless of when the patient was added to the corresponding organizations.