NexHealth Patients API

openapi: 3.2.0
info:
  title: NexHealth Adjustment Types Patients 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: Patients
  description: A patients resource
paths:
  /patients:
    get:
      summary: View patients
      description: This endpoint returns a list of patients for the specified location, 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: location_id
        description: Used to scope the request to the specified location
        required: true
        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  * id\n  * -id\n  * updated_at\n  * -updated_at\n"
        required: false
        schema:
          type: string
          default: id
      - in: query
        name: name
        description: Filter by patient name
        required: false
        example: John Smith
        schema:
          type: string
      - in: query
        name: email
        description: Filter by patient email
        required: false
        example: john.smith@example.com
        schema:
          type: string
      - in: query
        name: phone_number
        description: Filter by patient phone number
        required: false
        example: '5163042196'
        schema:
          type: string
      - in: query
        name: date_of_birth
        description: Filter by patient date of birth. Must be a parseable date string, recommended format is YYYY-MM-DD
        required: false
        example: '1964-05-03'
        schema:
          type: string
          format: date
      - in: query
        name: inactive
        description: Filter by inactive status. When true, returns only inactive patients. When false, returns only active patients. When not specified, does not filter
        required: false
        example: false
        schema:
          type: boolean
      - in: query
        name: foreign_id
        description: Filter by the unique patient id from the EHR
        required: false
        example: '100437'
        schema:
          type: string
      - in: query
        name: updated_since
        description: Only return patients updated at or after the specified date/time. 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: new_patient
        description: Filter patients by new_patient status. When true, returns only new patients with an upcoming appointment. When false, returns only non-new patients. When not specified, returns both regular patients and new patients with upcoming appointments. Patients with the attribute new_patient=true are patients that do not fully exist in the EHR so cannot be used to book appointments. When the patient record is officially created (and read by us) in the EHR, record associations will be created and any new_patient records are deleted.
        required: false
        example: false
        schema:
          type: boolean
      - in: query
        name: non_patient
        description: 'Specify if you want to filter non_patients. In case of true: return only non_patients. In case of false: Result does not include non_patients. In case of null: do not set filter/return any'
        required: false
        example: false
        schema:
          type: boolean
      - in: query
        name: forms_syncable
        description: 'Specify if you want to filter to patients that can have forms inserted into their patient file. In case of true: Return only patients that can have forms inserted into their patient file. In case of false or nil: do not filter'
        required: false
        example: true
        schema:
          type: boolean
      - in: query
        name: location_strict
        description: Only returns patients belonging to the specified location, rather than searching across the EHR system
        required: false
        example: false
        schema:
          type: boolean
          default: false
      - 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
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_V20240412_Entities_PatientWithPrivacyAuthorization_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:
      - Patients
      operationId: getPatients
    post:
      summary: Create patient
      description: This endpoint creates a new patient or returns an existing patient if return_existing_if_match is true. Responds with 201 when a new patient is created, or with 200 and the existing patient when return_existing_if_match is true and a patient with matching information already exists.
      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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postPatients'
        required: true
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_V2_Entities_PatientsResponses_Create_Response'
        '201':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_V2_Entities_PatientsResponses_Create_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:
      - Patients
      operationId: postPatients
  /patients/{id}:
    get:
      summary: View patient
      description: This endpoint returns a single patient. You must provide a valid patient NexHealth ID.
      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: path
        name: id
        required: true
        schema:
          type: integer
          format: int32
      - in: query
        name: include[]
        description: Resources to be included in the response
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - upcoming_appts
            - last_visited_appointment
            - children
            - guarantor
            - procedures
            - insurance_coverages
            - adjustments
            - charges
            - payments
            - patient_alerts
            - address
            - provider
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_V20240412_Entities_PatientDetailed_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:
      - Patients
      operationId: getPatientsId
