Definitive API
General Notes
The Definitive Healthcare API (v5) enables you to programatically access Definitive Healthcare facility and executive data, as well as saved reports (static or dynamic), using HTTP POST and GET requests. The API is RESTful, ensuring maximum programming flexibility and scalability.
A Data Integration License is required to utilize data outside of DefinitiveHealthcare.com.
All requests are made using https://api.defhc.com/v5, and the URL string determines the result or set of data that is returned.
- Entire data sets for facilities, executives, news items, and RFPs can be retrieved, depending on product access.
- Data can be retrieved for individual facilities or executives using Definitive ID or DHC Executive ID, respectively.
- Data can be retrieved for specific news items or RFPs.
- Custom reports can be built using the Report Builder on DefinitiveHealthcare.com and made accessible to the API using the API Download button; report data is dynamic, not static.
- All requests must be made using HTTPS.
- Queries are case-sensitive.
- Output is JSON format for direct API calls (odata-v4), and csv or xml for custom reports.
- For calls that return a collection of results, a page size parameter $top must be specified. The maximum page size per API request (odata-v4) is 5,000 records.
- Requests can be segmented by determining the record count using a $count query and $skip and $top parameters:
-
- /odata-v4/Hospitals/$count?$filter=State eq 'MA' (returns record count)
- /odata-v4/Hospitals?$filter=State eq 'MA'&$top=1000 (returns first 1,000 records)
- /odata-v4/Hospitals?$filter=State eq 'MA'&$top=1000&$skip=1000 (returns records 1,001 to 2,000)
- Max records returned for a report is either unlimited or 25,000, depending on the search criteria. If a report is capped at 25,000, then you will need to use pagesize and page parameters to download the remaining records (as shown below). There is no way to determine the number of pages in a report, so a programming loop will be required. Note that pagesize and page parameters cannot be used for "unlimited" record reports.
-
- https://api.defhc.com/v5/Reports/physician_default_cardiology/?returntype=csv&pagesize=25000&page=1
- https://api.defhc.com/v5/Reports/physician_default_cardiology/?returntype=csv&pagesize=25000&page=2
- The API (odata-v4) uses Open Data Protocol (OData), so you can incorporate a variety of query options into your URLs to filter the data and return the desired data points.
-
- /odata-v4/Hospitals?$filter=NumBeds gt 500 and contains(Name, 'Mass') // Number of Beds > 500, Name contains "Mass"
- /odata-v4/Hospitals?$select=Name,Id&$filter=NumBeds gt 500 and contains(Name, 'Mass') // returns Name, ID
API Details
Authentication
In order to access the Definitive Healthcare API, you are required to authenticate through the OpenID process. You will need to send an authentication request (POST) to https://api.defhc.com/v5/token with the following parameters: username, password and grant_type=password. In return, you will receive an assigned Bearer Token from the Definitive Healthcare server for the respective set of user credentials. The token will look similar to the following:
- Example 1: DQ8udZDzPtJ2dcly7AMhStOqujkKSRY46cWd89J1x6jIMT44fPimeKrqAQ7ASue9jsX
- Example 2: UQemUnY93VJEfr5PqNU1LkCOzdr6qHhNNYAdeJRSYywDc1J58
Get Access Token
The following data should be posted with the url encoded (application/x-www-form-urlencoded)
- username: Required, variable in length, assigned by Definitive Healthcare
- password: Required, variable in length, initial password assigned by Definitive Healthcare to be changed by end user
- grant_type: Required, should always equal 'password'
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password&username={{userName}}&password={{password}}" "https://api.defhc.com/v5/token"POST https://api.defhc.com/v5/token HTTP/1.1
Host:
Content-Type: application/x-www-form-urlencoded
grant_type=password&username={{userName}}&password={{password}}Executive
Hospital
Hospital API contains several expandable navigation properties. The following related entities can be included by using the $expand option in the query string. For example, https://api.defhc.com/v5/odata-v4/Hospitals(1973)?$expand=Fin.
- Fin - Hospital Financial
- Executives
- RFPs
- NewsItems
- Techs - Technology Implementation
- HCSMs - Hospital Compare Structural Measures
- HCOIs - Hospital Compare Outpatient Imaging
- HCIPPVs - Hospital Compare InPatient Procedure Volumes
- HCOPPVs - Hospital Compare Out Patient Procedure Volumes
- HCHVBPs - Hospital Compare HVBP
- HCHVBPDs - Hospital Compare HVBP Dimension
- HCHVBPSs - Hospital Compare HVBP Score
- HCDs - Hospital Compare Deficiency
Get (All Facilities)
curl -X GET -H "Authorization: Bearer {{token}}" "https://api.defhc.com/v5/odata-v4/Hospitals"GET https://api.defhc.com/v5/odata-v4/Hospitals HTTP/1.1
Host:
Authorization: Bearer {{token}}NewsItem
RFP
Reports
Get My Reports
- ReturnType Optional (default 'csv'), determined by End User for the format of the report . Should be either 'xml' or 'csv'
Returns list of reports the user has access to. Will include both reports created by the user and also the custom reports created by the Definitive helthcare.
curl -X GET -H "Authorization: Bearer {{token}}" "https://api.defhc.com/v5/Reports?returnType={{returnType}}"GET https://api.defhc.com/v5/Reports?returnType={{returnType}} HTTP/1.1
Host:
Authorization: Bearer {{token}}Get My Custom Report
customReportName File name of the report to be downloaded
After initial authentication is complete, please use the end user base URL with the name of the report to retrieve the requested data. Note, the report name should be without the file extension .
Example : HospitalReport
Please work with your dedicated account manager to receive a list of the complete report names that need to be pulled through the Definitive Healthcare API.
curl -X GET -H "Authorization: Bearer {{token}}" "https://api.defhc.com/v5/Reports/{{customReportName}}"GET https://api.defhc.com/v5/Reports/%7B%7BcustomReportName%7D%7D HTTP/1.1
Host:
Authorization: Bearer {{token}}Get My Report
- ReportName: Assigned by you or Definitive Healthcare. The report name should not include the file extension.
- Page: Optional (default =1 ), select a specific page of the report to return
- ReturnType: Optional (default = 'csv'), set format of the report. 'xml' is another option.
- PageSize: Optional (default = 50000), set a specific page size maximum
curl -X GET -H "Authorization: Bearer {{token}}" "https://api.defhc.com/v5/reports/{{reportName}}?pageSize={{pageSize}}&page={{page}}&returnType={{returnType}}"GET https://api.defhc.com/v5/reports/%7B%7BreportName%7D%7D?pageSize={{pageSize}}&page={{page}}&returnType={{returnType}} HTTP/1.1
Host:
Authorization: Bearer {{token}}Testing API with Postman
- Download, install and sign up for Postman through this link: https://www.getpostman.com/. It's free!
-
Create a new POST request using https://api.defhc.com/v5/token to obtain an access token. Click on Body->x-www-form-urlencoded and enter your grant_type, username and password. In the example shown below, you will replace {{userName}} and {{password}} with the username and password you use to log in to DefinitiveHealthcare.com. Additionally, grant_type must equal 'password'. Click Save/Send and copy the bearer token to your clipboard.
-
To retrieve a custom report, create a new GET request using https://api.defhc.com/v5/reports/{{customReportName}} and replace {{customReportName}} with the report name to be downloaded. In addition, paste the bearer token obtained in the previous step into the Authorization->Bearer Token field. Click Save/Send.
-
To see all report names, use the same request as outlined in step #3 without specifying a specific report name.
