Why Did NexHealth v3 Accept an Appointment Outside Working Hours?

NexHealth v3 can accept an appointment outside a provider’s working hours because POST /appointments no longer performs the working-hours validation used by the legacy API. NexHealth’s migration guide says an out-of-hours booking can be accepted and written back to the EHR. A successful request therefore does not prove that the selected time appeared in the current bookable-slot response.

The safe boundary belongs in the booking flow. Check the requested provider, location, appointment type, operatory, duration, and start time against GET /available_slots before submission. After submission, monitor the appointment insertion result. Keep transport acceptance, EHR completion, and patient attendance as separate states.

What changed in NexHealth v3 appointment creation?

NexHealth documents a specific breaking change in v3.0.0, also published as v20240412. The legacy v2.2.2 endpoint rejected bookings outside a provider’s synced working hours. Version 3 does not run that check. Its migration guide says those bookings are accepted and written back to the EHR.

This change affects the meaning of a successful create response. The endpoint still accepts an appointment body and returns the documented success status, but the server no longer uses working hours as a rejection gate. A client that relied on a 400 response to stop invalid selections has lost that control after migration.

The new behavior does not make working hours irrelevant. NexHealth still uses them when calculating bookable times through GET /available_slots. The difference is where validation happens. The read endpoint computes eligible choices; the write endpoint accepts the selected appointment without repeating the old working-hours check.

That distinction also separates HG074 from the related problem of an empty NexHealth availability response. An empty result asks why no options were returned. An out-of-hours write asks why creation succeeded despite the configured boundary.

How should the selected time be validated before submission?

Validate the proposed start time against a fresh GET /available_slots response for the same booking context. NexHealth says this endpoint returns bookable slots for the requested locations and date range, computed from provider availabilities and existing appointments. It requires the institution subdomain, start date, number of days, and location IDs, plus provider IDs or an appointment type.

Match more than the displayed clock time. Confirm the returned location ID, provider ID, operatory ID when applicable, and local start and end time. Separately confirm that the request used the intended appointment type and its configured duration. A 10:00 slot for one provider or operatory does not authorize 10:00 for another.

Operational inference: perform the availability check as close as practical to the create request. The official documentation says to validate against /available_slots before booking, but it does not promise to reserve a slot between the read and write. A later appointment or calendar change can make an earlier response stale.

Do not solve this by copying clinical details into the request log. A sanitized record needs the API version, institution alias, location ID, provider ID, operatory ID, appointment type ID, requested time, response status, and correlation ID. It does not need a patient’s name, phone number, reason for visit, treatment notes, or insurance information.

Why is a successful API response not the final booking state?

NexHealth describes appointment creation as asynchronous. Its Appointments reference recommends subscribing to the appointment insertion webhook, which reports complete or failed when the integration inserts the appointment into the EHR. The initial create response and the downstream EHR result therefore answer different questions.

A practical state model has at least four values: selected from current availability, accepted by the API, completed in the EHR, and later attended or not attended. The first three are technical or operational events. Attendance belongs to the clinic’s later workflow. Collapsing them into one “booked” flag hides failures and inflates acquisition reporting.

Apointoo should preserve the returned appointment identifier and a non-sensitive correlation key, then update the operational state from the insertion webhook. It should not send the appointment type, notes, patient identity, or other health context to advertising platforms. The guide to clinic booking outcome taxonomy explains why internal outcomes and ad-platform payloads need different detail.

If the insertion fails, keep the error category and timestamp without storing the raw patient payload in general logs. Route the case to the approved operational queue. Do not tell the patient or reception team that the EHR booking exists until the integration has reported completion or the practice has verified it directly.

Can availability change between the check and the create request?

Yes, that is a reasonable operational risk even though NexHealth does not document a temporary reservation created by GET /available_slots. The endpoint computes bookable time from provider availability and existing appointments. Another booking or schedule update can occur after the response and before the create request.

