Troubleshooting patients

Read the response body first. A failed request has code: false and the message in error. A successful one can still carry a warning in description.

Searching

The search returns nobody

Cause: The filters are too narrow, or the patient is inactive or marked as a non-patient and you filtered those out. date_of_birth is an exact match. email and phone_number match only what the office saved.
Fix: Search by name and date_of_birth first. name is a fuzzy match. Add email and phone_number to widen the search, not to narrow it. Drop inactive=false and non_patient=false to see every record, then decide.

The search returns patients from another office

Cause: Several locations share one health record system server. Without location_strict=true, GET /patients searches the whole server.
Fix: Send location_strict=true. To see where a patient belongs, read location_ids on GET /patients/{id}.

Note that following parameters are ignored: location_id. in description on GET /patients/{id}

Cause: location_id is not a parameter on this endpoint. The request still succeeds.
Fix: Leave location_id off. Read location_ids in the response instead.

The same person shows up twice

Cause: The office has two records for the patient, or one record is the new_patient placeholder from an API booking and the other is the record the office created afterwards.
Fix: Filter with new_patient=false to drop placeholders. For true duplicates, ask the office to merge the records in the health record system. Do not create a third record.

Creating

A patient with that information already exists -id=123 on POST /patients

Cause: A patient with the same date of birth, name and phone number exists in NexHealth or in the health record system. 123 is their ID.
Fix: Use that patient. Send return_existing_if_match: true to get the existing record back with a 200 instead of the error. Let the patient or the office confirm the match before you book.

400 with a field error on POST /patients

Cause: A required field is missing or malformed. first_name, last_name, email, bio.date_of_birth, bio.phone_number and provider.provider_id are required. The email has to be a valid address. The date of birth cannot be in the future or more than 130 years in the past.
Fix: Send every required field. Use YYYY-MM-DD for the date of birth.

The name was cut short in the health record system

Cause: Some systems limit first names to 15 characters and last names to 20.
Fix: Keep names inside those limits.

The gender is wrong in the health record system

Cause: bio.gender was left out, so it defaulted to Female. The default exists so every system accepts the record.
Fix: Send bio.gender when you have it. The office updates it at the first visit.

Data source must exist on POST /patients/{id}/alerts

Cause: The patient exists only in NexHealth. Their foreign_id is null and foreign_id_type is nex. A patient created through the API is written into the health record system with their first appointment.
Fix: Book the patient's first appointment, wait for appointment_insertion.complete, then add the alert.

Patient with id 123 not found on POST /appointments

Cause: The patient was created through the API for one location and their first appointment is going to another location.
Fix: Book the first appointment at the location where you created the patient.

Cannot create an appointment where the patient attribute new_patient=true on POST /appointments

Cause: Dentrix and Denticon. A new patient exists only on their first appointment until the office makes them a patient of record. Their foreign_id ends in _np.
Fix: Ask the office to convert the patient in the health record system. On Dentrix, you can move the first appointment with PATCH /appointments/{id} until then.

Keeping a copy

The patient never appears in the health record system

Cause: The patient is stored in NexHealth only. The write happens with the first appointment, and that appointment was not written. Its foreign_id is null.
Fix: Check for appointment_insertion.failed and appointment_insertion.timed_out. See Troubleshooting appointment writes.

Your copy of a patient is stale

Cause: You are polling without updated_since, or the sync has not read the office's change yet. NexHealth reads on-premises systems every 10 to 15 minutes, and gaps are longer overnight and on weekends.
Fix: Subscribe to patient_updated. If you poll, pass the time of your last run as updated_since and sort by updated_at. Check read_status_at on GET /sync_status to see when the last read happened.

A patient you stored is gone

Cause: It was a new_patient placeholder. When the office created the real record and NexHealth read it, NexHealth linked the records and deleted the placeholder.
Fix: Treat new_patient: true records as temporary. Subscribe to patient_updated and patient_created so your copy follows the change.

Still stuck

Email [email protected] with the request, the full response body, the subdomain, the location_id and the time of the call in UTC. Every message the API returns is in the Errors reference.