Garner Health Professionals API

openapi: 3.2.0
info:
  title: Garner Health Professionals API
  version: v1.11.0
  license:
    name: Commercial
    url: https://getgarner.com
  description: Garner's APIs power its core provider recommendation experience.
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,

        and directory data for each location at which the professional practices.'
      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:
    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
    ServiceError:
      type: object
      properties:
        requestId:
          type: number
        message:
          type: string
        data:
          type: object
          additionalProperties: true
      required:
      - message
      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
    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
    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
    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
    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
    Position:
      description: Global coordinates
      type: object
      properties:
        lat:
          type: number
          description: Latitude
        lng:
          type: number
          description: Longitude
      required:
      - lat
      - lng
      additionalProperties: false
    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
  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