Author: cmsapointoo

A secondary or shared Google Calendar does not block Jane online booking because Jane’s documented inbound sync reads only the primary calendar of the connected Google account. Events on that primary calendar appear in Jane as Busy - Google Calendar Event and prevent patients from booking the covered time online. Events on other calendars in the same account do not enter Jane through this connection.

The confusion comes from treating every calendar visible in Google as one availability source. Google can show primary, secondary, shared, and subscribed calendars together. Jane does not evaluate all of them for inbound blocking. Calendar ownership, sync direction, and administrative double booking create separate boundaries.

Why do secondary Google calendars stay invisible to Jane?

Jane states that only the primary calendar for the connected Google account is synced. Events from secondary or shared calendars do not show in Jane. The primary calendar is the first calendar listed under My Calendars in that Google account. Moving between calendars in the Google interface does not change which one Jane reads.

Jane also limits each staff profile to one connected Google account. That means connecting an account with a convenient email address is not enough. Its primary calendar must be the calendar that contains the events intended to block patient booking. A team can otherwise see the event in Google, see a Connected badge in Jane, and still have no corresponding Busy block.

This is a documented coverage boundary, not proof of an intermittent failure. Operational inference: identify the event’s actual calendar before reconnecting accounts or changing shifts. Check which calendar owns it, not merely which account can view or edit it.

Keep that availability diagnosis separate from acquisition attribution. A booking that remains available because a block was absent still has its own operational source. The guide to appointment source versus marketing source explains why calendar ownership should not rewrite campaign or channel data.

What is the difference between Jane’s two calendar directions?

Jane documents two separate one-way flows rather than an automatic two-way sync. The inbound Google Calendar connection brings primary-calendar events into Jane as Busy blocks. The outbound Jane calendar subscription sends appointments or shifts to external calendar software through private iCal URLs. These flows solve different jobs and should not be used as proof of each other.

The outbound subscription is view-only. Jane says it does not change the external calendar to show the user as busy and cannot be edited to manage availability. Subscribing to a Jane feed in Google therefore does not make a secondary Google calendar an inbound blocker. It only lets the staff member view selected Jane schedule information in an external calendar.

Name the direction before testing: “Google primary to Jane” for inbound blocking, or “Jane to external calendar” for outbound visibility. Avoid calling either path “two-way” in runbooks. That label hides which system owns the event and enforces availability.

Calendar movement should not create new demand in reports. If an appointment is changed after booking, use the separate method for preserving original booking source after a reschedule while recording the later action independently.

How should a clinic identify the primary Google calendar?

Jane identifies the primary calendar as the first calendar under My Calendars in the connected Google account. Open the test event and verify its calendar field. A color, shared access, or appearance in the same weekly grid is not enough. The event must belong to that primary calendar for Jane’s documented inbound sync to import it.

If the event belongs to a secondary or shared calendar, choose an operating rule before copying it. The clinic might use each practitioner’s primary calendar, connect another account, or manage the block in Jane. Those are workflow choices. Jane’s cited guides do not prescribe one migration strategy.

Operational inference: do not duplicate a whole shared calendar blindly. Repeated and all-day events may block more time than intended, and copied events can lose their ownership context. Test one non-sensitive event first. Use a neutral title because Jane hides titles from its schedule view, but Google permissions still govern who can see the original event.

How can staff verify that a primary-calendar event arrived?

A synced Google event should appear on the Jane schedule with the label Busy - Google Calendar Event. Jane says the schedule should update after about one minute, though a page refresh may be needed. The inbound window covers events from the past 30 days through 12 months into the future.

Create or select one neutral test event on the primary calendar at a time that is otherwise offered online. Wait for the documented update period, refresh Jane, and confirm the Busy block appears at the same time. Then check the patient-facing booking path with a non-identifying test. Do not use a patient’s existing appointment or private meeting details as test content.

If the Busy block does not appear, capture the connected account, staff profile, event calendar, time zone, creation time, and refresh state. Do not disconnect first. Jane says disconnecting removes previously synced Google events from its schedule, so preserve evidence before changing the connection.

