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
    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
    Position:
      description: Global coordinates
      type: object
      properties:
        lat:
          type: number
          description: Latitude
        lng:
          type: number
          description: Longitude
      required:
      - lat
      - lng
      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
    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
    DayOfWeek:
      type: number
      enum:
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      - 7
      description: ISO day of week (e.g. 1 is Monday)
    ServiceError:
      type: object
      properties:
        requestId:
          type: number
        message:
          type: string
        data:
          type: object
          additionalProperties: true
      required:
      - message
      additionalProperties: false
    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
    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
    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
    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
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServiceError'
  parameters:
    acceptVersion:
      name: Accept-Version
      in: header
      required: true
      schema:
        type: integer
        enum:
        - 1
      description: The API major version.
  securitySchemes:
    ApiToken:
      type: http
      scheme: bearer
      bearerFormat: API_TOKEN