NexHealth Providers API

openapi: 3.2.0
info:
  title: NexHealth Adjustment Types Providers API
  description: v3.0.0 and v20240412 are two names for the same API version; the Nex-Api-Version header accepts either value. Welcome to the developer hub and documentation for NexHealth API. This section of guide describes the operations, response parameters, request parameters, and parameter constraints related to User API. The term Operations refer to functions or methods. The operations are included in requests and send to the web server. Each operation performs a different action or a query on database.
  termsOfService: https://www.nexhealth.com/terms-of-service
  contact:
    name: NexHealth
    email: info@nexhealth.com
  license:
    name: NexHealth License 1.0
    url: https://www.nexhealth.com/privacy
  version: v20240412
servers:
- url: https://nexhealth.info
security:
- Authorization: []
tags:
- name: Providers
  description: A providers resource
paths:
  /providers:
    get:
      summary: View providers
      description: This endpoint returns the providers for the institution, narrowed down by the optional filters configured.
      parameters:
      - in: header
        name: Nex-Api-Version
        description: The NexHealth API version
        required: true
        schema:
          type: string
          default: v3.0.0
      - in: query
        name: subdomain
        description: Used to scope the request to the specified institution
        required: true
        schema:
          type: string
      - in: query
        name: start_cursor
        description: First item of the current page. Starts empty
        required: false
        schema:
          type: string
      - in: query
        name: end_cursor
        description: Last item of the current page. Starts empty
        required: false
        schema:
          type: string
      - in: query
        name: per_page
        description: Number of results to return per page. Maximum allowed amount is 1000.
        required: false
        schema:
          type: integer
          format: int32
          default: 5
      - in: query
        name: sort
        description: "Optional comma-separated string of fields to sort on.\nInclude a leading dash for descending order.\n\nAvailable fields:\n  * updated_at\n  * -updated_at\n"
        required: false
        schema:
          type: string
      - in: query
        name: location_id
        description: Only return providers associated with the specified Location Id
        required: false
        example: 1
        schema:
          type: integer
          format: int32
      - in: query
        name: foreign_id
        description: Unique provider id from the EHR
        required: false
        example: '100437'
        schema:
          type: string
      - in: query
        name: requestable
        description: Only return providers who are bookable via NexHealth online booking at the specified location_id
        required: false
        example: true
        schema:
          type: boolean
      - in: query
        name: inactive
        description: Filter result set based on inactive status, defaults to false if not specified
        required: false
        example: false
        schema:
          type: boolean
          default: false
      - in: query
        name: updated_since
        description: Query providers whose records have updated since the specified datetime in ISO8601 format. Must be a parseable Date, recommended formats are YYYY-MM-DD or YYYY-MM-DDThh:mm:ss+0000
        required: false
        example: '2024-04-12T10:30:00Z'
        schema:
          type: string
          format: date-time
      - in: query
        name: include[]
        description: Resources to be included in the response
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - locations
            - availabilities
            - appointment_types
            default: locations
      - in: query
        name: ids[]
        description: NexHealth IDs
        required: false
        example:
        - 83
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
            format: int32
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_V20240412_Entities_ProviderWithResources_Collection_Response_WithCursor'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Errors_BadRequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Errors_Unauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Errors_Forbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Errors_NotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Errors_InternalServerError'
      tags:
      - Providers
      operationId: getProviders
  /providers/{id}:
    get:
      summary: View provider
      description: This endpoint returns a single provider.
      parameters:
      - in: header
        name: Nex-Api-Version
        description: The NexHealth API version
        required: true
        schema:
          type: string
          default: v3.0.0
      - in: path
        name: id
        description: The NexHealth id of the Provider
        required: true
        schema:
          type: integer
          format: int32
      - in: query
        name: subdomain
        description: Used to scope the request to the specified institution
        required: true
        schema:
          type: string
      - in: query
        name: include[]
        description: Resources to be included in the response
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - locations
            - availabilities
            - appointment_types
            default: locations
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_V20240412_Entities_ProviderWithResources_Response'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Errors_BadRequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Errors_Unauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Errors_Forbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Errors_NotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Errors_InternalServerError'
      tags:
      - Providers
      operationId: getProvidersId
