Skip to main content

​
Availability Cache

Junction maintains a fast Availability Cache containing the next 21 days of availability for all locations. Each location is refreshed every 5 minutes on average. When you set the allow_stale parameter on the PSC Appointment Availability endpoint, your request is fulfilled directly from the Availability Cache, provided that:
  1. All requested locations have a cache hit; and
  2. The cached information is reasonably fresh (less than 15 minutes old).
When a request cannot be fulfilled by the Availability Cache, it is routed directly to the PSC Appointment Provider.

​
When to use

Use allow_stale when you need fast response times and can tolerate slightly stale availability data—for example, when displaying initial availability options to a user before they select a specific slot.

​
Idempotency Key

Consider specifying an Idempotency Key (X-Idempotency-Key header) when submitting a booking request to the Book PSC Appointment endpoint. Requests with the same idempotency key within a 14-day retention window will return the original request’s response. Note that the response is frozen at the time it is first emitted. For example, if a pending appointment later transitions to confirmed via Async Confirmation, requests with that idempotency key will still return the appointment in its original pending status.

​
When to use

When a booking request fails on your side (API consumer side), it could be a transient connection issue or a Junction request queueing issue. Your request might have still reached the Junction API server and might have been processed. Using an Idempotency Key allows your system to safely retry booking requests, without the risk of double booking appointments.

​
Async Confirmation

When calling the Book PSC Appointment endpoint, Junction by default returns a 500 Internal Server Error if the PSC Appointment Provider fails to acknowledge the booking request. With Async Confirmation enabled, Junction waits synchronously for the provider to acknowledge the booking request, up to sync_confirmation_timeout_millisecond (default: 2.5s, range: 1–10s).
  • If an acknowledgment is received before the timeout, Junction creates a reserved or confirmed appointment immediately and returns it in the response.
  • If no acknowledgment is received before the timeout, Junction creates a placeholder pending appointment and returns it in the response.

​
Background retries

If a pending appointment is created, Junction continues to retry the booking request with the PSC Appointment Provider in the background, up to async_confirmation_timeout_millisecond (default: 15min, range: 1min–48hr).
  • If an acknowledgment is received before the timeout, the appointment transitions to reserved or confirmed status.
  • If the provider still fails to acknowledge after the timeout, the pending appointment transitions to cancelled status.

​
Webhooks

You will receive the labtest.appointment.updated event for the initial appointment creation, as well as for all state transitions described above.

​
When to use

Use Async Confirmation when you want to provide a consistently responsive booking experience. When the PSC Appointment Provider is under stress, Async Confirmation allows you to show a pending appointment to the end patient, and manages all the logistics of retrying the booking requests with the provider.