Skip to main content
GET
Get Availability
Provider Filtering: Only providers with active=true AND hide_in_availability=false will appear in availability results. If you’ve set a provider’s hide_in_availability to true, they won’t appear here even if their status is active.
Use provider_ids and location_ids to narrow returned availability. Both parameters accept comma-separated EHR IDs, for example provider_ids=prov1,prov2 and location_ids=loc1,loc2. Location filtering is applied to generated availability windows using each slot’s facility_id; slots without a facility_id are excluded when location_ids is provided.

Example Request

Example Response

Enhanced Response with Detailed Slot Information

When using calculation_method=slots, if the EHR provides detailed slot information, the response may include additional fields for capacity management:
Key fields when detailed slot information is available:
  • visit_type: The specific appointment type that can be booked in this slot
  • available_appointments: How many more appointments can still be scheduled in this slot
  • max_visits: The total capacity of this slot (useful for understanding how many are already booked)
  • facility_id: Unique identifier for the facility/location
  • facility_name: Name of the facility/location
The availability of these enhanced fields depends on your EHR system’s capabilities. Not all EHRs provide this level of detail for slot-based availability.

Calculation Methods

The calculation_method parameter determines how availability is calculated:
  • gaps (Default): Calculates availability based on free time between a provider’s working hours and existing appointments
  • slots: Pre-defined appointment slots blocked only by appointments matching the slot’s visit type
  • equal_slots: Pre-defined appointment slots blocked by ANY appointment at that time, regardless of type

Example Scenarios

Scenario 1: A “New Patient” schedule_slot exists at 10:00 AM. A “Follow-up” appointment is already booked at 10:00 AM.
  • gaps: 10:00 AM not returned as available (appointment occupies that time)
  • slots: “New Patient” slot returned as available (different appointment type doesn’t block)
  • equal_slots: “New Patient” slot not returned (any appointment blocks all slot types)
Scenario 2: A “New Patient” schedule_slot exists at 10:00 AM. A “New Patient” appointment is already booked at 10:00 AM.
  • gaps: 10:00 AM not returned as available (appointment occupies that time)
  • slots: “New Patient” slot not returned (same appointment type blocks)
  • equal_slots: “New Patient” slot not returned (any appointment blocks all slot types)
Scenario 3: A “New Patient” schedule_slot exists at 10:00 AM. A schedule_block (e.g., “Lunch”) exists at 10:00 AM.
  • gaps: 10:00 AM not returned as available (schedule_block occupies that time)
  • slots: “New Patient” slot not returned (schedule_blocks block slots)
  • equal_slots: “New Patient” slot not returned (schedule_blocks block all slot types)
Use equal_slots when multiple parties (e.g., clinic staff and automated systems) are scheduling different appointment types into the same time slots and you need to prevent double-booking.

Authorizations

client_id
string
header
required
client_secret
string
header
required
access_token
string
header
required

Query Parameters

start_date
string
required

The start of the date range (YYYY-MM-DD)

end_date
string
required

The end of the date range (YYYY-MM-DD)

provider_type
enum<string>
default:primary

Whether to check availability for the primary provider (default) or secondary provider

Available options:
primary,
secondary
provider_ids
string

Comma-separated list of provider EHR IDs to include in availability results. Providers are still limited to active providers that are not hidden from availability.

Example:

"prov1,prov2"

location_ids
string

Comma-separated list of location EHR IDs to include in availability results. This filters generated availability windows by slot facility_id; slots without a facility_id are excluded when location_ids is provided.

Example:

"loc1,loc2"

fallback_to_default_hours
enum<string>
default:false

Whether to fallback to the default hours if no availability rules are defined for the provider

Available options:
true,
false
calculation_method
enum<string>
default:gaps

Specifies the method for determining availability. "gaps" (Default): Calculates availability based on free time between working hours and appointments. "slots": Pre-defined appointment slots blocked only by appointments matching the slot's type. "equal_slots": Pre-defined appointment slots blocked by ANY appointment at that time, regardless of type.

Available options:
gaps,
slots,
equal_slots
daily_appointment_limit
integer

If provided along with daily_limit_type, specifies the maximum number of appointments of that type a provider can have on a single day. If the limit is reached, no further availability will be shown for that day for that appointment type. Must be a positive integer. Requires daily_limit_type to also be provided.

Required range: x >= 1
daily_limit_type
string

Specifies the appointment type to which the daily_appointment_limit applies. Must be a valid visit type code configured for the user/organization (case-insensitive). Requires daily_appointment_limit to also be provided.

max_slot_duration
integer

If provided and calculation_method is 'gaps', this parameter instructs the system to subdivide large availability blocks into smaller, contiguous slots of this specified duration in minutes. Must be an integer between 5 and 60 (inclusive) and must be an increment of 5 (e.g., 5, 10, 15, ..., 60). When an available block of time is not an exact multiple of the max_slot_duration, the system will create as many full slots of the specified duration as possible. Any remaining portion of the block that is smaller than the max_slot_duration will not be returned as an available slot. For example, if there is a 45-minute availability block and max_slot_duration is set to 30 minutes, one 30-minute slot will be returned, and the remaining 15 minutes will not form an additional slot.

Required range: 5 <= x <= 60Must be a multiple of 5

Response

200 - application/json

Successful response

success
boolean
availability
object[]
timezone
string