components:
  schemas:
    API_V20240412_Entities_ProviderWithResources_Response:
      type: object
      properties:
        code:
          type: boolean
          example: false
          description: Indicates the success or failure of the request
        description:
          type: string
          example: Description
          description: Additional context on the request to help with debugging.
        error:
          type: array
          items:
            type: string
          example:
          - Error message
          description: Any errors that occur during the execution of the request.
        data:
          $ref: '#/components/schemas/API_V20240412_Entities_ProviderWithResources'
        count:
          type: integer
          format: int32
          example: 2
          description: Number of total objects, in case of collection.
      description: API_V20240412_Entities_ProviderWithResources_Response model
    API_V2_Entities_ProviderRequestable:
      type: object
      properties:
        location_id:
          type: integer
          format: int32
          example: 4
          description: Location id
    API_V20240412_Entities_ProviderWithResources:
      type: object
      properties:
        id:
          type: integer
          format: int32
          example: 415
          description: User id
        email:
          type:
          - string
          - 'null'
          example: Amy.Ramos@nexhealth.com
          description: User email
        first_name:
          type: string
          example: John
          description: First name
        middle_name:
          type:
          - string
          - 'null'
          example: Anthony
          description: Middle name
        last_name:
          type: string
          example: Smith
          description: Last name
        name:
          type: string
          example: John Smith
          description: Full name
        created_at:
          type: string
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: User creation date in UTC
        updated_at:
          type: string
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: User last updation date in UTC
        institution_id:
          type: integer
          format: int32
          example: 105
          description: The institution this user belongs to
        foreign_id:
          type:
          - string
          - 'null'
          example: '100437'
          description: Foreign Id is a unique identifier from the integrated system
        foreign_id_type:
          type: string
          example: --DataSource-
          description: Foreign Id type is a unique string identifier for the integrated system
        bio:
          type: object
          example:
            city: New York
            state: NY
            gender: Female
            zip_code: '20814'
            new_patient: false
            non_patient: true
            phone_number: '5163042196'
            date_of_birth: '1964-05-03'
            address_line_1: ''
            address_line_2: ''
            street_address: ''
            cell_phone_number: ''
            home_phone_number: ''
            work_phone_number: ''
          description: Patient biographical data, fields shown in our example response represent all possible data we retrieve but depending on system and what is actually saved in the health records system you cannot assume any field will consistently be returned
        inactive:
          type: boolean
          example: false
          description: Is the user inactivated?
        last_sync_time:
          type:
          - string
          - 'null'
          format: date-time
          example: '2024-04-12T10:30:00Z'
          description: The most recent time the resource's data changed meaningfully at the source
        display_name:
          type:
          - string
          - 'null'
          example: John Smith
          description: Display name
        npi:
          type:
          - string
          - 'null'
          example: '1912507500'
          description: National Provider Identifier as registered in NPPES. May be null if the practice did not enter it into the integrated system.
        tin:
          type:
          - string
          - 'null'
          example: 078051120
          description: Taxpayer Identification Number (SSN or ITIN). May be null if the practice did not enter it into the integrated system.
        state_license:
          type:
          - string
          - 'null'
          example: R219935
          description: State license number. May be null if the practice did not enter it into the integrated system.
        specialty_code:
          type:
          - string
          - 'null'
          example: 363L00000X
          description: Specialty code corresponding to the provider's state license and NPI. May be null if the practice did not enter it into the integrated system.
        locations:
          type: array
          items:
            $ref: '#/components/schemas/API_Entities_Location'
          description: Locations the provider is associated with
        provider_requestables:
          type: array
          items:
            $ref: '#/components/schemas/API_V2_Entities_ProviderRequestable'
          description: List of locations this provider can be booked with at
        availabilities:
          type: array
          items:
            $ref: '#/components/schemas/API_V20240412_Entities_WorkingHourWithAppointmentTypes'
          description: List of availabilities for the provider, each with its associated appointment types
    API_V20240412_Entities_WorkingHourWithAppointmentTypes:
      type: object
      properties:
        id:
          type: integer
          format: int32
          example: 12
          description: Resource id
        provider_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 7
          description: Provider id
        location_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 3
          description: Location id
        operatory_id:
          type:
          - integer
          - 'null'
          format: int64
          example: 149
          description: Operatory id
        begin_time:
          type: string
          example: '10:30'
          description: Availability start time in the practices timezone
        end_time:
          type: string
          example: '17:00'
          description: Availability end time in the practices timezone
        days:
          type:
          - array
          - 'null'
          items:
            type: string
          example:
          - Monday
          - Tuesday
          - Wednesday
          - Thursday
          - Friday
          description: Configured week days. Empty when the working hour is configured for a custom recurrence
        specific_date:
          type:
          - string
          - 'null'
          format: date
          example: '2022-11-03'
          description: Configured specific date
        custom_recurrence:
          type:
          - object
          - 'null'
          example:
            num: 3
            unit: day
            ref: '2022-11-03'
          description: Configured custom recurrence, with the fields num (recurrence interval count), ref (starting date), and unit (day, week, or month)
        tz_offset:
          type: string
          example: '-0700'
          description: UTC offset for the practice
        active:
          type: boolean
          example: true
          description: Is active?
        source:
          type: string
          enum:
          - manual
          - synced
          example: synced
          description: Source of the working hour
        label:
          $ref: '#/components/schemas/API_V20240412_Entities_WorkingHourLabel'
        appointment_types:
          type: array
          items:
            $ref: '#/components/schemas/API_V2_Entities_AppointmentTypeBasic'
          description: Associated appointment types
    API_V20240412_Entities_WorkingHourLabel:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 113
          description: Resource id
        location_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 115
          description: The location ID
        name:
          type: string
          example: New patient appointments
          description: The name for working hour label
    API_V2_Entities_AppointmentTypeBasic:
      type: object
      properties:
        id:
          type: integer
          format: int32
          example: 1
          description: Appointment type Id
        name:
          type: string
          example: Medical
          description: Appointment type name. Unique string identifier
        parent_type:
          type: string
          example: Institution
          description: Parent type for appointment type. Defines the belongs to relationship with either Institution or Location
        parent_id:
          type: integer
          format: int32
          example: 1
          description: Identifies the specific resource the appointment type belongs to (see parent_type)
        minutes:
          type: integer
          format: int32
          example: 15
          description: Default duration of appointments of this appointment type
        bookable_online:
          type: boolean
          example: false
          description: True if this appointment type should be bookable via the NexHealth online booking page
    API_Errors_Unauthorized:
      type: object
      properties:
        code:
          type: boolean
          description: Indicates the success or failure of the request.
        description:
          type: string
          description: Additional context about the request to help with debugging.
        data:
          type: object
        error:
          type: array
          items:
            type: string
          description: Any errors that occured during the execution of the request.
      description: API_Errors_Unauthorized model
    API_Errors_BadRequest:
      type: object
      properties:
        code:
          type: boolean
          description: Indicates the success or failure of the request.
        description:
          type: string
          description: Additional context about the request to help with debugging.
        data:
          type: object
        error:
          type: array
          items:
            type: string
          description: Any errors that occured during the execution of the request.
      description: API_Errors_BadRequest model
    API_Entities_Specialty:
      type: object
      properties:
        id:
          type: integer
          format: int32
          description: Specialty id
        name:
          type: string
          description: Specialty name
    API_V20240412_Entities_ProviderWithResources_Collection_Response_WithCursor:
      type: object
      properties:
        code:
          type: boolean
          example: false
          description: Indicates the success or failure of the request
        description:
          type: string
          example: Description
          description: Additional context on the request to help with debugging.
        error:
          type: array
          items:
            type: string
          example:
          - Error message
          description: Any errors that occur during the execution of the request.
        data:
          type: array
          items:
            $ref: '#/components/schemas/API_V20240412_Entities_ProviderWithResources'
        page_info:
          type: object
          example:
            has_previous_page: false
            has_next_page: false
            start_cursor: AAAAA
            end_cursor: BBBBBB
          description: Pagination information that can be used for fetching previous and next pages.
      description: API_V20240412_Entities_ProviderWithResources_Collection_Response_WithCursor model
    API_Errors_Forbidden:
      type: object
      properties:
        code:
          type: boolean
          description: Indicates the success or failure of the request.
        description:
          type: string
          description: Additional context about the request to help with debugging.
        data:
          type: object
        error:
          type: array
          items:
            type: string
          description: Any errors that occured during the execution of the request.
      description: API_Errors_Forbidden model
    API_Errors_NotFound:
      type: object
      properties:
        code:
          type: boolean
          description: Indicates the success or failure of the request.
        description:
          type: string
          description: Additional context about the request to help with debugging.
        data:
          type: object
        error:
          type: array
          items:
            type: string
          description: Any errors that occured during the execution of the request.
      description: API_Errors_NotFound model
    API_Errors_InternalServerError:
      type: object
      properties:
        code:
          type: boolean
          description: Indicates the success or failure of the request.
        description:
          type: string
          description: Additional context about the request to help with debugging.
        data:
          type: object
        error:
          type: array
          items:
            type: string
          description: Any errors that occured during the execution of the request.
      description: API_Errors_InternalServerError model
    API_Entities_Location:
      type: object
      properties:
        id:
          type: integer
          format: int32
          example: 7
          description: Location id
        name:
          type: string
          example: Default
          description: Location name
        institution_id:
          type: integer
          format: int32
          example: 1
          description: Institution id
        street_address:
          type:
          - string
          - 'null'
          example: 123 Law St
          description: Location street address
        street_address_2:
          type:
          - string
          - 'null'
          example: 85335, North East
          description: Location street address 2
        city:
          type:
          - string
          - 'null'
          example: New York
          description: Location city
        state:
          type:
          - string
          - 'null'
          example: NY
          description: 2 letter state code
        zip_code:
          type:
          - string
          - 'null'
          example: '54700'
          description: Location zip code
        country_code:
          type:
          - string
          - 'null'
          example: US
          description: Location country code
        created_at:
          type: string
          example: '2020-06-05T20:16:57.007Z'
          description: Location created time in UTC
        updated_at:
          type: string
          example: '2020-06-05T20:16:57.007Z'
          description: Location last updation time in UTC
        latitude:
          type:
          - number
          - 'null'
          format: float
          example: 37.7775028
          description: Geolocated latitude determined by the address
        longitude:
          type:
          - number
          - 'null'
          format: float
          example: -122.3970603
          description: Geolocated longitude determined by the address
        phone_number:
          type:
          - string
          - 'null'
          example: '8888750851'
          description: Practice phone number
        foreign_id:
          type: string
          example: '1'
          description: Unique identifier from the integrated system
        foreign_id_type:
          type: string
          example: --DataSource-
          description: Unique identifier for the integrated system
        email:
          type:
          - string
          - 'null'
          example: defaultLocation@nexhealth.com
          description: Location email id
        tz:
          type: string
          example: America/Los_Angeles
          description: Timezone name
        last_sync_time:
          type:
          - string
          - 'null'
          example: '2020-06-17T19:23:49.176Z'
          description: Last time the resource was refreshed with data from the data source
        insert_appt_client:
          type: boolean
          example: true
          description: True if appointments created at this location are inserted into the EHR
        map_by_operatory:
          type: boolean
          example: true
          description: True if this location uses and therefore requires an operatory to schedule appointments
        set_availability_by_operatory:
          type: boolean
          example: false
          description: True if the location has appointment types specific to an operatory, false if the appointment types are specific to a provider
        inactive:
          type: boolean
          example: false
          description: Is this location not being actively used?
        specialty:
          $ref: '#/components/schemas/API_Entities_Specialty'
  securitySchemes:
    Authorization:
      type: apiKey
      name: Authorization
      in: header