> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecobalt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
```bash theme={null}
curl -X GET https://api.usecobalt.com/v1/availability \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-G \
--data-urlencode "start_date=2024-03-14T00:00:00-07:00" \
--data-urlencode "end_date=2024-04-14T23:59:59-07:00" \
--data-urlencode "buffer=30" \
--data-urlencode "visit_type=np" \
--data-urlencode "calculation_method=slots" \
--data-urlencode "provider_ids=3498234,9834521" \
--data-urlencode "location_ids=1"
```
### Example Response
```json theme={null}
{
"success": true,
"results": {
"availability": [
{
"day_of_week": 5,
"date": "2024-04-05",
"duration_string": "9h",
"range_start": "2024-04-05T08:00:00.000-07:00",
"range_end": "2024-04-05T17:00:00.000-07:00",
"provider_id": "3498234",
"facility_id": "1", // if available in the EHR
"facility_name": "Main St Clinic", // if available in the EHR
"visit_type": "New Patient" // only present when calculation_method=slots
}
]
},
"timezone": "America/Los_Angeles"
}
```
### 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:
```json theme={null}
{
"success": true,
"availability": [
{
"day_of_week": 2,
"date": "2025-01-14",
"duration_string": "30 minutes",
"range_start": "2025-01-14T09:00:00.000-08:00",
"range_end": "2025-01-14T09:30:00.000-08:00",
"provider_id": "12345",
"visit_type": "New Patient Visit",
"available_appointments": 3,
"max_visits": 5,
"facility_id": "LOC-001",
"facility_name": "Main Office"
},
{
"day_of_week": 2,
"date": "2025-01-14",
"duration_string": "15 minutes",
"range_start": "2025-01-14T10:00:00.000-08:00",
"range_end": "2025-01-14T10:15:00.000-08:00",
"provider_id": "12345",
"visit_type": "Follow-up",
"available_appointments": 1,
"max_visits": 1,
"facility_id": "LOC-001",
"facility_name": "Main Office"
}
],
"timezone": "America/Los_Angeles"
}
```
**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.
## OpenAPI
````yaml GET /availability
openapi: 3.0.0
info:
title: Cobalt API
version: 1.0.1
description: API for interacting with Cobalt's EHR integration services
servers:
- url: https://api.usecobalt.com/v1
security:
- ClientCredentials: []
ClientSecret: []
AccessToken: []
paths:
/availability:
get:
summary: Get Availability
parameters:
- in: query
name: start_date
required: true
schema:
type: string
description: The start of the date range (YYYY-MM-DD)
- in: query
name: end_date
required: true
schema:
type: string
description: The end of the date range (YYYY-MM-DD)
- in: query
name: provider_type
schema:
type: string
enum:
- primary
- secondary
default: primary
description: >-
Whether to check availability for the primary provider (default) or
secondary provider
- in: query
name: provider_ids
schema:
type: string
example: prov1,prov2
description: >-
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.
- in: query
name: location_ids
schema:
type: string
example: loc1,loc2
description: >-
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.
- in: query
name: fallback_to_default_hours
schema:
type: string
enum:
- 'true'
- 'false'
default: 'false'
description: >-
Whether to fallback to the default hours if no availability rules
are defined for the provider
- in: query
name: calculation_method
schema:
type: string
enum:
- gaps
- slots
- equal_slots
default: gaps
description: >-
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.
- in: query
name: buffer
schema:
type: integer
minimum: 0
maximum: 60
exclusiveMaximum: true
description: >-
Specifies a buffer time in minutes to add after appointments of a
specific visit_type or all visit types. This effectively makes the
provider unavailable for this duration after such an appointment.
Must be a non-negative integer less than 60.
- in: query
name: visit_type
schema:
type: string
description: >-
Used in conjunction with buffer. Specifies the type of visit after
which the buffer should be applied. Can also be 'all' to apply the
buffer after all appointments. If buffer is set and visit_type is
omitted, it defaults to 'all'. Must be 'all' or a valid visit type
code configured for the user/organization (case-insensitive).
- in: query
name: daily_appointment_limit
schema:
type: integer
minimum: 1
description: >-
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.
- in: query
name: daily_limit_type
schema:
type: string
description: >-
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.
- in: query
name: max_slot_duration
schema:
type: integer
minimum: 5
maximum: 60
multipleOf: 5
description: >-
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.
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
availability:
type: array
items:
type: object
properties:
day_of_week:
type: integer
date:
type: string
duration_string:
type: string
range_start:
type: string
range_end:
type: string
provider_id:
type: string
facility_id:
type: string
description: >-
Facility/location EHR ID for the availability
window, when available.
facility_name:
type: string
description: >-
Facility/location name for the availability window,
when available.
timezone:
type: string
components:
securitySchemes:
ClientCredentials:
type: apiKey
in: header
name: client_id
ClientSecret:
type: apiKey
in: header
name: client_secret
AccessToken:
type: apiKey
in: header
name: access_token
````