A successful block proves availability behavior for that test. It does not prove reminder ownership or message suppression. Clinics using several systems should separately test duplicate appointment reminder paths after the booking workflow is stable.

Why can staff still book over a Google Busy block?

Jane distinguishes patient online booking from administrative booking. Imported Google events block the covered time for patients online. However, if administrative double booking is enabled in Schedule Settings, staff can still create an appointment at the same time as the Google event. Seeing an internal override does not mean the inbound sync failed.

Test the two paths separately. First, use the online booking experience to confirm the time is unavailable to a patient. Second, inspect the administrative schedule and relevant double-booking setting. Record whether the staff action displayed a warning or allowed the overlap, but do not infer a specific warning behavior that Jane’s cited calendar guide does not document.

Operational inference: clinics that expect a hard internal block should review who may double-book and under which procedure. The cited sources establish that the override can exist, not which staff roles should have it or how a clinic must govern exceptions. That decision belongs to clinic policy and current Jane configuration.

What privacy details matter in Jane calendar subscriptions?

The inbound Google sync shows only Busy blocks in Jane, without the Google event title, description, or guest information. Jane says these events do not appear in reports or exports. This limits what Jane displays, but it does not turn Google Calendar into a suitable place for patient or treatment details.

The outbound iCal subscription has a different privacy concern. Jane notes that appointment notes can contain PHI or other confidential information and lets staff exclude notes through Privacy and Sharing settings. It also warns that Google Calendar subscription defaults may expose details to people who can view the Google calendar unless sharing is configured carefully.

Use neutral synthetic events, keep private calendar URLs confidential, and confirm sharing settings. An iCal URL is an access mechanism, not a public link for tickets or shared documents. Troubleshooting needs timestamps and configuration evidence, not names, contact details, reasons for visits, or clinical notes.

What is a reliable test sequence for this problem?

A reliable test proves calendar ownership, inbound import, patient blocking, and administrative override as separate outcomes. Changing several settings at once makes the result hard to explain. Use one staff profile, one connected account, one neutral event, and one otherwise bookable time.

1. Confirm the Google account shown as Connected in the staff profile.
2. Identify the primary calendar under that account’s My Calendars list.
3. Create a neutral test event on the primary calendar.
4. Wait about one minute, refresh Jane, and find the Busy block.
5. Confirm the time is unavailable through patient online booking.
6. Test administrative booking separately if double booking is enabled.
7. Repeat with a secondary calendar only to demonstrate the documented coverage boundary.

Record each result without creating a real patient record. If a synthetic booking is permitted and necessary, remove it through the clinic’s approved process and preserve its test label. Later reporting should use a stable outcome taxonomy rather than treating a calendar test as a genuine booking. The clinic booking outcome taxonomy provides that separation.

Frequently asked questions

Can Jane sync a shared Google calendar for blocking?

Jane’s guide says secondary and shared calendars do not sync into Jane. Only the primary calendar of the connected Google account creates the documented Busy blocks. Shared access to an event does not make that event part of the primary calendar.

Does subscribing to Jane’s iCal feed create Busy time in Google?

No. Jane describes its calendar subscription as view-only and says it does not change the external calendar to show the user as busy. The iCal feed displays Jane appointments or shifts externally; it is not the inbound Google-to-Jane availability connection.

Why can reception book a time that patients cannot?

Administrative double booking may be enabled in Jane’s Schedule Settings. In that case, a Google event still blocks patient online booking, but staff can book administratively at the same time. Test the patient and staff paths independently before diagnosing a sync failure.

How far does Jane import Google Calendar events?

Jane says the inbound sync brings over all primary-calendar events from the past 30 days through 12 months into the future. An event beyond that window is not a valid test of current coverage. A new event should update after about one minute, though Jane may need a refresh.

References

• Jane App, Google Calendar Sync, reviewed August 16, 2026.
• Jane App, Subscribing to Your Calendar for Staff, reviewed August 16, 2026.

