NexHealth Appointments API

openapi: 3.2.0
info:
  title: NexHealth Adjustment Types Appointments 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: Appointments
  description: A booking on the Practice's calendar
paths:
  /appointments/{id}:
    get:
      summary: View appointment
      parameters:
      - in: path
        name: id
        description: Id of the appointment
        required: true
        schema:
          type: integer
          format: int64
      - 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:
            - patient
            - guarantor
            - descriptors
            - booking_details
            - procedures
            - operatory
            - appointment_type
            default: patient
      responses:
        '200':
          description: Successful
          content:
            application/vnd.Nexhealth+json;version=2:
              schema:
                $ref: '#/components/schemas/API_V2_Entities_Appointment_Response'
        '400':
          description: Bad Request
          content:
            application/vnd.Nexhealth+json;version=2:
              schema:
                $ref: '#/components/schemas/API_Errors_BadRequest'
        '401':
          description: Unauthorized
          content:
            application/vnd.Nexhealth+json;version=2:
              schema:
                $ref: '#/components/schemas/API_Errors_Unauthorized'
        '403':
          description: Forbidden
          content:
            application/vnd.Nexhealth+json;version=2:
              schema:
                $ref: '#/components/schemas/API_Errors_Forbidden'
        '404':
          description: Not Found
          content:
            application/vnd.Nexhealth+json;version=2:
              schema:
                $ref: '#/components/schemas/API_Errors_NotFound'
        '500':
          description: Internal Server Error
          content:
            application/vnd.Nexhealth+json;version=2:
              schema:
                $ref: '#/components/schemas/API_Errors_InternalServerError'
      tags:
      - Appointments
      operationId: getAppointmentsId
    patch:
      summary: Edit Appointment
      description: This endpoint updates an existing appointment.
      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: Id of the appointment
        required: true
        schema:
          type: integer
          format: int64
      - in: query
        name: subdomain
        description: Used to scope the request to the specified institution
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/patchAppointmentsId'
        required: true
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_V2_Entities_AppointmentResponse_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:
      - Appointments
      operationId: patchAppointmentsId
  /appointments/{id}/appointment_descriptors:
    get:
      summary: View appointment descriptors
      parameters:
      - in: path
        name: id
        description: Id of the appointment
        required: true
        schema:
          type: integer
          format: int64
      - in: query
        name: subdomain
        description: Used to scope the request to the specified institution
        required: true
        schema:
          type: string
      - in: query
        name: descriptor_type
        description: Query by descriptor type
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful
          content:
            application/vnd.Nexhealth+json;version=2:
              schema:
                $ref: '#/components/schemas/API_V2_Entities_EmrApptDescriptor_Collection_Response'
        '400':
          description: Bad Request
          content:
            application/vnd.Nexhealth+json;version=2:
              schema:
                $ref: '#/components/schemas/API_Errors_BadRequest'
        '401':
          description: Unauthorized
          content:
            application/vnd.Nexhealth+json;version=2:
              schema:
                $ref: '#/components/schemas/API_Errors_Unauthorized'
        '403':
          description: Forbidden
          content:
            application/vnd.Nexhealth+json;version=2:
              schema:
                $ref: '#/components/schemas/API_Errors_Forbidden'
        '404':
          description: Not Found
          content:
            application/vnd.Nexhealth+json;version=2:
              schema:
                $ref: '#/components/schemas/API_Errors_NotFound'
        '500':
          description: Internal Server Error
          content:
            application/vnd.Nexhealth+json;version=2:
              schema:
                $ref: '#/components/schemas/API_Errors_InternalServerError'
      tags:
      - Appointments
      operationId: getAppointmentsIdAppointmentDescriptors
  /appointments:
    get:
      summary: View appointments
      description: This endpoint returns the appointments starting within the requested time window, narrowed down by the optional filters configured. At least one of location_id or foreign_id must be provided.
      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: location_id
        description: Used to scope the request to the specified location
        required: false
        example: 1
        schema:
          type: integer
          format: int32
      - 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: start
        description: A parseable date string defining the earliest returned records. Recommended format is YYYY-MM-DDThh:mm:ss+0000
        required: true
        example: '2024-04-01T00:00:00Z'
        schema:
          type: string
          format: date-time
      - in: query
        name: end
        description: A parseable date string defining the last returned records. Recommended format is YYYY-MM-DDThh:mm:ss+0000
        required: true
        example: '2024-04-30T23:59:59Z'
        schema:
          type: string
          format: date-time
      - in: query
        name: timezone
        description: Timezone for the appointment clinic
        required: false
        example: America/New_York
        schema:
          type: string
      - in: query
        name: cancelled
        description: Filter by cancelled status.
        required: false
        example: false
        schema:
          type: boolean
      - in: query
        name: unavailable
        description: Unavailable appointments are used to block availability on a schedule, specify to set the filter
        required: false
        example: false
        schema:
          type: boolean
      - in: query
        name: nex_only
        description: Only show appointments booked via NexHealth API
        required: false
        example: false
        schema:
          type: boolean
      - in: query
        name: updated_since
        description: Query appointments whose records have updated since the specified datetime in ISO8601 format. Must be a parseable date/time, recommended formats are YYYY-MM-DD or YYYY-MM-DDT00:00:00+0000
        required: false
        example: '2024-04-12T10:30:00Z'
        schema:
          type: string
          format: date-time
      - in: query
        name: appointment_type_id
        description: Get appointments for a specific appointment type
        required: false
        example: 27
        schema:
          type: integer
          format: int32
      - in: query
        name: foreign_id
        description: Unique appointment id from the EHR
        required: false
        example: '94'
        schema:
          type: string
      - in: query
        name: created_by
        description: Query appointments that were created by a specific user
        required: false
        example: 197
        schema:
          type: integer
          format: int32
      - 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: patient_ids[]
        description: Get appointments for specific patients (up to 25 ids)
        required: false
        example:
        - 2897
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
            format: int32
      - in: query
        name: provider_ids[]
        description: Query appointments that are booked with the specified providers only
        required: false
        example:
        - 104
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
            format: int32
      - in: query
        name: operatory_ids[]
        description: Query appointments that are booked in the specified operatories only
        required: false
        example:
        - 181
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
            format: int32
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_V2_Entities_AppointmentWithoutIncludes_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:
      - Appointments
      operationId: getAppointments
    post:
      summary: Create appointment
      description: This endpoint books an appointment for the given patient with the given provider at the specified location. When is_guardian is true, the booking is made by a guardian and a patient object with the dependent's details must be provided. Set unavailable to true to create a block instead of a patient appointment.
      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: location_id
        description: Used to scope the request to the specified location
        required: true
        schema:
          type: integer
          format: int32
      - in: query
        name: notify_patient
        description: Send NexHealth appointment created notifications to patient
        required: false
        schema:
          type: boolean
          default: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postAppointments'
        required: true
      responses:
        '201':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_V2_Entities_AppointmentResponse_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:
      - Appointments
      operationId: postAppointments
