---
updatedAt: 2026-10-17T02:38:08.000Z
agentTools:
  projectIndex: https://docs.nexhealth.com/llms.txt
---

# How a write reaches the health record system

A successful response means NexHealth accepted the record. A webhook tells you when it is in the health record system.

NexHealth keeps a copy of each practice's data and keeps it in sync with the health record system. Reads come from that copy. Writes go to NexHealth first and into the health record system afterwards.

```mermaid
sequenceDiagram
    participant A as Your app
    participant N as NexHealth
    participant H as Health record system
    A->>N: POST /appointments
    N-->>A: 201 Created. The record is accepted.
    N->>H: Write the appointment
    H-->>N: Saved, or failed
    N-->>A: Webhook: appointment_insertion
```

## Reads

NexHealth copies changes from the health record system on a cycle. A change made in the health record system can take several minutes to show up in the API.

[Sync status](https://docs.nexhealth.com/docs/interpreting-sync-status) tells you how fresh the data is for a location.

## Writes

A write has two stages.

1. **Accepted.** You call the API, for example `POST /appointments`. A successful response means NexHealth accepted the record. It is not in the health record system yet.
2. **Written.** NexHealth writes the record into the health record system. When that finishes, NexHealth sends you a webhook.

## How to tell whether a write landed

Subscribe to the insertion event for each resource you write. Do this before you start writing.

| You write         | Subscribe to              |
| :---------------- | :------------------------ |
| Appointments      | `appointment_insertion`   |
| Payments          | `payment_insertion`       |
| Adjustments       | `adjustment_insertion`    |
| Patient documents | `document_insertion`      |
| Form responses    | `form_response_insertion` |

The event name carries the result. For an appointment you receive one of these.

| Event                             | What it means                                                                                       |
| :-------------------------------- | :-------------------------------------------------------------------------------------------------- |
| `appointment_insertion.complete`  | The appointment is in the health record system.                                                     |
| `appointment_insertion.failed`    | NexHealth tried to write the appointment and the write did not succeed.                             |
| `appointment_insertion.timed_out` | The write could not reach the health record system before the start time of the appointment passed. |

You can also read the record back. An appointment that NexHealth has not written yet 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.

See [Setting up webhooks](https://docs.nexhealth.com/docs/webhooks) for setup and the [Webhook Subscriptions](https://docs.nexhealth.com/reference/webhook-subscriptions) reference for every event and payload.

## How long a write takes

There is no fixed time. When the sync is online, writes usually complete quickly. A write waits when the sync is offline.

* **Server-based systems.** The sync is offline when the office server is off.
* **Cloud-based systems.** The sync is offline when nobody at the office is logged in to the NexHealth Chrome extension and the health record system.

Do not hold a patient or a caller waiting for the webhook.

## When a write fails

NexHealth does not retry a failed write automatically. Before you send it again, read the original record and confirm that `foreign_id` is still `null`.

[Troubleshooting appointment writes](https://docs.nexhealth.com/docs/troubleshooting-appointment-writes) lists the common causes and what to do for each.

## What this means for your app

* Treat a successful response as accepted, not done.
* Store the NexHealth `id` and match webhook events to it.
* Handle `failed` and `timed_out` as follow-up work, for example by offering another time.
* Check the sync status of a location before you offer times.

# Sibling pages

* [Start here](https://docs.nexhealth.com/docs/start-here.md)
* [Quickstart: book your first appointment](https://docs.nexhealth.com/docs/quickstart.md)
* [Sandbox and test mode](https://docs.nexhealth.com/docs/sandbox-and-test-mode.md)
* [Institutions, syncs, and locations](https://docs.nexhealth.com/docs/institutions-syncs-and-locations.md)
* [What you can build](https://docs.nexhealth.com/docs/whats-possible-with-nexhealth.md)
* [Glossary](https://docs.nexhealth.com/docs/glossary.md)
* [MCP server](https://docs.nexhealth.com/docs/use-the-docs-with-ai-tools.md)

# What’s Next

* [Setting up webhooks](https://docs.nexhealth.com/docs/webhooks.md)