An open EHR calendar does not automatically mean NexHealth can return online-bookable times. NexHealth documents a narrower calculation: GET /available_slots starts with configured working hours, evaluates the requested provider, location, date range, and appointment type, then removes existing appointments and calendar unavailabilities. If the first boundary is empty or the request filters out every matching record, the response can contain no slots while staff still see unused time in the EHR.

The EHR view answers whether time appears unused in the source schedule. NexHealth answers whether that time meets the integration’s booking rules. Confusing the two can hide a mismatch in working hours, appointment-type assignment, operatory scope, or request parameters.

What does an empty NexHealth availability response mean?

An empty slot list means the request produced no bookable time under the configuration and filters NexHealth evaluated. It does not, by itself, prove the EHR is full, the provider is off, synchronization failed, or the endpoint is unavailable. NexHealth’s Scheduling Configuration Guide even shows a successful HTTP 200 response with an empty slots array when active availability is missing.

The documented calculation has three main inputs: working hours define candidate time, calendar unavailabilities remove blocked time, and NexHealth appointment types determine which service can use a working-hour record and its duration. The request window and identifiers decide which records enter that calculation. A clean diagnosis checks each layer instead of using the EHR’s visual calendar as the only evidence.

Operational inference: save the response, request parameters, timestamp, API version, and relevant record identifiers before editing anything. The record will show whether a later result followed a configuration change or a different request. Keep patient-identifying screenshots and appointment details out of the support ticket.

Why can the EHR look open when working hours are missing?

NexHealth states that working hours are required before GET /available_slots can show real-time availability. Those records define when online booking is allowed. When none exist for the requested provider and location, NexHealth returns no availability even if the EHR contains a visibly open part of the day. Unused EHR space is not a substitute for a configured online-booking boundary.

Working hours may be manual or synced. Manual records are managed through NexHealth. Synced records come from supported EHR systems and are not edited in NexHealth. The source field identifies the path. NexHealth instructs users to update synced hours in the EHR.

Operational inference: query working hours for the same provider and location used in the empty slot request. Confirm that at least one active record covers the requested date and local time. Then compare its source, days, specific date, begin time, end time, provider, location, and operatory. Do not create manual hours merely to make a test pass if synced hours are supposed to be authoritative.

Mixing manual and synced working hours is possible, but NexHealth warns that overlapping records can affect returned slots. Choose the source deliberately. A practice comparing owned booking with a marketplace should also keep this technical boundary separate from the broader question of whether it needs marketplace demand or owned scheduling.

How does appointment type filtering remove otherwise open time?

An appointment_type_id does more than name the visit. NexHealth says it sets slot length from the appointment type’s minutes and restricts the calculation to working-hour records associated with that type. If no matching working hour has that type assigned, the endpoint correctly returns no slots, even when other appointment types or unfiltered requests show availability.

Compare two requests that differ only by the appointment-type filter. If the provider request returns time and the filtered request does not, inspect the type’s working-hour assignment. Confirm that the application sent the intended NexHealth type ID. A similar EHR label does not prove the records are the same.

NexHealth also distinguishes its appointment types from EHR appointment descriptors. The former controls scheduling categories, duration, and working-hour eligibility. The latter describes how a booked appointment is written into the EHR. Do not change descriptor mapping to solve an empty slot search unless separate evidence shows a write-back problem.

Keep the service selection captured as operational evidence without copying treatment details into marketing tools. The same separation used to preserve booking source after a reschedule helps here: scheduling configuration, booking lineage, and acquisition attribution should remain distinct records.

Which provider, location, operatory, and date filters should be checked?

The /available_slots request requires subdomain, lids[], start_date, days, and Nex-Api-Version, plus at least one pids[] or appointment_type_id. NexHealth recommends requesting no more than 14 days for better performance. A technically valid request can still search the wrong location, provider, date window, or working-hour source and therefore return no relevant slots.

