openapi: 3.0.3
info:
title: Garner Health 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,\n\
physicians, 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`, \n\
and `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: []
paths:
/providers:
parameters:
- $ref: '#/components/parameters/acceptVersion'
- name: Request-ID
in: header
schema:
type: string
required: false
description: Correlation ID to be provided on responses
get:
operationId: GetRankedProviders
summary: Get a list of providers near a position
x-codeSamples:
- lang: curl
source: "curl -i -X GET \\\n 'https://api.getgarner.com/providers?gender=male&language=fas&lat=40.8144984&limit=30&lng=-74.259863&networkId=string&plan=core&specialty=adult_general_gastroenterologist'\
\ \\\n -H 'Accept-Version: 1' \\\n -H 'Authorization: Bearer <YOUR_API_TOKEN_HERE>' \\\n \
\ -H 'Request-ID: string'\n"
- lang: JavaScript
source: "const query = new URLSearchParams({\n gender: 'male',\n language: 'fas',\n lat: '40.8144984',\n\
\ lng: '-74.259863',\n limit: '30',\n networkId: 'string',\n plan: 'core',\n specialty:\
\ 'adult_general_gastroenterologist'\n}).toString();\n\nconst resp = await fetch(\n `https://api.getgarner.com/providers?${query}`,\n\
\ {\n method: 'GET',\n headers: {\n 'Accept-Version': '1',\n 'Request-ID':\
\ 'string',\n Authorization: 'Bearer <YOUR_API_TOKEN_HERE>'\n }\n }\n);\n\nconst data\
\ = await resp.text();\nconsole.log(data);\n"
description: "This endpoint supports two modes of querying. Depending on the query parameter you\
\ provide, a different result\nwill be returned.\n\n| Query Parameter | Search Mode | Query Type\
\ | Result Type |\n| -- | -- | -- | -- |\n| `specialty` | Ranked Search | `RankedProviderQuery`\
\ | `RankedProviderList` |\n| `name` | Directory Search | `DirectorySearchQuery` | `DirectorySearchResultList`\
\ |\n| `npi` | Directory Search | `DirectorySearchQuery` | `DirectorySearchResultList` |\n\n\n\
### Ranked Search (Primary)\n\nPerforms a ranked query for a specialty near a specific `Position`.\
\ This will return \nresults in rank-order, where the first `Provider` in the list is the most\
\ highly recommended based on distance, \nquality, cost, and patient reviews.\n\n### Directory\
\ Search (Secondary)\n\nPerforms a lookup for a professional by name or NPI near a specific Position;\
\ facilities are not currently \nsupported. **This will return results by relevance to the query.\
\ Providers returned are not necessarily\nrecommended by Garner.**\n"
parameters:
- name: QueryModeParams
in: query
explode: true
schema:
oneOf:
- $ref: '#/components/schemas/RankedProviderQuery'
- $ref: '#/components/schemas/DirectorySearchQuery'
responses:
'200':
description: Providers resolved successfully
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/RankedProviderList'
- $ref: '#/components/schemas/DirectorySearchResultList'
'422':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
/provider-annotations/{provider_id}:
parameters:
- $ref: '#/components/parameters/acceptVersion'
post:
operationId: CreateProviderAnnotations
summary: Annotate a Provider record for accuracy
parameters:
- name: provider_id
in: path
required: true
schema:
type: string
description: The Garner ID for the provider.
example: p.f3ac4f1a01275ca68e6c932ad4722491
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAnnotation.RequestBody'
responses:
'200':
description: Created annotations
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAnnotation.ResponseBody'
'422':
description: Annotation field not supported
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
/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'
/facilities/{facility_id}:
parameters:
- $ref: '#/components/parameters/acceptVersion'
get:
description: "This endpoint returns details about a single location of a facility including data\
\ for each of the facility's specialties \nand directory data for the requested location.\n\n\
Note that one facility ID can be related to many different locations. This endpoint \nwill only\
\ show data for one location of a facility, according to the location ID included on the request.\n"
operationId: GetFacility
summary: Get details about a facility
parameters:
- name: facility_id
in: path
required: true
schema:
type: string
description: The Garner ID for the facility. It will always have the prefix `f.`
pattern: ^f\.[0-9a-f]+$
example: f.l3ac4f1a01275ca68e6c932ad4722491
- name: location_id
required: true
description: The Garner location ID for a specific location of the requested facility ID.
in: query
schema:
type: string
- name: network_id
description: The list of networks to include on the facility response.
in: query
required: true
schema:
type: array
items:
type: string
responses:
'200':
description: Facility found
content:
application/json:
schema:
$ref: '#/components/schemas/Facility'
'404':
$ref: '#/components/responses/NotFound'
'422':
description: Missing required query parameter
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
components:
securitySchemes:
ApiToken:
type: http
scheme: bearer
bearerFormat: API_TOKEN
parameters:
acceptVersion:
name: Accept-Version
in: header
required: true
schema:
type: integer
enum:
- 1
description: The API major version.
schemas:
ServiceError:
type: object
properties:
requestId:
type: number
message:
type: string
data:
type: object
additionalProperties: true
required:
- message
additionalProperties: false
BaseQuery:
type: object
properties:
lat:
type: number
description: Latitude of the origin of the query. Must be combined with `lng`. Must not be combined
with `zipCode`
example: 40.8144984
lng:
type: number
description: Longitude of the origin of the query. Must be combined with `lat`. Must not be
combined with `zipCode`
example: -74.259863
zipCode:
format: '[0-9]{5}'
type: string
description: The center of this ZIP-5 code to use as the origin of the query. Must not be combined
with `lat` or `lng`
example: '10451'
plan:
type: string
description: The data subscription plan associated with your account. Contact your account manager
for the correct value to this parameter.
example: core
limit:
type: number
description: The maximum number of providers to include in the response. Defaults to 15.
example: 15
maximum: 30
default: 15
required:
- plan
RankedProviderQuery:
allOf:
- type: object
properties:
specialty:
type: string
description: Specialty code to query.
example: adult_general_gastroenterologist
networkId:
type: string
description: Filters results to a given carrier network when included.
gender:
type: string
enum:
- male
- female
description: Filters results to a given gender. If omitted, no gender filter will be applied.
language:
type: string
description: Filters results to require a given language to be spoken by the provider. If
omitted, no language filter will be applied. Must be provided as a [ISO639-3](https://iso639-3.sil.org/code_tables/639/data)
code.
example: fas
required:
- networkId
- $ref: '#/components/schemas/BaseQuery'
RankedProviderList:
type: object
properties:
providers:
type: array
items:
$ref: '#/components/schemas/RankedProvider'
description: The result list of providers (professionals or facilities) for the request. The
providers are in rank order.
required:
- providers
RankedProvider:
type: object
properties:
id:
type: string
description: Unique identifier for the provider
npi:
type: string
description: National Provider Identifier
firstName:
type: string
description: First name of the provider. Only returned if provider is a professional rather
than a facility
lastName:
type: string
description: Last name of the provider. Only returned if provider is a professional rather than
a facility
credentials:
type: string
description: Degrees and certifications held by the provider. Only returned if provider is a
professional rather than a facility
example: MD
gender:
$ref: '#/components/schemas/Gender'
specialty:
type: string
description: The specialty identifier for the provider
example: adult_general_gastroenterologist
organizationName:
type: string
description: Name of the facility. Only returned if provider is a facility rather than a professional
example: Mount Sinai
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. Only returned if provider is a professional rather than a facility,
metrics:
description: Relevant metrics for the query. Will be repeated for each provider ranked for ease
of comparison.
type: array
items:
type: object
properties:
id:
type: string
description: Metric descriptor
example: id="Patient Outcomes"
value:
type: string
enum:
- good
- very_good
- excellent
description: Performance on the metric. Providers will only be recommended by the API
if they have at least a score of `good` on each metric
overallScore:
description: Score for the provider taking into account overall quality and cost
type: integer
minimum: 0
maximum: 100
reviewStars:
description: Star-rating synthesizing the patient reviews for the provider
type: number
minimum: 1
maximum: 5
location:
$ref: '#/components/schemas/Location'
hours:
type: array
items:
$ref: '#/components/schemas/WorkingHours'
phoneNumber:
type: string
format: '[0-9]{10}'
description: 10-digit phone number
example: 5555555555
faxNumber:
type: string
format: '[0-9]{10}'
description: 10-digit fax number
example: 5555555555
distanceMi:
type: number
description: The driving distance to the location in miles
required:
- costScore
- distanceMi
- id
- location
- phoneNumber
- specialty
additionalProperties: false
description: A ranked provider
example:
id: p.f3ac4f1a01275ca68e6c932ad4722491
npi: 1231766309
firstName: Sepideh
lastName: Baghian
credentials: MD
gender: female
specialty: adult_general_gastroenterologist
languages:
- eng
- fas
metrics:
- id: accurately_diagnoses_gi_issues
value: very_good
- id: performs_safe_colonoscopies
value: excellent
- id: great_patient_outcomes
value: good
overallScore: 92
reviewStars: 4.5
location:
id: fc8b2f21-506c-5c7c-a96f-a4580bd9ba87
name: Mount Sinai Morningside Cardiovascular Institute
providerCorporationName: Mount Sinai Health System
allProviderCorporations:
- Mount Sinai Health System
- NYC Health + Hospitals
city: New York
lines:
- 440 W 114th St 2nd Fl Ste 220
position:
lat: 40.8053
lng: -73.9618
state: NY
zipCode: '10025'
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
phoneNumber: '2124271540'
faxNumber: '2124107196'
distanceMi: 3.50453352288
DirectorySearchQuery:
allOf:
- type: object
properties:
name:
type: string
description: Name or partial name of the provider. Must not be combined with `npi`
example: Mark Smith
npi:
format: '[0-9]{9}'
type: string
description: The unique identifier for the provider. Must not be combined with `name`
example: 123456789
networkId:
type: string
description: "When included, the `networkStatus` attribute of the result will indicate whether\
\ the physician is \nin-network with the given network.\n"
gender:
type: string
enum:
- male
- female
description: Filters results to a given gender. If omitted, no gender filter will be applied.
language:
type: string
description: Filters results to require a given language to be spoken by the provider. If
omitted, no language filter will be applied. Must be provided as a [ISO639-3](https://iso639-3.sil.org/code_tables/639/data)
code.
example: fas
required:
- networkId
- $ref: '#/components/schemas/BaseQuery'
DirectorySearchResultList:
type: object
properties:
providers:
type: array
items:
$ref: '#/components/schemas/ProviderDirectoryEntry'
description: The result list of professionals for the request.
required:
- providers
ProviderDirectoryEntry:
type: object
properties:
id:
type: string
description: Unique identifier for the provider
npi:
type: string
description: National Provider Identifier
firstName:
type: string
description: First name of the provider.
lastName:
type: string
description: Last name of the provider.
credentials:
type: string
description: Degrees and certifications held by the provider. Only returned if provider is a
professional rather than a facility
example: MD
gender:
$ref: '#/components/schemas/Gender'
specialty:
type: string
description: The specialty identifier for the provider
example: adult_general_gastroenterologist
networkStatus:
type: boolean
description: Whether the doctor is in-network with the network specified in the query parameters
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. Only returned if provider is a professional rather than a facility
location:
$ref: '#/components/schemas/Location'
hours:
type: array
items:
$ref: '#/components/schemas/WorkingHours'
phoneNumber:
type: string
format: '[0-9]{10}'
description: 10-digit phone number
example: 5555555555
faxNumber:
type: string
format: '[0-9]{10}'
description: 10-digit phone number
example: 5555555555
distanceMi:
type: number
description: The driving distance to the location in miles
required:
- distanceMi
- id
- location
- phoneNumber
- specialty
additionalProperties: false
description: A ranked provider
example:
id: p.f3ac4f1a01275ca68e6c932ad4722491
npi: 1231766309
firstName: Sepideh
lastName: Baghian
credentials: MD
gender: female
specialty: adult_general_gastroenterologist
languages:
- eng
- fas
location:
id: fc8b2f21-506c-5c7c-a96f-a4580bd9ba87
name: Mount Sinai Morningside Cardiovascular Institute
providerCorporationName: Mount Sinai Health System
allProviderCorporations:
- Mount Sinai Health System
- NYC Health + Hospitals
city: New York
lines:
- 440 W 114th St 2nd Fl Ste 220
position:
lat: 40.8053
lng: -73.9618
state: NY
zipCode: '10025'
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
phoneNumber: '2124271540'
faxNumber: '2124107196'
distanceMi: 3.50453352288
networkStatus: true
Location:
description: The office location of a provider
type: object
properties:
id:
type: string
description: The unique identifier for this location
name:
type: string
description: Name of the office or facility for the associated location and provider. Only returned
if provider is a professional rather than a facility
providerCorporationName:
type: string
description: The primary provider corporation (e.g. health system) affiliated with this location.
When both `providerCorporationName` and `allProviderCorporations` are present, the value here
is also included in `allProviderCorporations`. Only returned when the provider is a professional
and the corporation is known.
example: NYU Langone Health
allProviderCorporations:
type: array
items:
type: string
description: All provider corporations (e.g. health systems) the professional is affiliated
with at this location. When `providerCorporationName` is also returned, it is the primary
entry in this list. Only returned when the provider is a professional and at least one affiliation
is known.
example:
- NYU Langone Health
- Mount Sinai Health System
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
position:
$ref: '#/components/schemas/Position'
required:
- lines
- city
- state
- zipCode
- position
additionalProperties: false
Position:
description: Global coordinates
type: object
properties:
lat:
type: number
description: Latitude
lng:
type: number
description: Longitude
required:
- lat
- lng
additionalProperties: false
Gender:
type: string
enum:
- male
- female
description: Gender. Only returned if provider is a professional rather than a facility
DayOfWeek:
type: number
enum:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
description: ISO day of week (e.g. 1 is Monday)
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
AnnotationField:
type: string
enum:
- specialty
- phoneNumber
- firstName
- lastName
- locationName
- gender
- credentials
- faxNumber
- street1
- street2
- city
- state
- zipCode
Annotation:
type: object
properties:
field:
$ref: '#/components/schemas/AnnotationField'
description: key of the field to be annotated
example: phoneNumber
value:
anyOf:
- type: string
- type: object
additionalProperties:
type: string
description: value of the field that is being annotated. It can either be a string or an object.
example: 2121126544
isCorrect:
type: boolean
description: indicates whether the current value is correct or incorrect
example: false
correctedValue:
anyOf:
- type: string
- type: object
additionalProperties:
type: string
description: Corrected value of the annotated field
example: 2121126542
required:
- field
- value
- isCorrect
additionalProperties: false
CreateAnnotationParams:
type: object
properties:
locationId:
type: string
description: id of the provider's location
example: c52305b90e2a5ce08ce6f0a621acd22f
annotations:
type: array
items:
$ref: '#/components/schemas/Annotation'
description: List of annotations for the provider record
example:
- field: phoneNumber
isCorrect: false
value: 2121126544
correctedValue: 2121126542
required:
- locationId
- annotations
additionalProperties: false
CreateAnnotation.RequestBody:
$ref: '#/components/schemas/CreateAnnotationParams'
CreateAnnotation.ResponseBody:
type: object
properties:
count:
type: number
description: Number of annotations created
example: 1
required:
- count
additionalProperties: false
description: Returns number of annotations created
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:
descript
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/garner-health/refs/heads/main/openapi/garner-health-openapi-original.yml