Definitive API

General notes

The Definitive Healthcare API (V4) works using the custom reports created for you by Definitive Healthcare or using the saved reports created through https://www.defhc.com.

Requirements to access the Definitive Healthcare API are standard and basic practice, which include the following unique identifiers: username, password, and grant type.

All requests will be made at https://api.defhc.com/v4, in which the URL string will determine the result or set of data that is returned.
Please note that all requests will go over https , and all other types of requests will not be returned.

API details

Authentication

In order to access the Definitive Healthcare API, the end user is required to authenticate through the OpenID process. The user will need to send an authentication request (POST) to the following URL: https://api.defhc.com/v4/token with their respective username , password and granttype=password parameters.
In return, the user will receive an assigned access token from the Definitive Healthcare server for the respective set of user credentials. An access token, for example, could look like the following examples:

  • Example 1: DQ8udZDzPtJ2dcly7AMhStOqujkKSRY46cWd89J1x6jIMT44fPimeKrqAQ7ASue9jsX
  • Example 2: UQemUnY93VJEfr5PqNU1LkCOzdr6qHhNNYAdeJRSYywDc1J58

Again, please note that an access token is a requirement in order to successfully pull data from the Definitive Healthcare server.

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 be always equal to 'password'
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password&username={{userName}}&password={{password}}" "https://api.defhc.com/v4/token"
POST https://api.defhc.com/v4/token HTTP/1.1
Host: 
Content-Type: application/x-www-form-urlencoded
grant_type=password&username={{userName}}&password={{password}}

Executive

Get 

curl -X GET -H "Authorization: Bearer {{token}}" "https://api.defhc.com/v4/odata-v4/Executives"
GET https://api.defhc.com/v4/odata-v4/Executives HTTP/1.1
Host: 
Authorization: Bearer {{token}}

Get Details 

curl -X GET -H "Authorization: Bearer {{token}}" "https://api.defhc.com/v4/odata-v4/Executives({{executiveId}})"
GET https://api.defhc.com/v4/odata-v4/Executives%28%7B%7BexecutiveId%7D%7D%29 HTTP/1.1
Host: 
Authorization: Bearer {{token}}

Hospital

Hospital API contains several expandable navigation properties

  • 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 

curl -X GET -H "Authorization: Bearer {{token}}" "https://api.defhc.com/v4/odata-v4/Hospitals"
GET https://api.defhc.com/v4/odata-v4/Hospitals HTTP/1.1
Host: 
Authorization: Bearer {{token}}

Get expand executives 

curl -X GET -H "Authorization: Bearer {{token}}" "https://api.defhc.com/v4/odata-v4/Hospitals?$expand=Executives"
GET https://api.defhc.com/v4/odata-v4/Hospitals?$expand=Executives HTTP/1.1
Host: 
Authorization: Bearer {{token}}

Get details 

curl -X GET -H "Authorization: Bearer {{token}}" "https://api.defhc.com/v4/odata-v4/Hospitals({{hospitalId}})"
GET https://api.defhc.com/v4/odata-v4/Hospitals%28%7B%7BhospitalId%7D%7D%29 HTTP/1.1
Host: 
Authorization: Bearer {{token}}

NewsItem

Get 

curl -X GET -H "Authorization: Bearer {{token}}" "https://api.defhc.com/v4/odata-v4/NewsItems"
GET https://api.defhc.com/v4/odata-v4/NewsItems HTTP/1.1
Host: 
Authorization: Bearer {{token}}

Get Details 

curl -X GET -H "Authorization: Bearer {{token}}" "https://api.defhc.com/v4/odata-v4/NewsItems({{newsItemId}})"
GET https://api.defhc.com/v4/odata-v4/NewsItems%28%7B%7BnewsItemId%7D%7D%29 HTTP/1.1
Host: 
Authorization: Bearer {{token}}

RFP

Get 

curl -X GET -H "Authorization: Bearer {{token}}" "https://api.defhc.com/v4/odata-v4/RFP"
GET https://api.defhc.com/v4/odata-v4/RFP HTTP/1.1
Host: 
Authorization: Bearer {{token}}

Get Details 

curl -X GET -H "Authorization: Bearer {{token}}" "https://api.defhc.com/v4/odata-v4/RFPs({{RFPId}})"
GET https://api.defhc.com/v4/odata-v4/RFPs%28%7B%7BRFPId%7D%7D%29 HTTP/1.1
Host: 
Authorization: Bearer {{token}}

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/v4/Reports?returnType={{returnType}}"
GET https://api.defhc.com/v4/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/v4/Reports/{{customReportName}}"
GET https://api.defhc.com/v4/Reports/%7B%7BcustomReportName%7D%7D HTTP/1.1
Host: 
Authorization: Bearer {{token}}

Get my report

  • ReportName Optional, either assigned by Definitive Healthcare or End User
  • Page Optional (default =1 ), determined by End User to select a specific page of the report to return
  • ReturnType Optional (default = csv), determined by End User for the format of the report
  • PageSize Optional (default = 50000), determined by End User to set a specific page size maximum 
curl -X GET -H "Authorization: Bearer {{token}}" "https://api.defhc.com/v4/reports/{{reportName}}?pageSize={{pageSize}}&page={{page}}&returnType={{returnType}}"
GET https://api.defhc.com/v4/reports/%7B%7BreportName%7D%7D?pageSize={{pageSize}}&page={{page}}&returnType={{returnType}} HTTP/1.1
Host: 
Authorization: Bearer {{token}}

Accessing Reports with POSTMAN

Postman is a desktop app which can be easily and securely used to get the data from the API. These are the steps required to access Reports using POSTMAN.
  1. Download / install and sign up for postman through this link: https://www.getpostman.com/
  2. Make an authentication request to get an access token by replacing {{userName}} and {{password}} with your user name and the password to login to Definitive Healthcare, at www.defhc.com
  3. To retrieve a custom report or file created for you by the Definitive Healthcare team, replace {{customReportName}} with the report name to be downloaded (which the exact name would be provided to you by Definitive). In addition, copy the access_token delivered through the request made in step 2 and paste it in the header as following:
  4. To see all report names, use the same request as outlined in step 3 without inputting a specific report name.