Rebuild one minimal request from verified identifiers. Include the required subdomain, location, start date, day count, API version, and provider or appointment type. Then add working-hour source, label, and operatory filters one at a time. This sequence is an operational diagnostic method, not a NexHealth guarantee, but it makes the filter that removes availability visible.

Operatory mapping needs special care. NexHealth says operatory_id is required when a location uses map_by_operatory = true for working-hour creation or updates. Its configuration guide also says an availability query without an operatory can return only the first available operatory. That may produce an incomplete view rather than a universal no-availability conclusion.

Record scheduling source separately from marketing source while testing these identifiers. The guide to appointment source versus marketing source explains why a request parameter should not overwrite the campaign or channel that originally influenced a booking.

How do appointments and calendar unavailabilities affect the result?

After NexHealth identifies candidate time inside working hours, it subtracts booked appointments and calendar unavailabilities. The configuration guide describes an unavailable calendar record with unavailable: true; any overlapping window is excluded from /available_slots. A provider can therefore have valid working hours and still have no remaining bookable interval for the requested duration.

Compare the exact time window, not only the number of visible entries. A short opening may be too small for the appointment type’s duration. A block may overlap part of a candidate slot. A lunch gap may be represented as missing working hours rather than an explicit unavailable record. These documented models can produce similar screens but require different configuration checks.

Operational inference: use a synthetic test window approved by the practice, with no patient-identifying data. Confirm the provider, local date, duration, and expected operatory. Then inspect the working hour and any overlapping appointment or unavailability record. Do not remove a real appointment or administrative block simply to force availability.

How should a team run a controlled availability test?

A controlled test should change one variable at a time and keep the request evidence. Start with a narrow date range, verified location, and verified provider. Confirm working hours first. Then compare an unfiltered provider request with the intended appointment type, operatory, and working-hour source filters. Stop when one added filter changes the result from available to empty.

1. Capture the empty response and exact request without credentials.
2. Retrieve matching working-hour records and confirm active coverage in local time.
3. Check appointment-type assignment and duration against those records.
4. Check operatory scope and any working-hour source or label filter.
5. Inspect overlapping appointments and calendar unavailabilities.
6. Repeat the original request and record whether the same slot appears.

Success means the API returns the expected slot for the intended configuration, not merely that any slot appears somewhere. Keep reminders out of this test unless the booking itself succeeds. If multiple systems may message the same appointment later, use the separate process to assign one reminder owner per message purpose.

What evidence should be sent to support or an integration team?

A useful escalation packet contains the request path, sanitized parameters, response, API version, capture time, relevant IDs, and matching working-hour records. Include whether hours are manual or synced and identify the EHR product. Omit names, contact details, treatment descriptions, and other patient data.

State the expected result precisely: for example, one provider should have one bookable interval at a stated local time for one appointment type and operatory. Attach the observed result and the last known successful test if available. Do not claim a synchronization defect until the records and request prove that the documented inputs all match.

If the slot later becomes an appointment, preserve the original operational source and subsequent action history. That prevents a technical retest or reschedule from being counted as new demand and keeps the troubleshooting record useful without turning it into a patient chart.

Frequently asked questions

Does an open EHR calendar guarantee NexHealth availability?

No. NexHealth evaluates only configured working hours and then applies the request’s provider, location, appointment type, operatory, and date scope before subtracting appointments and unavailabilities. The EHR can look open while no eligible NexHealth working-hour record covers that time.

Can a successful HTTP 200 response still contain no slots?

Yes. NexHealth’s configuration guide shows a successful response with an empty slots array when active availability is missing. Treat transport success and scheduling eligibility as separate checks. Save the response description and next_available_date with the sanitized request.

Why does availability disappear when appointment_type_id is added?

The appointment type narrows the search to working hours associated with that type and supplies the slot duration. If no working-hour record carries that association, NexHealth documents that no slots will return. Verify the NexHealth type ID rather than matching labels by sight.

Should the team create manual working hours to fix an empty response?