components:
  schemas:
    API_V2_Entities_Procedure:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 11
          description: Procedure id
        location_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 21
          description: Location id
        patient_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 162
          description: Patient id
        provider_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 84
          description: Provider id
        appointment_id:
          type:
          - integer
          - 'null'
          format: int64
          example: 283
          description: Appointment id. Null when the procedure is not attached to an appointment
        code:
          type:
          - string
          - 'null'
          example: D6100
          description: Procedure code
        name:
          type:
          - string
          - 'null'
          example: Implant Removal
          description: Procedure name
        status:
          type:
          - string
          - 'null'
          enum:
          - planned
          - scheduled
          - completed
          - inactive
          - referred
          example: referred
          description: Procedure status
        updated_at:
          type: string
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: Procedure update date in UTC
        body_site:
          $ref: '#/components/schemas/API_V2_Entities_ProcedureBodySite'
        fee:
          $ref: '#/components/schemas/API_V2_Entities_Price'
        start_date:
          type:
          - string
          - 'null'
          format: date
          example: '2022-06-24'
          description: Start date for procedure
        end_date:
          type:
          - string
          - 'null'
          format: date
          example: '2022-06-24'
          description: End date for procedure
    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
    patchAppointmentsId:
      type: object
      properties:
        appt:
          type: object
          description: Appointment detail object
          properties:
            confirmed:
              type: boolean
              description: Denotes the office has confirmed the appt, update this to write back confirm status
              example: true
            cancelled:
              type: boolean
              description: Denotes the office has cancelled the appt, update this to write back cancel status
              example: false
            checkin_at:
              type: string
              format: date-time
              description: Denotes the office has checked in the appt at this time, update this to write back checked in status. Must be a parseable date/time string, recommended format is YYYY-MM-DDThh:mm:ss+0000
              example: '2024-04-15T14:55:00Z'
            start_time:
              type: string
              format: date-time
              description: Appointment start time. Must be a parseable date/time string. Recommended format is YYYY-MM-DDThh:mm:ss+0000.
              example: '2024-04-15T15:00:00Z'
            end_time:
              type: string
              format: date-time
              description: Appointment end time. Must be a parseable date/time string. Recommended format is YYYY-MM-DDThh:mm:ss+0000.
              example: '2024-04-15T15:30:00Z'
            operatory_id:
              type: integer
              format: int32
              description: The operatory for this appointment
              example: 181
            note:
              type: string
              description: A note that will be written to the EHR
              example: Patient has been having a cough for 3 days
      required:
      - appt
      description: Edit Appointment
    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_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_V2_Entities_Appointment:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1822
          description: Appointment id
        patient_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 2897
          description: Appointment patient id
        provider_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 104
          description: Provider id
        provider_name:
          type:
          - string
          - 'null'
          example: Dr. John Smith
          description: Provider name
        start_time:
          type: string
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: Appointment scheduled start time in UTC
        confirmed:
          type:
          - boolean
          - 'null'
          example: true
          description: Appointment confirmation status
        patient_missed:
          type:
          - boolean
          - 'null'
          example: false
          description: Did the patient no show? Not supported by all integrations
        created_at:
          type: string
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: Appointment created time in UTC
        updated_at:
          type: string
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: Appointment last updation time in UTC
        note:
          type:
          - string
          - 'null'
          example: Patient has been having a cough for 3 days
          description: Appointment note
        end_time:
          type: string
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: Appointment scheduled end time in UTC
        unavailable:
          type:
          - boolean
          - 'null'
          example: false
          description: Is this appointment a scheduling block (blocks off the schedule)
        cancelled:
          type: boolean
          example: false
          description: Is this appointment cancelled?
        timezone:
          type: string
          example: America/New_York
          description: Appointment timezone
        institution_id:
          type: integer
          format: int32
          example: 1
          description: Institution id
        appointment_type_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 27
          description: Nexhealth appointment_type id, 0 if not set
        checkin_at:
          type:
          - string
          - 'null'
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: Time the patient checked in at in UTC. Not supported by all integrations
        location_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 1
          description: Appointment location id
        foreign_id:
          type:
          - string
          - 'null'
          example: '94'
          description: Unique identifier of this resource from the integrated system
        foreign_id_type:
          type: string
          example: msg-dentrix-DataSource-100
          description: Unique identifier for the integrated system itself
        misc:
          type:
          - object
          - 'null'
          example:
            is_booked_on_nexhealth: true
          description: Miscellaneous information for the appointment. The is_booked_on_nexhealth key indicates whether the appointment was booked through NexHealth
        last_sync_time:
          type:
          - string
          - 'null'
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: Last Sync time in UTC
        patient_confirmed:
          type:
          - boolean
          - 'null'
          example: false
          description: Is this appointment confirmed by the patient (as opposed to the office)?
        created_by_user_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 197
          description: Id of the user who booked the appointment
        is_guardian:
          type:
          - boolean
          - 'null'
          example: false
          description: Was the appointment booked by a guardian?
        patient_confirmed_at:
          type:
          - string
          - 'null'
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: Time of patient_confirmation in UTC
        cancelled_at:
          type:
          - string
          - 'null'
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: Time of appointment cancellation in UTC. Note this will not be reset if the appointment is uncancelled
        is_new_clients_patient:
          type:
          - boolean
          - 'null'
          example: false
          description: Is this a new patient at this practice?
        confirmed_at:
          type:
          - string
          - 'null'
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: Time of appointment confirmation by the office in UTC
        sooner_if_possible:
          type:
          - boolean
          - 'null'
          example: false
          description: Does patient want an earlier time?
        operatory_id:
          type:
          - integer
          - 'null'
          format: int64
          example: 181
          description: Operatory id for the appointment
        checked_out:
          type:
          - boolean
          - 'null'
          example: false
          description: Has the patient checked out? Not supported by all integrations
        checked_out_at:
          type:
          - string
          - 'null'
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: Time of check out in UTC
        referrer:
          type:
          - string
          - 'null'
          example: http://mypractice.com/book
          description: Optional field to store URI origin of the booking
        is_past_patient:
          type:
          - boolean
          - 'null'
          example: true
          description: Does this patient have prior appointments?
        timezone_offset:
          type: string
          example: '-4:00'
          description: Timezone offset string
        patient:
          $ref: '#/components/schemas/API_V2_Entities_PatientWithGuarantor'
        operatory:
          $ref: '#/components/schemas/API_V2_Entities_OperatoryBasic'
        appointment_type:
          $ref: '#/components/schemas/API_V2_Entities_AppointmentTypeBasic'
        procedures:
          type: array
          items:
            $ref: '#/components/schemas/API_V2_Entities_Procedure'
          description: Procedures assigned to the appointment
        descriptors:
          type: array
          items:
            $ref: '#/components/schemas/API_V2_Entities_EmrApptDescriptor'
          description: EHR descriptors
        booking_details:
          $ref: '#/components/schemas/API_V2_Entities_Appointment_OnlineBookingDetail'
    API_V2_Entities_Appointment_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_V2_Entities_Appointment'
        count:
          type: integer
          format: int32
          example: 2
          description: Number of total objects, in case of collection.
      description: API_V2_Entities_Appointment_Response model
    postAppointments:
      type: object
      properties:
        appointments_per_timeslot:
          type: integer
          format: int32
          description: Number of appointments (default:1, max:5) that can be booked in a single slot. Only supported for eClinicalWorks and NextGen.
          minimum: 1
          maximum: 5
          default: 1
        appt:
          type: object
          description: Appointment detail object
          properties:
            patient_id:
              type: integer
              format: int32
              description: Id of the patient, unless booking is being done by a guardian in which case use the guardian's patient id
              example: 2897
            provider_id:
              type: integer
              format: int32
              description: Provider id
              example: 104
            operatory_id:
              type: integer
              format: int32
              description: Required if bookings are mapped to operatories for this location
              example: 181
            start_time:
              type: string
              format: date-time
              description: Appointment start time. Must be a parseable date/time string, recommended format is YYYY-MM-DDThh:mm:ss+0000
              example: '2024-04-15T15:00:00Z'
            end_time:
              type: string
              format: date-time
              description: Appointment end time. Must be a parseable date/time string. Recommended format is YYYY-MM-DDThh:mm:ss+0000.
              example: '2024-04-15T15:30:00Z'
            appointment_type_id:
              type: integer
              format: int32
              description: The appointment type for this appointment
              example: 27
            note:
              type: string
              description: A note that will be written to the EHR. 128 character limit.
              example: Patient has been having a cough for 3 days
            un

# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nexhealth/refs/heads/main/openapi/nexhealth-appointments-api-openapi.yml