Troubleshooting appointment writes

When you create an appointment with POST /appointments, NexHealth accepts the request first and writes the appointment into the health record system afterwards. A successful response means NexHealth accepted the appointment. It does not mean the appointment is in the health record system yet.

This guide covers how to tell whether a write succeeded, why writes fail, and what to do next.

Check whether the appointment was written

Subscribe to the appointment_insertion event before you create appointments. See Setting up webhooks and the Webhook Subscriptions reference.

You receive one of these events for each appointment you create:

All three events carry the same payload, which is the appointment object. The payload does not include the reason for a failure.

You can also read the appointment with GET /appointments/{id}. An appointment that has not been written has foreign_id set to null and last_sync_time set to null. Once it is written, foreign_id holds the ID of the appointment in the health record system.

Why a write fails

The error usually comes from the health record system itself, so there is no complete list. These are the most common causes.

The time was taken in the health record system. NexHealth reads the schedule from the health record system on a cycle, so a change made there can take several minutes to reach NexHealth. If office staff book the same time during that gap, /available_slots can still offer it, and the write is then rejected. Check the sync status of the location with GET /sync_status before you offer times. See Interpreting sync status.

The sync is down. For server-based systems, the office server may be off or the Synchronizer may have been removed. For cloud-based systems, office staff may not be logged in to the Chrome extension and the health record system. The write waits until the sync is back. If the start time of the appointment passes first, you receive appointment_insertion.timed_out.

The provider, operatory or appointment type does not fit the location. Use a provider_id, operatory_id and appointment_type_id that belong to the same location. Send operatory_id when the map_by_operatory attribute of the location is true. The slots returned by /available_slots give you a provider and operatory that can be booked together.

The health record system rejected the patient details. When the patient is new, NexHealth creates the patient in the health record system together with the appointment. Some systems reject a patient with a missing first or last name, or a name written in characters they do not accept. If the appointment is not written, the new patient is not written either.

The appointment was written and then changed. If you received appointment_insertion.complete and the appointment later looks different or is gone, office staff likely moved, edited or deleted it in the health record system. NexHealth keeps appointments in sync with the health record system, so the API reflects that change.

Retries

NexHealth does not retry a failed write automatically. Before you create the appointment again:

1. Read the original with GET /appointments/{id} and confirm that foreign_id is still null.
2. Confirm the time is still open with /available_slots.

A write can still succeed later if NexHealth support runs it again. You then receive appointment_insertion.complete for the same appointment id. Match events to your records by appointment id, and keep your record when you receive failed or timed_out.

How long a write takes

There is no fixed time. When the sync is online, writes usually complete quickly. When the office server is off, or nobody is logged in to the Chrome extension, the write waits.

Do not hold a patient or a caller waiting for the webhook. Handle failed and timed_out as follow-up work, for example by offering another time.

When to contact support

If the cause is not clear, email [email protected] with the subdomain, location ID, appointment ID and the time you created the appointment. Support can see the error returned by the health record system for that write.