openapi: 3.0.3
info:
title: Garner Health Facilities Professionals API
version: v1.11.0
license:
name: Commercial
url: https://getgarner.com
description: "Garner's APIs power its core provider recommendation experience. These recommendations are based on over 60 billion\nanonymized health insurance claims that paint a clear picture of a patient's journey through the healthcare system. \n\nUsing these data, Garner evaluates whether physicians practice evidence-based medicine as defined by major,\nrespected healthcare journals. Garner has designed over 550 clinical and financial metrics that look closely\nat every decision a physician makes rather than relying on standard industry episode groupers. This results in\nrankings that are much more transparent and trustworthy and enable better-informed decisions for patients,\nphysicians, and payers.\n\n# Authentication: \n \n## OAuth2.0\n\n*If you were provided a JWT at account setup rather than an API client id and client secret, please refer to instructions for [legacy token authentication.](#section/Authentication:/Legacy-token)*\n\nGarner APIs authenticate with OAuth 2.0 access tokens. You will be provided an API client ID and API client secret during account setup. \nThe client ID and client secret can be exchanged for an access token which in turn authenticates your app when making calls to Garner's APIs. \n\nTo obtain an access token, make a request to the `POST oauth2/token/` endpoint. In the request body, include the `client_id`, `client_secret`, \nand `grant_type=client_credentials`. This response will contain an `access_token`, the `token_type` which will always be \"Bearer\", \nand `expires_in` which is the lifetime in seconds of the token. \n\nThe access token can be used to authenticate with Garner's APIs. When making a request, provide the access token as a \nbearer token in the `Authorization` header. \n\nFor example, \n\n**JavaScript**\n```js\n/* Get the token */\nconst { access_token, token_type, expires_in } = await fetch('https://api.getgarner.com/oauth2/token', {\n method: 'POST',\n headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n body: new URLSearchParams({\n grant_type: 'client_credentials',\n client_id: '<YOUR_API_CLIENT_ID_HERE>',\n client_secret: '<YOUR_API_CLIENT_SECRET_HERE>',\n }),\n}).then(r => r.json());\n\n\n/* Use the token */\nconst { providers } = fetch(\n 'https://api.getgarner.com/providers',\n {\n method: 'GET',\n headers: {'Authorization': `Bearer ${<YOUR_ACCESS_TOKEN_HERE>}`},\n query: ...\n },\n).then(response => response.json());\n\n``` \n**cURL**\n```sh\n# Get the token\ncurl --location 'https://api.garner.health/oauth2/token' \\\n--header 'Content-Type: application/x-www-form-urlencoded' \\\n--data-urlencode 'grant_type=client_credentials' \\\n--data-urlencode 'client_id=<YOUR_API_CLIENT_ID_HERE' \\\n--data-urlencode 'client_secret=<YOUR_API_CLIENT_SECRET_HERE>'\n\n# Use the token\ncurl -G https://api.getgarner.com/providers -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN_HERE>'\n```\n\n\n### Managing the access token\nThe access token will only be valid for 15 minutes. We recommend caching the token in your application so that it can be reused up to its expiration. This can be managed by the app programmatically by implementing a `GarnerTokenClient` class like the following:\n```typescript\nclass GarnerTokenClient {\n /** Cached access token */\n private currentToken: string | undefined;\n /** Time at which the cached token expires */\n private expirationTime: number | undefined;\n\n /** \n * Fetches a new access token from the `POST /oauth2/token` endpoint,\n * then caches the token and its expiration time.\n * Returns a promise that resolves to the newly fetched access token\n */\n private async fetchNewToken(): Promise<string> {\n const currentTime = Date.now();\n const { access_token: accessToken, expires_in: expiresIn } = await fetch('https://api.getgarner.com/oauth2/token', {\n method: 'POST',\n headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n body: new URLSearchParams({\n grant_type: 'client_credentials',\n client_id: '<YOUR_API_CLIENT_ID_HERE>',\n client_secret: '<YOUR_API_CLIENT_SECRET_HERE>',\n }),\n }).then(r => r.json());\n // Cache the access token\n this.currentToken = accessToken;\n // Set the expiration time as the current time plus the number of ms until the token expires. Subtract a 15 second buffer to account for lag.\n this.expirationTime = (currentTime + expiresIn * 1000) - 15000; \n return accessToken;\n }\n\n /** \n * Returns the cached access token if it is valid. \n * Otherwise, fetches a new token.\n */\n async getToken(): Promise<string> {\n if (this.currentToken && this.expirationTime && Date.now() < this.expirationTime) {\n return this.currentToken;\n }\n return await this.fetchNewToken();\n }\n}\n```\n\nThen when making a request to Garner's APIs you can use the response of `getToken()` from an instance of the `GarnerTokenClient` class as your token.\n\nFor example, \n\n```typescript\nconst garnerTokenClient = new GarnerTokenClient();\n\nfetch('https://api.getgarner.com/providers',\n {\n method: 'GET',\n headers: {'Authorization': `Bearer ${await garnerTokenClient.getToken()}`},\n query: ...\n },\n);\n\n```\n## Legacy token\n\n*If you were provided an API client id and client secret at account setup rather than a token, please refer to instructions for [OAuth2.0 authentication.](#section/Authentication:/OAuth2.0)*\n\nAuthenticating is done with an JSON Web Token (JWT) provided as a `Bearer` token to the `Authorization` header.\nYou will have received a token during account setup.\n\nFor example, \n```sh\ncurl -G https://api.getgarner.com -H 'Authorization: Bearer <YOUR_API_TOKEN_HERE>'\n```\n"
servers:
- url: https://api.getgarner.com
security:
- ApiToken: []
tags:
- name: Professionals
paths:
/professionals/{professional_id}:
parameters:
- $ref: '#/components/parameters/acceptVersion'
get:
operationId: GetProfessional
summary: Get details about a professional
description: "This endpoint returns details about a single professional including quality data for each of the professional's specialties, \nand directory data for each location at which the professional practices.\n"
parameters:
- name: professional_id
in: path
required: true
schema:
type: string
description: The Garner ID for the professional. It will always have the prefix `p.`
pattern: ^p\.[0-9a-f]+$
example: p.f3ac4f1a01275ca68e6c932ad4722491
- name: network_id
description: The list of networks to include on the professional response.
in: query
required: true
schema:
type: array
items:
type: string
responses:
'200':
description: Professional found
content:
application/json:
schema:
$ref: '#/components/schemas/Professional'
'404':
$ref: '#/components/responses/NotFound'
'422':
description: Missing required query parameter
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
tags:
- Professionals
components:
schemas:
WorkingHours:
description: The days and times of day the provider's office is open
type: object
properties:
day:
$ref: '#/components/schemas/DayOfWeek'
open:
type: number
description: The time of day the office opens. Represented as minutes after midnight
close:
type: number
description: The time of day the office closes. Represented as minutes after midnight
Professional:
type: object
properties:
id:
type: string
pattern: ^p\.[0-9a-f]+$
description: Unique identifier for the provider
npi:
type: string
description: National Provider Identifier
first_name:
type: string
description: First name of the provider
last_name:
type: string
description: Last name of the provider
sex:
type: string
enum:
- female
- male
description: Sex of the provider
credentials:
type: string
description: Degrees and certifications held by the provider
review_stars:
description: Star-rating synthesizing the patient reviews for the provider
type: number
minimum: 1
maximum: 5
languages:
type: array
items:
type: string
format: '[a-z]{3}'
description: List of languages spoken by the provider. Languages are [ISO639-3](https://iso639-3.sil.org/code_tables/639/data) codes
metrics:
type: array
items:
$ref: '#/components/schemas/Metric'
description: All metrics associated with all specialties practiced by the provider
specialties:
type: object
additionalProperties:
x-additionalPropertiesName: specialty
$ref: '#/components/schemas/ProfessionalSpecialty'
description: A map of all specialties practiced by the provider keyed by the specialty identifier
locations:
description: Map of all office locations of the provider keyed by the location id
type: object
additionalProperties:
x-additionalPropertiesName: location_id
$ref: '#/components/schemas/ProfessionalLocation'
required:
- id
- npi
- first_name
- last_name
- sex
- specialties
- locations
additionalProperties: false
example:
id: p.f3ac4f1a01275ca68e6c932ad4722491
npi: 1231766309
first_name: Sepideh
last_name: Baghian
credentials: MD
review_stars: 4.78
sex: female
languages:
- eng
- fas
metrics:
- id: accurately_diagnoses_gi_issues
name: Accurate Diagnosis
value: very_good
- id: performs_safe_colonoscopies
name: Procedure Safety
value: excellent
- id: great_patient_outcomes
name: Patient Outcomes
value: good
specialties:
adult_general_gastroenterologist:
overallScore: 92
locations:
- location_id: fc8b2f21-506c-5c7c-a96f-a4580bd9ba87
networks:
- network_id: aetna
is_in_network: true
is_top_provider: false
- network_id: cigna
is_in_network: true
is_top_provider: true
- location_id: 0372c41d-3a13-5094-9a12-a1e0e1ce5a64
networks:
- network_id: aetna
is_in_network: true
is_top_provider: true
- network_id: cigna
is_in_network: false
is_top_provider: false
adult_primary_care_physician:
overallScore: 97
locations:
- location_id: fc8b2f21-506c-5c7c-a96f-a4580bd9ba87
networks:
- network_id: aetna
is_in_network: true
is_top_provider: true
- network_id: cigna
is_in_network: false
is_top_provider: false
- location_id: 0372c41d-3a13-5094-9a12-a1e0e1ce5a64
networks:
- network_id: aetna
is_in_network: true
is_top_provider: true
- network_id: cigna
is_in_network: false
is_top_provider: false
locations:
fc8b2f21-506c-5c7c-a96f-a4580bd9ba87:
lines:
- 440 W 114th St 2nd Fl Ste 220
city: New York
state: NY
zip_code: '10025'
position:
lat: 40.8053
lng: -73.9618
hours:
- day: 1
open: 480
close: 1020
- day: 2
open: 480
close: 1020
- day: 3
open: 480
close: 1020
- day: 4
open: 480
close: 1020
- day: 5
open: 480
close: 1020
phone_number: '2124271540'
fax_number: '2124107196'
name: Mount Sinai Morningside Cardiovascular Institute
provider_corporation_name: Mount Sinai Health System
all_provider_corporations:
- Mount Sinai Health System
- NYC Health + Hospitals
accepts_new_patients: true
availability_within_weeks: 2
0372c41d-3a13-5094-9a12-a1e0e1ce5a64:
lines:
- 1090 Amsterdam Ave
city: New York
state: NY
zip_code: '10025'
position:
lat: 40.805222
lng: -73.962477
hours:
- day: 1
open: 480
close: 1020
- day: 4
open: 480
close: 1020
- day: 5
open: 480
close: 1020
phone_number: '2125328762'
fax_number: '2125328777'
name: Mount Sinai
provider_corporation_name: Mount Sinai Health System
all_provider_corporations:
- Mount Sinai Health System
accepts_new_patients: false
availability_within_weeks: null
ProfessionalLocation:
allOf:
- $ref: '#/components/schemas/LocationBase'
- type: object
properties:
name:
description: Name of the office or facility for the associated location and provider
type: string
accepts_new_patients:
description: Whether the provider is accepting new patients at the location
type: boolean
availability_within_weeks:
description: The number of weeks out a provider is scheduling new patients, if known
type: integer
provider_corporation_name:
type: string
description: The primary provider corporation (e.g. health system) affiliated with this location. When both `provider_corporation_name` and `all_provider_corporations` are present, the value here is also included in `all_provider_corporations`. Only present when the corporation is known.
example: NYU Langone Health
all_provider_corporations:
type: array
items:
type: string
description: All provider corporations (e.g. health systems) the professional is affiliated with at this location. When `provider_corporation_name` is also present, it is the primary entry in this list. Only present when at least one affiliation is known.
example:
- NYU Langone Health
- Mount Sinai Health System
required:
- accepts_new_patients
additionalProperties: false
additionalProperties: false
ServiceError:
type: object
properties:
requestId:
type: number
message:
type: string
data:
type: object
additionalProperties: true
required:
- message
additionalProperties: false
LocationBase:
type: object
properties:
lines:
type: array
items:
type: string
description: The lines of an address, in order
city:
type: string
description: The city of the address
state:
type: string
description: The state of the address
zip_code:
type: string
description: The zip code of the address
position:
$ref: '#/components/schemas/Position'
hours:
description: The days and times of day the provider's office is open
type: array
items:
$ref: '#/components/schemas/WorkingHours'
phone_number:
type: string
format: '[0-9]{10}'
description: 10-digit phone number
example: 5555555555
fax_number:
type: string
format: '[0-9]{10}'
description: 10-digit fax number
example: 5555555555
additionalProperties: false
required:
- lines
- city
- state
- zip_code
- position
Metric:
type: object
properties:
id:
type: string
description: Metric descriptor
example: accurately_diagnoses_gi_issues
name:
type: string
description: Metric category
example: Accurate Diagnosis
value:
type: string
enum:
- good
- very_good
- excellent
description: Performance on the metric.
example: very_good
required:
- id
- name
- value
additionalProperties: false
ProfessionalNetwork:
allOf:
- $ref: '#/components/schemas/FacilityNetwork'
- type: object
properties:
is_top_provider:
type: boolean
description: Whether the provider is a top provider for the given specialty at the given location within the given network, taking into account cost and quality.
required:
- is_top_provider
additionalProperties: false
ProfessionalSpecialty:
type: object
properties:
overall_score:
description: Score for the provider in the given specialty taking into account overall quality and cost
type: integer
minimum: 0
maximum: 100
locations:
type: array
description: List of locations where the provider practices the given specialty
items:
$ref: '#/components/schemas/ProfessionalSpecialtyLocation'
additionalProperties: false
required:
- locations
DayOfWeek:
type: number
enum:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
description: ISO day of week (e.g. 1 is Monday)
Position:
description: Global coordinates
type: object
properties:
lat:
type: number
description: Latitude
lng:
type: number
description: Longitude
required:
- lat
- lng
additionalProperties: false
FacilityNetwork:
type: object
properties:
network_id:
type: string
description: Unique identifier for the network
is_in_network:
type: boolean
description: Whether the provider is in network for the given specialty at the given location
required:
- network_id
- is_in_network
additionalProperties: false
ProfessionalSpecialtyLocation:
type: object
properties:
location_id:
type: string
description: Unique identifier for an office location. Can be used to obtain address information from the top level `locations` map
networks:
type: array
description: List of networks included on the request. Each network will show both in-network and top-provider status
items:
$ref: '#/components/schemas/ProfessionalNetwork'
additionalProperties: false
required:
- location_id
- networks
parameters:
acceptVersion:
name: Accept-Version
in: header
required: true
schema:
type: integer
enum:
- 1
description: The API major version.
responses:
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
securitySchemes:
ApiToken:
type: http
scheme: bearer
bearerFormat: API_TOKEN