Not automatically. First determine whether the location uses manual or synced working hours. NexHealth says synced hours are managed in the EHR, while manual hours are edited through NexHealth. Adding a second source without a clear ownership decision can create overlapping records and misleading results.

References

• NexHealth, Working Hours, reviewed August 16, 2026.
• NexHealth, View available slots, reviewed August 16, 2026.
• NexHealth, Scheduling Configuration Guide, reviewed August 16, 2026.

Google can reject or remove a clinic appointment link when the Business Profile is not verified, the URL is malformed, the destination is not dedicated to that location, the page cannot complete the booking action, or Google’s verification crawler cannot load it successfully. The practical fix is to identify which requirement failed, repair that exact problem, and request review.

Do not treat approval as proof that appointments are reaching the schedule or attribution is working. It proves only that the link passed Google’s current Business Profile review. Keep patient names, appointment details, conditions, and other health information out of the URL, analytics parameters, support evidence, and Google Ads data.

What does Google check before accepting the link?

Google’s business link policy starts with the profile itself. The Business Profile must be verified before the business can add links. The URL must be valid and cannot be malformed. It also needs to lead to a dedicated landing page for the specific business location rather than an unrelated homepage or a page for another branch.

The destination must let the user complete the action represented by the link. For an appointment link, that means the journey must support booking, not merely describe services, display a phone number, or send the visitor through a route that never reaches a booking action. Google also disallows social media links, messaging links, app store links, and link shorteners in this feature.

These are separate checks. A technically valid URL can still fail because it points to a generic corporate page. A location page can still fail because the appointment action is unavailable. Start from the rejection notice or current public state and test each requirement without assuming one successful check clears the others.

Why can a working page still fail verification?

A page may open for clinic staff while remaining inaccessible to Google’s automated verification. Google says it crawls business links regularly, potentially once each day, to confirm that they remain valid and compliant. Its documented crawler uses the Google-BusinessLinkVerification user agent. The crawler must reach the page without being stopped by a login, CAPTCHA, bot protection, rate limit, IP block, or geographic restriction.

The server also needs to return a successful HTTP response. A friendly error screen, redirect loop, access-denied page, or challenge page can look like a designed website in a browser while returning a failed response to the crawler. Test the final destination, including every redirect, from outside the clinic network. Confirm that the public booking journey works without an authenticated staff session.

Do not permanently weaken the whole site to solve a narrow crawl problem. Review web application firewall logs and hosting responses, identify the rule affecting the documented crawler, and make the smallest safe correction. If a vendor owns the booking page, give it the exact URL, response evidence, time of failure, and Google’s crawler requirement.

Does the page belong to the correct clinic location?

Location specificity matters when a practice has several branches or schedules. The link should open a landing page dedicated to the location represented by that Business Profile. A visitor should not have to guess which clinic is available.

Check the public business name, address, phone, services, and booking destination as one unit. The location page can use a shared scheduling platform, but the route should preserve the intended branch and offer an action for that branch. If a central selector is unavoidable, confirm that it still satisfies Google’s dedicated-page requirement before relying on it.

This is also an ownership issue. A profile may contain clinic-added links and links supplied through another provider. Read who controls a Google Business Profile booking link before editing the wrong source. Removing a provider link has a separate workflow, covered in the guide to removing a third-party booking link.

How should the clinic diagnose the removal?

Build a short evidence record before changing the page. Record the exact profile and location, the URL entered, the notice shown by Google, the date observed, the managing account, and the public result in Search and Maps. Capture only operational evidence. Do not include patient records, completed booking details, free-text health information, or screenshots containing real appointments.

1. Confirm that the correct Business Profile is verified.
2. Copy the submitted URL exactly and check for malformed characters or accidental spaces.
3. Follow every redirect and record the final URL and HTTP response.
4. Verify that the destination is dedicated to the profile’s location.
5. Complete an approved synthetic booking test without using a real patient’s identity.
6. Review firewall, bot protection, CAPTCHA, login, rate-limit, IP, and geographic controls.
7. Confirm that the URL is not a prohibited social, messaging, app store, or shortened link.
8. Check whether the profile has reached Google’s limit of 20 links for that transaction type.

