Patients quickstart

A duplicate patient in a practice's system is the mistake to avoid.

The samples use the values from the Quickstart: NEX_TOKEN, NEX_SUBDOMAIN, NEX_LOCATION_ID and NEX_PROVIDER_ID. Node samples need Node 18 or later, saved as .mjs files. Python samples need the requests package.

1. Search first

Patient search always runs for one location. Pass as much contact information as you have.

curl -s --request GET \
  --url "https://nexhealth.info/patients?subdomain=$NEX_SUBDOMAIN&location_id=$NEX_LOCATION_ID&name=John%20Smith&date_of_birth=1964-05-03&inactive=false&non_patient=false" \
  --header "Nex-Api-Version: v3.0.0" \
  --header "Authorization: Bearer $NEX_TOKEN"

const { NEX_TOKEN, NEX_SUBDOMAIN, NEX_LOCATION_ID } = process.env;

const url = `https://nexhealth.info/patients?subdomain=${NEX_SUBDOMAIN}&location_id=${NEX_LOCATION_ID}&name=John%20Smith&date_of_birth=1964-05-03&inactive=false&non_patient=false`;

const res = await fetch(url, {
  headers: {
    "Nex-Api-Version": "v3.0.0",
    Authorization: `Bearer ${NEX_TOKEN}`,
  },
});
console.log(await res.json());

import os

import requests

res = requests.get(
    "https://nexhealth.info/patients",
    params={
        "subdomain": os.environ["NEX_SUBDOMAIN"],
        "location_id": os.environ["NEX_LOCATION_ID"],
        "name": "John Smith",
        "date_of_birth": "1964-05-03",
        "inactive": "false",
        "non_patient": "false",
    },
    headers={
        "Nex-Api-Version": "v3.0.0",
        "Authorization": "Bearer " + os.environ["NEX_TOKEN"],
    },
)
print(res.json())

name is a fuzzy match, so a nickname or a typo still finds the patient.
email and phone_number widen the search. A request with both returns patients matching the email and patients matching the phone number.
Set inactive and non_patient to false when you plan to book. That filters out records that cannot be booked.

2. Create the patient if there is no match

A new patient needs a first name, last name, email, phone number and date of birth, and a provider.

cat > patient.json <<EOF
{
  "provider": { "provider_id": $NEX_PROVIDER_ID },
  "patient": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "[email protected]",
    "bio": {
      "date_of_birth": "1990-12-10",
      "phone_number": "5165550100",
      "gender": "Female"
    }
  }
}
EOF

curl -s --request POST \
  --url "https://nexhealth.info/patients?subdomain=$NEX_SUBDOMAIN&location_id=$NEX_LOCATION_ID" \
  --header "Nex-Api-Version: v3.0.0" \
  --header "Authorization: Bearer $NEX_TOKEN" \
  --header "Content-Type: application/json" \
  --data @patient.json

const { NEX_TOKEN, NEX_SUBDOMAIN, NEX_LOCATION_ID, NEX_PROVIDER_ID } = process.env;

const url = `https://nexhealth.info/patients?subdomain=${NEX_SUBDOMAIN}&location_id=${NEX_LOCATION_ID}`;

const res = await fetch(url, {
  method: "POST",
  headers: {
    "Nex-Api-Version": "v3.0.0",
    Authorization: `Bearer ${NEX_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    provider: {
      provider_id: Number(NEX_PROVIDER_ID),
    },
    patient: {
      first_name: "Ada",
      last_name: "Lovelace",
      email: "[email protected]",
      bio: {
        date_of_birth: "1990-12-10",
        phone_number: "5165550100",
        gender: "Female",
      },
    },
  }),
});
console.log(await res.json());

import os

import requests

res = requests.post(
    "https://nexhealth.info/patients",
    params={
        "subdomain": os.environ["NEX_SUBDOMAIN"],
        "location_id": os.environ["NEX_LOCATION_ID"],
    },
    headers={
        "Nex-Api-Version": "v3.0.0",
        "Authorization": "Bearer " + os.environ["NEX_TOKEN"],
    },
    json={
        "provider": {
            "provider_id": int(os.environ["NEX_PROVIDER_ID"]),
        },
        "patient": {
            "first_name": "Ada",
            "last_name": "Lovelace",
            "email": "[email protected]",
            "bio": {
                "date_of_birth": "1990-12-10",
                "phone_number": "5165550100",
                "gender": "Female",
            },
        },
    },
)
print(res.json())

The new patient comes back in data.user.

Some health record systems limit name length. Keep first names to 15 characters and last names to 20 to avoid truncation.

3. Handle a match

If a patient with the same name and date of birth already exists, the create fails with 400 and this message, where 123 is the id of the existing patient.

A patient with that information already exists -id=123

To get the existing patient back with a 200 in place of the error, send return_existing_if_match set to true in the request body. Either way, check that the match is the right person before you book.

What happens next

NexHealth stores a new patient in its own database only. Its foreign_id_type is nex. NexHealth writes the patient into the health record system with their first appointment. If that appointment does not get written, neither does the patient. See How a write reaches the health record system.

What differs by health record system

The 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. On those systems, book with a patient the system already has.
Dentrix holds 15 characters of a first name and 20 of a last name. Keep names within that.
Dentrix and Eaglesoft need a gender to create a patient record. NexHealth stores Female when you leave gender out, so send the real one.
PATCH /patients changes the patient in NexHealth only. The system is not updated.

The full table is on Testing writes, per system.

For every field and filter, see the Patients reference.

1. Search first

2. Create the patient if there is no match

3. Handle a match

What happens next

What differs by health record system

What’s Next