Operational inference: treat each slot response as a current observation, not a lock. Keep the interval between selection and submission short. When the user returns to an old browser tab, changes provider, changes appointment type, or resumes after a long pause, request availability again instead of trusting cached options.

Do not retry a create request blindly after a timeout. First determine whether NexHealth accepted the original request and whether the insertion webhook later completed it. An automatic retry without an idempotency decision can create duplicate operational work or competing appointment records. The general process for preventing duplicate appointment reminders uses the same ownership principle: one event needs one authoritative state and one controlled retry path.

If the selected slot is no longer available, return the user to a new availability result. Do not silently move the appointment to a nearby time. A different time is a different choice and may require renewed confirmation from the person booking.

What evidence should a booking integration retain?

Retain enough evidence to reconstruct the technical decision without creating a shadow patient record. For the availability check, keep the request time, API version, sanitized booking scope, and the selected returned slot. For creation, keep the correlation ID, response code, returned appointment ID, and insertion status. Apply normal retention and access controls to this operational record.

Use structured fields rather than dumping full requests and responses. Full payloads may contain patient identity, contact details, notes, or other data that belongs in the approved scheduling system. Redaction after collection is weaker than never collecting the unnecessary field. Support screenshots should also use a sandbox or synthetic appointment.

Separate the booking system’s source from the marketing source. A successful NexHealth write should not replace the campaign or channel that originally influenced the request. The article on appointment source versus marketing source gives a durable model for that distinction.

For an escalation, provide the endpoint, sanitized parameters, API version, timestamps, correlation ID, expected slot, observed status, and webhook result. State whether the time appeared in the immediately preceding availability response. That packet helps an integration team diagnose the path without exposing patient information.

How should a team test the v3 booking boundary?

Use a sandbox when available. Otherwise, obtain clinic approval for a future synthetic window that cannot displace real care. Create no patient record with a real person’s identity. Keep the test outside advertising systems and remove synthetic records through the practice’s approved cleanup process.

1. Send every request with the intended Nex-Api-Version header.
2. Query /available_slots for one verified provider, location, appointment type, and date.
3. Choose a returned slot and save only sanitized request evidence.
4. Submit the appointment once and record its response and identifier.
5. Wait for the insertion webhook and record complete or failed.
6. Verify the synthetic appointment in the correct EHR calendar.
7. Test an out-of-hours time only in a controlled environment where an accepted write cannot affect a real schedule.

The pass condition is precise: the interface offers only current returned slots, submission uses the same scope, and the system does not claim EHR completion before the webhook or direct verification. A separate test should confirm that rescheduling keeps the original acquisition lineage, as described in preserving booking source after a reschedule.

Frequently asked questions

Does NexHealth v3 reject appointments outside working hours?

No. NexHealth’s migration guide says v3 removed the working-hours validation performed by v2.2.2. Out-of-hours bookings can be accepted and written to the EHR. Validate the selected time against GET /available_slots before creating the appointment.

Does HTTP 201 mean the appointment reached the EHR?

Not by itself. NexHealth describes appointment creation as asynchronous and recommends the appointment insertion webhook. Treat the create response as API acceptance, then use the webhook’s complete or failed result to track EHR insertion.

Should the integration cache available slots?

NexHealth documents available slots as bookable times computed from availability and existing appointments, but it does not document a reservation created by reading them. If the booking context or time has changed, request current availability again. This refresh rule is an operational inference, not a vendor guarantee.

Can the booking event be sent to Google Ads?

Only a separately approved, privacy-safe conversion event should enter an advertising workflow. Do not send patient identity, appointment type, reason for visit, notes, or other health data. API acceptance also should not be labeled as attendance or revenue.

References

• NexHealth, Migration Guide to Stable, reviewed August 16, 2026.
• NexHealth, View available slots, reviewed August 16, 2026.
• NexHealth, Appointments, reviewed August 16, 2026.