components:
  schemas:
    API_V20240412_Entities_PatientWithPrivacyAuthorization:
      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
        guarantor_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 472
          description: User id of this patient's responsible party
        billing_type:
          type:
          - string
          - 'null'
          example: Standard Billing - finance charges
          description: Used by practices in some integrated systems to categorize and filter patients when creating reports, requesting payments, and performing other related office tasks. Some integrated systems call this an account type rather than a billing type
        chart_id:
          type:
          - string
          - 'null'
          example: '017407'
          description: User-facing ID for referencing patient data, used in some integrated systems. Depending on the system, the chart ID supplements or replaces the foreign_id as the ID visible to EHR users
        preferred_language:
          type:
          - string
          - 'null'
          example: es
          description: Patient's preferred language as an ISO 639-1 code, if specified in the integrated system
        provider_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 23
          description: User id of this patient's primary provider
        hipaa:
          $ref: '#/components/schemas/API_V2_Entities_PrivacyAuthorization'
    API_V2_Entities_PatientAlert:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
          description: Patient Alert id
        patient_id:
          type: integer
          format: int32
          example: 101
          description: Id of the associated patient
        note:
          type: string
          example: Patient is late on payment
          description: The note for the patient alert
        disabled_at:
          type: string
          format: date-time
          example: '2024-02-05T20:16:57.007Z'
          description: The time that the alert was disabled in UTC
        created_at:
          type: string
          format: date-time
          example: '2023-11-11T10:11:01.007Z'
          description: The time that the alert was created in UTC
        updated_at:
          type: string
          format: date-time
          example: '2024-01-14T14:11:01.007Z'
          description: The time that the alert was last updated in UTC
    API_V2_Entities_PatientsResponses_Create:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/API_V2_Entities_PatientBasic'
    API_V20240412_Entities_Ledger_Payment:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 113
          description: Resource id
        foreign_id:
          type: string
          example: 1234-5678
          description: Unique identifier of this resource from the integrated system
        location_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 10
          description: The ID of the location that this item is for
        patient_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 3
          description: The ID of the patient that this item is for
        guarantor_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 5
          description: The ID of the guarantor that this item is for
        provider_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 15
          description: The ID of the provider that this item is for
        updated_at:
          type: string
          format: date-time
          example: '2024-09-05T20:31:17.007Z'
          description: Last updated time for item in UTC
        description:
          type:
          - string
          - 'null'
          example: This is a description
          description: A description of the item
        deleted_at:
          type:
          - string
          - 'null'
          format: date-time
          example: '2024-09-15T11:21:26.003Z'
          description: Deleted time for item in UTC
        payment_amount:
          $ref: '#/components/schemas/API_V2_Entities_Price'
        paid_at:
          type:
          - string
          - 'null'
          format: date
          example: '2024-10-01'
          description: The UTC date payment was made
        transaction_id:
          type:
          - string
          - 'null'
          example: NHP:JXZEQ1234
          description: The ID of the transaction for this payment
        charge_id:
          type:
          - integer
          - 'null'
          format: int64
          example: 1111
          description: The ID of the charge for this payment
        claim_id:
          type:
          - integer
          - 'null'
          format: int64
          example: 2222
          description: The ID of the insurance claim for this payment
        payment_plan_id:
          type:
          - integer
          - 'null'
          format: int64
          example: 3
          description: The ID of the payment plan associated with this payment
        insurance_plan_id:
          type:
          - integer
          - 'null'
          format: int64
          example: 4
          description: The ID of the insurance plan associated with this payment
        payment_type_id:
          type:
          - integer
          - 'null'
          format: int64
          example: 5
          description: The ID of the payment type for this payment
    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_Insurance_EhrPlan:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 18
          description: Plan id
        payer_id:
          type:
          - string
          - 'null'
          example: '87726'
          description: A unique ID number that is assigned to an insurance company for the purpose of transmitting provider claims electronically
        name:
          type:
          - string
          - 'null'
          example: United Healthcare
          description: Plan name
        address:
          type:
          - string
          - 'null'
          example: 123 Law St
          description: Street address
        address2:
          type:
          - string
          - 'null'
          example: 85335, North East
          description: Street address 2
        city:
          type:
          - string
          - 'null'
          example: New York
          description: City
        state:
          type:
          - string
          - 'null'
          example: NY
          description: 2 letter state code
        zip_code:
          type:
          - string
          - 'null'
          example: '54700'
          description: Zip code
        country_code:
          type:
          - string
          - 'null'
          example: US
          description: 2 letter country code
        group_num:
          type:
          - string
          - 'null'
          example: '12345'
          description: Group number
        employer_name:
          type:
          - string
          - 'null'
          example: Walmart
          description: Employer name
        foreign_id:
          type:
          - string
          - 'null'
          example: '1'
          description: Foreign Id is a unique identifier from the integrated system
        updated_at:
          type: string
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: Insurance Plan update date in UTC
        deleted_at:
          type:
          - string
          - 'null'
          format: date-time
          example: '2024-09-15T11:21:26.003Z'
          description: The UTC date and time the insurance plan was deleted. Null unless the plan is soft-deleted; deleted plans are only returned when include_deleted is true
    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_V20240412_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
        treatment_plan_ids:
          type: array
          items:
            type: integer
            format: int64
          example:
          - 42
          - 57
          description: Treatment plan ids
    postPatients:
      type: object
      properties:
        provider:
          type: object
          example:
            provider_id: 12
          properties:
            provider_id:
              type: integer
              format: int64
              description: Id of the provider with which to intake this new patient
          required:
          - provider_id
        patient:
          type: object
          properties:
            first_name:
              type: string
              description: Patient first name
              example: John
            last_name:
              type: string
              description: Patient last name
              example: Smith
            email:
              type: string
              description: Patient email id. Must match regular expression /\A([^@\s]+)@((?:[-a-z0-9]\.)[a-z]{2,})\Z/
              example: john.smith@example.com
            bio:
              type: object
              description: Patient Bio
              properties:
                date_of_birth:
                  type: string
                  format: date
                  description: Patient date of birth. Must be a parseable date string, recommended format is YYYY-MM-DD. Cannot be more than 130 years in the past or in the future
                  example: '1964-05-03'
                phone_number:
                  type: string
                  description: Patient phone number
                  example: '5163042196'
                home_phone_number:
                  type: string
                  description: Patient home phone number
                  example: '5163042197'
                cell_phone_number:
                  type: string
                  description: Patient cell phone number
                  example: '5163042198'
                work_phone_number:
                  type: string
                  description: Patient work place phone number
                  example: '5163042199'
                custom_contact_number:
                  type: string
                  description: Patient custom contact phone number
                  example: '5163042200'
                gender:
                  type: string
                  description: Patient gender. Gender will default to Female if not provided. This is to ensure compatibility with all EHRs. This will be updated when the patient visits the office and updates their info
                  enum:
                  - Male
                  - Female
                  - Other
                  example: Female
                weight:
                  type: integer
                  format: int32
                  description: Patient weight in KG
                  example: 70
                height:
                  type: integer
                  format: int32
                  description: Patient height in CM
                  example: 175
                street_address:
                  type: string
                  description: Patient full street address
                  example: 333 Bush Street
                address_line_1:
                  type: string
                  description: Patient street address line 1
                  example: 333 Bush Street
                address_line_2:
                  type: string
                  description: Patient street address line 2
                  example: Apt 4B
                city:
                  type: string
                  description: Patient city
                  example: New York
                state:
                  type: string
                  description: Patient living state
                  example: NY
                zip_code:
                  type: string
                  description: Patient zip code
                  example: '20814'
                insurance_name:
                  type: string
                  description: Insurance name
                  example: Delta Dental of California
                ssn:
                  type: string
                  description: Patient SSN
                  example: 123-45-6789
                race:
                  type: string
                  description: Patient race
                  example: White
              required:
              - date_of_birth
              - phone_number
          required:
          - first_name
          - last_name
          - email
          - bio
        return_existing_if_match:
          type: boolean
          description: If true, return existing patient with matching information (200 OK) instead of raising an error. If false, raise an error when a patient with matching information already exists (400 Bad Request). Matching is based on date of birth, name, and phone number.
          default: false
      required:
      - provider
      - patient
      description: Create patient
    API_V20240412_Entities_Ledger_ChargeBasicWithDelete:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 113
          description: Resource id
        foreign_id:
          type: string
          example: 1234-5678
          description: Unique identifier of this resource from the integrated system
        location_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 10
          description: The ID of the location that this item is for
        patient_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 3
          description: The ID of the patient that this item is for
        guarantor_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 5
          description: The ID of the guarantor that this item is for
        provider_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 15
          description: The ID of the provider that this item is for
        procedure_id:
          type:
          - integer
          - 'null'
          format: int64
          example: 34
          description: The ID of the procedure associated with this charge
        procedure_code:
          type:
          - string
 

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