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 any 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 OR 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 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


Default Values for Demographic Fields

There are some API users who may not want to ask their end users for their demographic information at intake time. If this includes you, you will want to speak with the practice you are working with and see if they are okay with you providing default values for these fields to be updated later by the office staff.

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:

  1. Search for an existing patient record using GET /patients
  2. If no existing patient is found, create one using POST /patients

If you attempt to create a new patient via a POST request, but their contact information 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.


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_type is 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

  "code": false,
  "description": "Description",
  "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": {
            "phone_number": "5163042196",
            "date_of_birth": "1964-05-03"
          "inactive": false,
          "last_sync_time": "string",
          "guarantor_id": 0,
          "unsubscribe_sms": 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": [
          "insurance_coverages": [
  "count": 2