A patient represents a person receiving care from a given practice.
Searching for Patients
GET requests to /patients allow you to perform a patient search. Patient search is always performed in the context of a location, so subdomain and location_id are required.
Any search request will return ALL results matching all of the specified search parameters. This means that if you specify both the email address and the phone number of a patient, you will receive a result set that includes patients matching the email address AND patients matching the phone number.
Search by name
Searching using the name parameter performs a "fuzzy" match, as opposed to an exact match. This is to catch cases where a patient may provide a preferred name or legal name or perhaps makes a typo.
Search Parameters
It is highly recommended that you provide as much contact information as possible when performing a search, or you may not find the patient you are looking for in the case they use a different email, name or phone number.
If you plan on using the patient records to book appointments, it's also recommended that you set the params
inactiveandnon_patienttofalse. This will help to filter out patients that cannot be booked for.
Creating a New Patient
In order to create a new patient, basic contact and demographic information is required. This ensures that any patient created via the Nexhealth Synchronizer API will have the information needed to also be successfully created in any number of different health record systems. The following fields are required:
- First and last names
- Email address
- Phone number
- Date of birth
- Gender
Patient Name Character Limits
Some health record systems limit the length of first and last names. Try to avoid first names greater than 15 characters and last names greater than 20 to avoid truncation.
When creating patients, it's very important that duplicates are not inadvertently created in a practice's system. To prevent this, the recommended workflow for creating with patients is as follows:
- Search for an existing patient record using
GET /patients - If no existing patient is found, create one using
POST /patients
If you attempt to create a new patient via a POST request, but a record with the same name and date of birth already exists in our system or in the health record system, you will receive a 400 Bad Request error with the message A patient with that information already exists -id=123, where 123 is the id of the existing patient. In this event, please implement a process to vet the match and prompt office staff to update/accept the contact info within your application.
Patient record insertion
Patients are not inserted into the practice management system until they have booked a first appointment. Prior to insertion they are stored in the NexHealth database. You can see if a patient has been inserted by checking that the
foreign_id_typeis not "nex".
Editing a Patient Record
A patient record can only be edited via PATCH commands prior to being inserted into the practice management system. After insertion any edits via the NexHealth API will be overwritten when NexHealth syncs with the practice management system.
Patients Response
Please note that the associated entities listed below (line 46 to 444) are available if explicitly added via the include[] parameter in a call but these entities are excluded from webhook payloads.
Additionally, please note that the view patient (singular) call includes additional associated entities (last_visited_appointment, patient_alerts, provider, children, guarantor) which are not available via the view patients (multiple) call.
{
"code": false,
"description": "Description",
"error": [
"Error"
],
"data": [
{
"patients": [
{
"id": 415,
"email": "[email protected]",
"first_name": "John",
"middle_name": "Anthony",
"last_name": "Smith",
"name": "John Smith",
"created_at": "2020-06-05T20:16:57.007Z",
"updated_at": "2020-06-05T20:16:57.007Z",
"institution_id": 0,
"foreign_id": "string",
"foreign_id_type": "--DataSource-",
"bio": {
"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": ""
},
"inactive": false,
"last_sync_time": "string",
"guarantor_id": 0,
"unsubscribe_sms": true,
"balance": {
"amount": "62.00",
"currency": "USD"
},
"children": [
{
"id": 415,
"email": "[email protected]",
"first_name": "John",
"middle_name": "Anthony",
"last_name": "Smith",
"name": "John Smith",
"created_at": "2020-06-05T20:16:57.007Z",
"updated_at": "2020-06-05T20:16:57.007Z",
"institution_id": 0,
"foreign_id": "string",
"foreign_id_type": "--DataSource-",
"bio": {
"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": ""
},
"inactive": false,
"last_sync_time": "string"
}
],
"guarantor": {
"id": 415,
"email": "[email protected]",
"first_name": "John",
"middle_name": "Anthony",
"last_name": "Smith",
"name": "John Smith",
"created_at": "2020-06-05T20:16:57.007Z",
"updated_at": "2020-06-05T20:16:57.007Z",
"institution_id": 0,
"foreign_id": "string",
"foreign_id_type": "--DataSource-",
"bio": {
"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": ""
},
"inactive": false,
"last_sync_time": "string"
},
"last_visited_appointment": {
"id": 1822,
"provider_id": 102,
"provider_name": "Dr. John Smith",
"start_time": "2021-12-06T09:45:00.000Z",
"end_time": "2021-12-06T10:00:00.000Z",
"location_id": 1,
"confirmed": true
},
"upcoming_appts": [
{
"id": 1822,
"provider_id": 102,
"provider_name": "Dr. John Smith",
"start_time": "2021-12-06T09:45:00.000Z",
"end_time": "2021-12-06T10:00:00.000Z",
"location_id": 1,
"confirmed": true
}
],
"procedures": [
{
"id": 11,
"location_id": 21,
"patient_id": 162,
"provider_id": 84,
"appointment_id": 283,
"code": "D6100",
"name": "Implant Removal",
"status": "referred",
"body_site": {},
"fee": {
"amount": "62.00",
"currency": "USD"
},
"start_date": "2022-06-24",
"end_date": "2022-06-24"
}
],
"insurance_coverages": [
{
"id": 18,
"subscription_relation": "self",
"patient_id": 25,
"priority": 2,
"subscriber_num": "123456789",
"effective_date": "2022-01-01",
"expiration_date": "2022-12-31",
"plan": {
"id": 18,
"payer_id": "87726",
"name": "United Healthcare",
"address": "123 Law St",
"address2": "85335, North East",
"city": "New York",
"state": "NY",
"zip_code": "54700",
"country_code": "US",
"group_num": "12345",
"employer_name": "Walmart",
"foreign_id": "1",
"patient_coverages": [
{
"id": 18,
"subscription_relation": "self",
"patient_id": 25,
"priority": 2,
"subscriber_num": "123456789",
"effective_date": "2022-01-01",
"expiration_date": "2022-12-31"
}
],
"subscribers": [
{
"id": 415,
"name": "John Smith",
"date_of_birth": "2020-06-05"
}
]
}
}
],
"adjustments": [
{
"id": 113,
"value": {
"amount": "62.00",
"currency": "USD"
},
"patient_id": 3,
"provider_id": 15,
"procedure_id": 42,
"date": "2020-06-05",
"notes": "string",
"patient": {
"id": 415,
"email": "[email protected]",
"first_name": "John",
"middle_name": "Anthony",
"last_name": "Smith",
"name": "John Smith",
"created_at": "2020-06-05T20:16:57.007Z",
"updated_at": "2020-06-05T20:16:57.007Z",
"institution_id": 0,
"foreign_id": "string",
"foreign_id_type": "--DataSource-",
"bio": {
"phone_number": "5163042196",
"date_of_birth": "1964-05-03"
},
"inactive": false,
"last_sync_time": "string",
"guarantor_id": 0,
"unsubscribe_sms": true,
"balance": {
"amount": "62.00",
"currency": "USD"
}
},
"provider": {
"id": 415,
"email": "[email protected]",
"first_name": "John",
"middle_name": "Anthony",
"last_name": "Smith",
"name": "John Smith",
"created_at": "2020-06-05T20:16:57.007Z",
"updated_at": "2020-06-05T20:16:57.007Z",
"institution_id": 0,
"foreign_id": "string",
"foreign_id_type": "--DataSource-",
"bio": {
"phone_number": "5163042196",
"date_of_birth": "1964-05-03"
},
"inactive": false,
"last_sync_time": "string",
"display_name": "John Smith",
"npi": "string"
},
"procedure": {
"id": 11,
"location_id": 21,
"patient_id": 162,
"provider_id": 84,
"appointment_id": 283,
"code": "D6100",
"name": "Implant Removal",
"status": "referred",
"body_site": {},
"fee": {
"amount": "62.00",
"currency": "USD"
},
"start_date": "2022-06-24",
"end_date": "2022-06-24"
},
"directionality": "credit"
}
],
"charges": [
{
"id": 113,
"value": {
"amount": "62.00",
"currency": "USD"
},
"patient_id": 3,
"provider_id": 15,
"procedure_id": 42,
"date": "2020-06-05",
"notes": "string",
"patient": {
"id": 415,
"email": "[email protected]",
"first_name": "John",
"middle_name": "Anthony",
"last_name": "Smith",
"name": "John Smith",
"created_at": "2020-06-05T20:16:57.007Z",
"updated_at": "2020-06-05T20:16:57.007Z",
"institution_id": 0,
"foreign_id": "string",
"foreign_id_type": "--DataSource-",
"bio": {
"phone_number": "5163042196",
"date_of_birth": "1964-05-03"
},
"inactive": false,
"last_sync_time": "string",
"guarantor_id": 0,
"unsubscribe_sms": true,
"balance": {
"amount": "62.00",
"currency": "USD"
}
},
"provider": {
"id": 415,
"email": "[email protected]",
"first_name": "John",
"middle_name": "Anthony",
"last_name": "Smith",
"name": "John Smith",
"created_at": "2020-06-05T20:16:57.007Z",
"updated_at": "2020-06-05T20:16:57.007Z",
"institution_id": 0,
"foreign_id": "string",
"foreign_id_type": "--DataSource-",
"bio": {
"phone_number": "5163042196",
"date_of_birth": "1964-05-03"
},
"inactive": false,
"last_sync_time": "string",
"display_name": "John Smith",
"npi": "string"
},
"procedure": {
"id": 11,
"location_id": 21,
"patient_id": 162,
"provider_id": 84,
"appointment_id": 283,
"code": "D6100",
"name": "Implant Removal",
"status": "referred",
"body_site": {},
"fee": {
"amount": "62.00",
"currency": "USD"
},
"start_date": "2022-06-24",
"end_date": "2022-06-24"
}
}
],
"payments": [
{
"id": 113,
"value": {
"amount": "62.00",
"currency": "USD"
},
"patient_id": 3,
"provider_id": 15,
"procedure_id": 42,
"date": "2020-06-05",
"notes": "string",
"patient": {
"id": 415,
"email": "[email protected]",
"first_name": "John",
"middle_name": "Anthony",
"last_name": "Smith",
"name": "John Smith",
"created_at": "2020-06-05T20:16:57.007Z",
"updated_at": "2020-06-05T20:16:57.007Z",
"institution_id": 0,
"foreign_id": "string",
"foreign_id_type": "--DataSource-",
"bio": {
"phone_number": "5163042196",
"date_of_birth": "1964-05-03"
},
"inactive": false,
"last_sync_time": "string",
"guarantor_id": 0,
"unsubscribe_sms": true,
"balance": {
"amount": "62.00",
"currency": "USD"
}
},
"provider": {
"id": 415,
"email": "[email protected]",
"first_name": "John",
"middle_name": "Anthony",
"last_name": "Smith",
"name": "John Smith",
"created_at": "2020-06-05T20:16:57.007Z",
"updated_at": "2020-06-05T20:16:57.007Z",
"institution_id": 0,
"foreign_id": "string",
"foreign_id_type": "--DataSource-",
"bio": {
"phone_number": "5163042196",
"date_of_birth": "1964-05-03"
},
"inactive": false,
"last_sync_time": "string",
"display_name": "John Smith",
"npi": "string"
},
"procedure": {
"id": 11,
"location_id": 21,
"patient_id": 162,
"provider_id": 84,
"appointment_id": 283,
"code": "D6100",
"name": "Implant Removal",
"status": "referred",
"body_site": {},
"fee": {
"amount": "62.00",
"currency": "USD"
},
"start_date": "2022-06-24",
"end_date": "2022-06-24"
}
}
],
"patient_alerts": [
{
"id": 10,
"patient_id": 101,
"note": "Patient is late on payment",
"disabled_at": "2024-02-05T20:16:57.007Z",
"created_at": "2023-11-11T10:11:01.007Z",
"updated_at": "2024-01-14T14:11:01.007Z"
}
],
"appointments": [
{
"id": 1822,
"provider_id": 102,
"provider_name": "Dr. John Smith",
"start_time": "2021-12-06T09:45:00.000Z",
"end_time": "2021-12-06T10:00:00.000Z",
"location_id": 1,
"confirmed": true
}
],
"location_ids": [
101,
102,
103
],
"address": {
"line_1": "string",
"line_2": "string",
"postal_code": "string",
"city": "string",
"region": "string"
}
}
]
}
],
"count": 2
}