One failed item is enough to explain a rejection, but passing this checklist does not reveal Google’s internal decision. It produces useful evidence for a correction and review request. Preserve before-and-after screenshots and response details so the next operator can see what changed.

What should be repaired before requesting review?

Repair the narrowest confirmed failure. Correct a malformed URL. Replace a generic homepage with the location’s booking destination. Restore the booking action if the page only describes the clinic. Fix a failed server response or redirect. Adjust a verified protection rule if it blocks the documented crawler. Remove a prohibited link type rather than wrapping it in a shortener.

Then repeat the checks from a clean browser and external network. Use a synthetic record approved by the clinic and handle it under the scheduling system’s test procedure. Confirm location, service availability, time zone, and final schedule without adding clinical detail.

Submit a review request only after the destination is stable. State the original issue, the exact repair, the current URL, and the evidence that it now meets the relevant requirement. Avoid broad claims such as “everything is fixed.” A focused request is easier to audit if the link is rejected again.

What does approval prove, and what does it not prove?

Approval means the business link was accepted under Google’s current checks at that point in time. Because Google may recrawl links, later changes to the page, redirect, firewall, or vendor setup can affect continued eligibility. Add the booking URL to the clinic’s release and vendor-change checklists.

Approval does not prove that every user can find the link, that every booking enters the practice management system, or that reminders and rescheduling work. It also does not prove campaign attribution. A Business Profile action and a marketing source are different facts, as explained in appointment source versus marketing source.

Google’s profile decision also does not authorize patient or health data to enter advertising systems. Keep sensitive values out of URL paths, query parameters, page titles, analytics events, and Google Ads payloads. Use generic operational states for approved internal tests and assess every external data transfer under its own privacy, contract, and platform-policy gate.

How can the clinic verify the repaired journey?

Use three proof layers. First, technical proof: the public URL resolves, redirects are intentional, and the server returns a successful response without login or challenge. Second, operational proof: a synthetic booking reaches the correct location and schedule. Third, public proof: the appointment action appears on the intended Business Profile in the surfaces the clinic relies on.

Record each layer separately. A visible link can open a broken journey. A website test does not prove the profile displays the link, and a scheduled appointment does not identify the marketing activity that influenced it.

If reporting is required, compare custom booking links with Reserve with Google reporting. That choice comes after the public booking route is reliable. Measurement should never be repaired by adding patient names, service details, or health-related values to a URL.

How do you keep the link from disappearing again?

Assign one owner for the profile and one owner for the destination. Record the canonical booking URL for every location, the scheduling vendor, the domain owner, and the team responsible for firewall changes. Review access when staff or agencies change. Avoid undocumented redirects and expired campaign pages as permanent appointment destinations.

Monitor the public journey after website releases, vendor migrations, domain changes, security-rule updates, and location moves. A small recurring check should open the link from Search or Maps, confirm the location, and stop before creating a real appointment unless the clinic has an approved synthetic test process.

If Google removes the link again, compare the current evidence with the last accepted state. That makes it possible to identify a changed response, redirect, page purpose, or security rule without rebuilding the investigation from memory.

Frequently asked questions

Can the clinic use its homepage as the appointment link?

Only if it meets Google’s requirements, including a dedicated landing page for that location and the ability to complete the represented action. A generic homepage that merely describes the organization is a weak fit for an appointment link.

Can a URL shortener fix a long booking URL?

No. Google lists link shorteners among disallowed destinations for business links. Use the valid direct destination and repair the underlying route instead of hiding it behind a shortened link.

Does a 200 response guarantee that Google will approve the link?

No. A successful HTTP response addresses one technical condition. Verification, location specificity, action completion, link type, and other stated requirements still apply, and Google retains the review decision.

Can the clinic add tracking parameters to the URL?

