Patients

A patient is a person who receives care from a practice.

Searching for patients

GET /patients searches for patients. A search always runs in one location, so subdomain and location_id are required.

A search returns all results for the search parameters you send. Send both an email address and a phone number, and the results include patients that match either one.

Search by name

The name parameter does a fuzzy match, not an exact match. This catches cases where a patient gives a preferred name, a legal name or a typo.

👍
Search parameters
Send as much contact information as you can when you search. Otherwise you may miss a patient who uses a different email, name or phone number.
If you plan to book appointments with the patient records, also set inactive and non_patient to false. This filters out patients you cannot book for.

Creating a new patient

To create a patient, you need basic contact and demographic information. This makes sure a patient created through the NexHealth Synchronizer API can also be created in any health record system. These fields are required:

First and last names
Email address
Phone number
Date of birth
Gender. It is optional in the API, and NexHealth stores Female when you leave it out, so send the real one. Dentrix and Eaglesoft need it to create the record.

🚧
Patient name character limits
Some health record systems limit the length of first and last names. Keep first names to 15 characters or fewer and last names to 20 or fewer so they are not cut off.

Do not create duplicate patients in a practice's system. To prevent duplicates, follow this workflow:

Search for an existing patient record with GET /patients.
If you find none, create one with POST /patients.

Suppose you send POST /patients and a record with the same name and date of birth already exists in NexHealth or in the health record system. You get a 400 Bad Request error with the message A patient with that information already exists -id=123. 123 is the id of the existing patient. When this happens, vet the match and prompt office staff to update or accept the contact information in your application. To get the existing patient back with a 200 instead of the error, set return_existing_if_match to true.

🚧
Patient insertion
NexHealth writes a patient to the health record system only when they book their first appointment. Until then, the patient exists only in NexHealth's database and their foreign_id_type is nex.
That first booking creates the patient in the system on athenahealth, Cloud9, Denticon, Dentrix, Dentrix Ascend, Dentrix Enterprise, Eaglesoft, eClinicalWorks, ModMed, NextGen Office, Open Dental and OrthoTrac. Curve Hero, Dolphin and PracticeWorks cannot take a new patient from the API. See Testing writes, per system.

Patients response

{
  "code": true,
  "description": null,
  "error": null,
  "data": [
    {
      "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": "5555550100",
        "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:20:53.043Z",
      "guarantor_id": 0,
      "unsubscribe_sms": true,
      "billing_type": "Standard Billing - finance charges",
      "chart_id": "017407",
      "preferred_language": "es"
    }
  ],
  "page_info": {
    "has_previous_page": false,
    "has_next_page": false,
    "start_cursor": "AAAAA",
    "end_cursor": "BBBBBB"
  }
}