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 inactive and non_patient to false. 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 insertion
Patients only get inserted into health record systems when they book their first appointment. Until then, they're just stored in NexHealth's database and their foreign_id_type is set to 'nex'.

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": "Amy.Ramos@nexhealth.com",
          "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": "2025-03-17T21:21:25.644Z",
          "authz": {
            "permissions": {}
          },
          "guarantor_id": 0,
          "unsubscribe_sms": true,
          "balance": {
            "amount": "62.00",
            "currency": "USD"
          },
          "billing_type": "Standard Billing - finance charges",
          "chart_id": "017407",
          "preferred_language": "es",
          "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"
              },
              "subscriber": {
                "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": "Amy.Ramos@nexhealth.com",
                "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": "2025-03-17T21:21:25.644Z",
                "authz": {
                  "permissions": {}
                },
                "guarantor_id": 0,
                "unsubscribe_sms": true,
                "balance": {
                  "amount": "62.00",
                  "currency": "USD"
                },
                "billing_type": "Standard Billing - finance charges",
                "chart_id": "017407",
                "preferred_language": "es"
              },
              "provider": {
                "id": 415,
                "email": "Amy.Ramos@nexhealth.com",
                "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": "2025-03-17T21:21:25.644Z",
                "authz": {
                  "permissions": {}
                },
                "display_name": "John Smith",
                "npi": "1912507500",
                "tin": "078051120",
                "state_license": "R219935",
                "specialty_code": "363L00000X"
              },
              "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": "Amy.Ramos@nexhealth.com",
                "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": "2025-03-17T21:21:25.644Z",
                "authz": {
                  "permissions": {}
                },
                "guarantor_id": 0,
                "unsubscribe_sms": true,
                "balance": {
                  "amount": "62.00",
                  "currency": "USD"
                },
                "billing_type": "Standard Billing - finance charges",
                "chart_id": "017407",
                "preferred_language": "es"
              },
              "provider": {
                "id": 415,
                "email": "Amy.Ramos@nexhealth.com",
                "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": "2025-03-17T21:21:25.644Z",
                "authz": {
                  "permissions": {}
                },
                "display_name": "John Smith",
                "npi": "1912507500",
                "tin": "078051120",
                "state_license": "R219935",
                "specialty_code": "363L00000X"
              },
              "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": "Amy.Ramos@nexhealth.com",
                "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": "2025-03-17T21:21:25.644Z",
                "authz": {
                  "permissions": {}
                },
                "guarantor_id": 0,
                "unsubscribe_sms": true,
                "balance": {
                  "amount": "62.00",
                  "currency": "USD"
                },
                "billing_type": "Standard Billing - finance charges",
                "chart_id": "017407",
                "preferred_language": "es"
              },
              "provider": {
                "id": 415,
                "email": "Amy.Ramos@nexhealth.com",
                "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": "2025-03-17T21:21:25.644Z",
                "authz": {
                  "permissions": {}
                },
                "display_name": "John Smith",
                "npi": "1912507500",
                "tin": "078051120",
                "state_license": "R219935",
                "specialty_code": "363L00000X"
              },
              "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"
              }
            }
          ],
          "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
}