Use only parameters approved by the clinic’s privacy and platform review, and never put patient identity, appointment details, conditions, or health-related values in them. Test that any parameterized route remains valid and completes booking.

References

• Google Business Profile Help, “Business links policies and guidelines,” retrieved 2026-08-16, https://support.google.com/business/answer/13769188?hl=en

A Zocdoc timeslot update is a full replacement for one provider and date. The documented PUT /v1/providers/{provider_id}/calendar/timeslots operation does not append the submitted slots to existing availability. Each request must contain every open timeslot that should remain published for that provider-day.

Any existing slot omitted from a later request is removed from that date. An empty timeslots array removes all slots for the provider-day. Build one complete, validated snapshot before sending the request. Use a valid IANA time-zone identifier for every slot, respect the documented 1,500-item limit, and retry HTTP 429 responses with exponential backoff.

What does the Zocdoc timeslot PUT replace?

The Create Timeslots guide says the endpoint sets all slots for a given provider and date, replacing any existing slots. The provider_id is in the path and the date is supplied as the date query parameter. Together they define the availability slice replaced by that request.

This contract is different from an event stream or an append operation. Sending one newly opened 2:00 PM slot does not mean “add 2:00 PM.” It means “the complete open set for this provider and date is the array in this request.” If 9:00 AM existed before and is absent now, the new snapshot no longer contains it.

Keep this availability operation separate from appointment-type translation. The guide to mapping Zocdoc visit reasons to EHR appointment types covers destination codes and durations. It does not change the provider-day replacement boundary.

Why must the request contain the complete provider day?

Zocdoc explicitly instructs developers to include all open timeslots in the array for each date and request. Subsequent requests for one date override the previous data. The safe unit of publication is therefore the complete current provider-day, built from the scheduling source that owns availability.

Start with a consistent source snapshot. Select one provider and local date, apply the clinic’s approved availability rules, remove occupied or blocked times, and then serialize every slot that should remain open. Do not create independent requests from separate departments or appointment categories unless one process merges them before the PUT.

A single writer is operational guidance, not a Zocdoc requirement stated in these sources. It follows from replacement semantics: two writers can each submit a valid but incomplete view and the later one will replace the earlier result. If multiple systems contribute availability, combine their approved output before publishing.

What happens to omitted slots and empty arrays?

An omitted existing slot disappears when the new full-day array replaces the old one. An empty timeslots array removes every slot for that provider and date. Those behaviors are useful when availability closes, but dangerous when a partial calculation is mistaken for a patch.

Treat an empty result as a deliberate state. Require the upstream schedule calculation to complete successfully before it can publish zero slots. If the source read failed, the request should stop rather than convert an unknown day into a closed day. This is a recommended data-loss guard based on the documented empty-array behavior.

How should you build the replacement payload?

Build the array from a provider-day snapshot, then validate every item before the request. The documented timeslot object includes provider_id, location_id, start_time, time_zone, and patient_type. It can also include allowed and excluded visit-reason IDs.

1. Resolve the provider and target local date.
2. Read the complete current availability from its approved source.
3. Apply location, patient-type, and visit-reason eligibility.
4. Validate identifiers, local start times, and IANA zones.
5. Reject accidental empty output or an array above the documented limit.
6. Send one complete replacement request for the provider-day.

Do not let marketing attribution decide which slots exist. The distinction between appointment source and marketing source protects scheduling facts from campaign fields. Availability should come from the approved calendar logic, while attribution remains downstream context.

How do local start times and IANA zones work together?

The guide defines start_time as the local date and time within the supplied zone. It requires time_zone to be a valid IANA time-zone identifier, with America/New_York shown as an example. Seconds may be omitted from the local date-time value.

Send the actual IANA zone for the appointment location or approved scheduling context. Do not send a display abbreviation such as EST, and do not attach a browser’s current zone without confirming that it is the scheduling zone. The source requires a valid IANA identifier; the clinic still owns the rule that selects the correct one.

