OpenAPI Specification
openapi: 3.0.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_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_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_V20240412_Entities_Ledger_Adjustment:
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
format: int32
example: 10
description: The ID of the location that this item is for
nullable: true
patient_id:
type: integer
format: int32
example: 3
description: The ID of the patient that this item is for
nullable: true
guarantor_id:
type: integer
format: int32
example: 5
description: The ID of the guarantor that this item is for
nullable: true
provider_id:
type: integer
format: int32
example: 15
description: The ID of the provider that this item is for
nullable: true
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
example: This is a description
description: A description of the item
nullable: true
deleted_at:
type: string
format: date-time
example: '2024-09-15T11:21:26.003Z'
description: Deleted time for item in UTC
nullable: true
adjustment_amount:
$ref: '#/components/schemas/API_V2_Entities_Price'
adjusted_at:
type: string
format: date
example: '2024-10-01'
description: The UTC date adjustment was made
nullable: true
transaction_id:
type: string
example: NHP:JXZEQ1234
description: The ID of the transaction for this adjustment
nullable: true
charge_id:
type: integer
format: int64
example: 1111
description: The ID of the charge for this adjustment
nullable: true
claim_id:
type: integer
format: int64
example: 2222
description: The ID of the insurance claim for this adjustment
nullable: true
adjustment_type_id:
type: integer
format: int64
example: 5
description: The ID of the adjustment type for this adjustment
nullable: true
API_V2_Entities_PatientsResponses_Create:
type: object
properties:
user:
$ref: '#/components/schemas/API_V2_Entities_PatientBasic'
API_V2_Entities_PatientBasic:
type: object
properties:
id:
type: integer
format: int32
example: 415
description: User id
email:
type: string
example: Amy.Ramos@nexhealth.com
description: User email
nullable: true
first_name:
type: string
example: John
description: First name
middle_name:
type: string
example: Anthony
description: Middle name
nullable: true
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
example: '100437'
description: Foreign Id is a unique identifier from the integrated system
nullable: true
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
format: date-time
example: '2024-04-12T10:30:00Z'
description: The most recent time the resource's data changed meaningfully at the source
nullable: true
guarantor_id:
type: integer
format: int32
example: 472
description: User id of this patient's responsible party
nullable: true
billing_type:
type: string
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
nullable: true
chart_id:
type: string
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
nullable: true
preferred_language:
type: string
example: es
description: Patient's preferred language as an ISO 639-1 code, if specified in the integrated system
nullable: true
preferred_locale:
type: string
example: es
description: The patient's preferred language setting used for displaying NexHealth forms and communications
nullable: true
location_ids:
type: array
items:
type: integer
format: int32
example:
- 101
- 102
- 103
description: Array of location ids associated with the user
API_V2_Entities_Price:
type: object
properties:
amount:
type: string
example: '62.00'
description: The currency value, in whole units (e.g. dollars)
currency:
type: string
example: USD
description: The ISO currency code
API_V2_Entities_ProcedureBodySite:
type: object
properties:
tooth:
type: array
items:
type: string
example:
- '3'
- '14'
description: Tooth identifier strings, typically tooth numbers
surface:
type: string
example: MOD
description: Tooth surface codes
API_V20240412_Entities_PatientDetailed_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_PatientDetailed'
count:
type: integer
format: int32
example: 2
description: Number of total objects, in case of collection.
description: API_V20240412_Entities_PatientDetailed_Response model
API_V2_Entities_AppointmentBasic:
type: object
properties:
id:
type: integer
format: int64
example: 1822
description: Appointment id
provider_id:
type: integer
format: int32
example: 102
description: Provider id
provider_name:
type: string
example: Dr. John Smith
description: Provider name
start_time:
type: string
format: date-time
example: '2021-12-06T09:45:00.000Z'
description: Start time of the appointment in UTC
end_time:
type: string
format: date-time
example: '2021-12-06T10:00:00.000Z'
description: End time of the appointment in UTC
location_id:
type: integer
format: int32
example: 1
description: Location id
confirmed:
type: boolean
example: true
description: Is this appointment confirmed?
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
format: int32
example: 10
description: The ID of the location that this item is for
nullable: true
patient_id:
type: integer
format: int32
example: 3
description: The ID of the patient that this item is for
nullable: true
guarantor_id:
type: integer
format: int32
example: 5
description: The ID of the guarantor that this item is for
nullable: true
provider_id:
type: integer
format: int32
example: 15
description: The ID of the provider that this item is for
nullable: true
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
example: This is a description
description: A description of the item
nullable: true
deleted_at:
type: string
format: date-time
example: '2024-09-15T11:21:26.003Z'
description: Deleted time for item in UTC
nullable: true
payment_amount:
$ref: '#/components/schemas/API_V2_Entities_Price'
paid_at:
type: string
format: date
example: '2024-10-01'
description: The UTC date payment was made
nullable: true
transaction_id:
type: string
example: NHP:JXZEQ1234
description: The ID of the transaction for this payment
nullable: true
charge_id:
type: integer
format: int64
example: 1111
description: The ID of the charge for this payment
nullable: true
claim_id:
type: integer
format: int64
example: 2222
description: The ID of the insurance claim for this payment
nullable: true
payment_plan_id:
type: integer
format: int64
example: 3
description: The ID of the payment plan associated with this payment
nullable: true
insurance_plan_id:
type: integer
format: int64
example: 4
description: The ID of the insurance plan associated with this payment
nullable: true
payment_type_id:
type: integer
format: int64
example: 5
description: The ID of the payment type for this payment
nullable: true
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
format: int32
example: 10
description: The ID of the location that this item is for
nullable: true
patient_id:
type: integer
format: int32
example: 3
description: The ID of the patient that this item is for
nullable: true
guarantor_id:
type: integer
format: int32
example: 5
description: The ID of the guarantor that this item is for
nullable: true
provider_id:
type: integer
format: int32
example: 15
description: The ID of the provider that this item is for
nullable: true
procedure_id:
type: integer
format: int64
example: 34
description: The ID of the procedure associated with this charge
nullable: true
procedure_code:
type: string
example: D0120
description: The procedure code associated with this charge
nullable: true
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
example: This is a description
description: A description of the charge
# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nexhealth/refs/heads/main/openapi/nexhealth-patients-api-openapi.yml