Skip to main content
POST
Live-fetch availability
This is an async operation that fetches up-to-date appointment data directly from the EMR and computes availability in one pass. If freshness is not critical, use GET /availability instead, which returns availability against cached appointment data.

Request Constraints

  • provider_ids: required array of EMR provider IDs. Must contain between 1 and 10 entries.
  • A single provider may span up to a 5-day window.
  • Two or more providers must share a single date (start_date must equal end_date).
All availability-calculation parameters (calculation_method, daily_appointment_limit, daily_limit_type, provider_type, fallback_to_default_hours, max_slot_duration, facility_scoped_scheduling, location_ids, cancelled_statuses, additional_cancelled_statuses) are optional and follow the same defaults and validation rules as GET /availability.

Example Request (1 provider, 5 days)

Example Request (multiple providers, single day)

Webhook Notification

When the fetch completes, we send an availability.live_fetch_completed event to your registered webhook endpoint with the computed slots inline. The slots themselves are not persisted, but as a side effect the underlying appointments returned by the EMR are written to our appointments cache — a follow-up GET /availability reflects the live state.
Each slot always includes day_of_week (1-7, ISO weekday), date (YYYY-MM-DD), duration_string, range_start, range_end, and provider_id. facility_id and facility_name are present when the source EHR scopes the shift to a specific location. visit_type, available_appointments, and max_visits appear when calculation_method is slots or equal_slots.

Failures and Partial Results

Cobalt retries transient failures automatically. Intermediate failed attempts do not send completion webhooks. A terminal or exhausted failure sends availability.live_fetch_completed with success: false, the existing error message, and reasons: [{ code, description }] when a shared code is known. An exhausted rate limit may return success: true with partial slots and an issues[] entry with code: "EHR_RATE_LIMITED". Only provider/days whose appointments were successfully fetched contribute slots; an unread day is unknown, not available. Partial results update returned appointments without deleting cached appointments absent from the incomplete read. For EHR_RATE_LIMITED, try again later. If it happens frequently, add credential sets to the account to spread requests across more EHR sessions.

Authorizations

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

Body

application/json
start_date
string<date>
required

Range start (YYYY-MM-DD).

Example:

"2026-03-15"

end_date
string<date>
required

Range end (YYYY-MM-DD). One provider spans up to 5 days; 2–10 providers must share a single day.

Example:

"2026-03-20"

provider_ids
string[]
required

EMR provider IDs to fetch availability for (1–10).

Example:
buffer

Minutes of buffer between slots (0–59).

Example:

15

visit_type
string

Visit-type code to size slots for. Requires buffer to be set.

Example:

"FOLLOW-UP"

calculation_method
string

Slot calculation method: gaps, slots, or equal_slots.

Example:

"gaps"

daily_appointment_limit

Max appointments per day (positive integer). Requires daily_limit_type.

Example:

8

daily_limit_type
string

Visit-type code the daily limit applies to. Requires daily_appointment_limit.

Example:

"all"

provider_type
string

Which provider slot to match on: primary or secondary.

Example:

"primary"

fallback_to_default_hours

Use default business hours when a provider has no configured hours.

Example:

false

max_slot_duration

Cap on slot length in minutes (5–60, multiples of 5).

Example:

30

facility_scoped_scheduling

Scope slots per facility rather than per provider.

Example:

true

location_ids
string[]

Filter returned slots to these EMR location IDs.

Example:
cancelled_statuses
string[]

Appointment statuses to treat as cancelled, freeing the slot. When provided, this overrides the default cancelled/rescheduled detection. The default detection treats "c", "cancelled", "canc", "rescheduled", "r/s" and "deleted" as cancelled (PTPracticePro uses "3" in place of "c"); for eClinicalWorks it also treats any status containing "canc", "r/s" or "resched" as cancelled. Statuses are matched case-insensitively. To keep the default detection and add your own statuses, use additional_cancelled_statuses instead.

Example:
additional_cancelled_statuses
string[]

Appointment statuses to treat as cancelled in addition to the default cancelled/rescheduled detection (or to cancelled_statuses, when provided); statuses are matched case-insensitively. Use this to add custom status codes without losing the defaults.

Example:
callback_urls
string[]

URLs to receive the results webhook, in addition to the account webhook.

Example:

Response

Live-fetch request accepted; results delivered by webhook

success
boolean
required
Example:

true

message
string
required
Example:

"Live-fetch request accepted"

job_id
integer
required
Example:

12345