Test dates around local clock changes when a zone observes them. The mapped documentation does not specify a daylight-saving test procedure, so this is an integration acceptance recommendation. Confirm that the local time intended by the clinic appears on the expected provider date after serialization.

How should the 1,500-timeslot limit be handled?

Zocdoc documents the timeslots array as containing from zero through 1,500 items. Validate the final array length before sending it. A count above 1,500 is not a reason to send the day in independent partial PUT requests because each later request would replace the earlier one.

If one provider-day calculation exceeds the limit, stop publication for that slice and review the slot-generation rules. Check for duplicates, unexpectedly small increments, repeated locations, or an expanded input window. Do not truncate the array silently. Truncation would publish an incomplete day while presenting the request as successful.

The source set does not document a chunking method that preserves more than 1,500 slots for one provider-date. Escalate that requirement to Zocdoc rather than inventing one. Record the provider, date, generated count, and rule version without patient information.

How should HTTP 429 responses be retried?

Zocdoc’s Performance guide says rate-limited requests fail with HTTP status 429 and developers should use exponential backoff. Pause according to a bounded backoff policy, then retry the validated full-day request. Do not react to a rate limit by splitting the provider-day into partial replacement calls.

Keep the payload associated with the attempt. If the scheduling source changes before the retry, choose one clear policy: retry the same validated snapshot or rebuild a new complete snapshot and treat it as a new publication. Never merge fragments from two calculation times. The exact policy is local implementation guidance, not a vendor guarantee.

Track provider, date, attempt number, response status, payload count, and a non-sensitive snapshot identifier. Avoid logging patient details. When a retry eventually succeeds, the log should show which complete snapshot was published and which earlier attempt received the 429.

What tests prove replacement behavior safely?

Use Zocdoc’s sandbox environment and tokens that match that environment, as described in the API FAQ. Start with a provider-day containing three synthetic slots. Send a second array with two of them and confirm the omitted slot no longer appears. Then restore the three-slot set before testing an empty array.

Cover failure cases without touching live availability:

• A partial array must be recognized as a complete replacement.
• An empty array must require an intentional closed-day state.
• An invalid or missing IANA zone must fail local validation.
• An array above 1,500 items must stop before the request.
• A simulated 429 must trigger backoff and a full-payload retry.

After appointment actions, keep historical reporting separate from current availability. The guide on preserving original booking source after rescheduling explains why a changed appointment should not rewrite acquisition history.

How do you monitor a full-day publication?

Measure the replacement unit, not individual additions. For each attempt, record the provider, date, expected slot count, payload count, source-snapshot identifier, response status, and completion time. Alert when the expected count changes sharply, the payload becomes unexpectedly empty, validation rejects a zone, or retries exhaust their limit.

A response alone does not prove the input represented the clinic’s intended schedule. Reconcile a sample of provider-days against the scheduling source after changes to slot generation, location rules, patient types, or visit-reason restrictions. Keep that reconciliation free of patient records because the timeslot payload describes open availability.

If the practice is evaluating another scheduling product, do not reduce the comparison to endpoint names. The article on Zocdoc alternatives for practices with existing demand separates marketplace acquisition from owned scheduling. Replacement behavior is one integration acceptance criterion within that broader decision.

Frequently Asked Questions

Can I send only the slot that changed?

No. The PUT replaces all slots for the provider and date. Include every open slot that should remain after the update.

What does an empty timeslots array do?

It removes all slots for the specified provider-day. Treat empty output as an intentional closed-day instruction, not a fallback after a failed source read.

Can I split more than 1,500 slots into several PUT requests?

The mapped documentation does not define chunking for one provider-date. Later requests override earlier data, so partial PUTs would not safely combine. Stop and confirm the requirement with Zocdoc.

What should happen after a 429 response?

Use exponential backoff, then retry a complete validated provider-day payload. Do not convert the retry into smaller replacement fragments.

References

• Zocdoc for Developers, Create Timeslots
• Zocdoc for Developers, Frequently Asked Questions
• Zocdoc for Developers, Performance