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 date of birth, name and phone number 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

A new patient is stored in NexHealth only. Its foreign_id_type is nex. The patient is written into the health record system with their first appointment. If that appointment is not written, the patient is not written either. See How a write reaches the health record 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’s Next