Why a Zocdoc Timeslot Update Must Send the Complete Provider Day

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.

Request body	Resulting provider-day
All current open slots	Exactly those slots remain published
Only one newly opened slot	That slot replaces the earlier set
Earlier set minus one closed slot	The omitted slot is removed and the rest remain
Empty timeslots array	All slots for the date are removed

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