Skip to main content
POST
/
availability
/
fetch
Fetch Availability
curl --request POST \
  --url https://api.usecobalt.com/v1/availability/fetch \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "start_date": "2023-12-25",
  "end_date": "2023-12-25",
  "provider_ids": [
    "<string>"
  ],
  "buffer": 30,
  "visit_type": "<string>",
  "calculation_method": "gaps",
  "daily_appointment_limit": 2,
  "daily_limit_type": "<string>",
  "fallback_to_default_hours": true,
  "max_slot_duration": 32,
  "facility_scoped_scheduling": true,
  "location_ids": [
    "<string>"
  ]
}
'
{
  "success": true,
  "message": "<string>",
  "job_id": "<string>"
}
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 (buffer, visit_type, calculation_method, daily_appointment_limit, daily_limit_type, provider_type, fallback_to_default_hours, max_slot_duration, facility_scoped_scheduling, location_ids) are optional and follow the same defaults and validation rules as GET /availability.

​
Example Request (1 provider, 5 days)

{
    "start_date": "2026-07-01",
    "end_date": "2026-07-05",
    "provider_ids": ["prov_789"],
    "buffer": 5,
    "visit_type": "NP",
    "calculation_method": "gaps"
}

​
Example Request (multiple providers, single day)

{
    "start_date": "2026-07-01",
    "end_date": "2026-07-01",
    "provider_ids": ["prov_789", "prov_790", "prov_791"]
}

​
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. 
{
    "id": "evt_1J9X2q2eZvKYlo2Cmnopqr",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cstuv",
    "job_id": "job_1J9X2q2eZvKYlo2Cmnopqr",
    "timestamp": "2026-07-01T11:00:00Z",
    "type": "availability.live_fetch_completed",
    "action": "sync",
    "data": {
        "success": true,
        "provider_ids": ["prov_789"],
        "start_date": "2026-07-01",
        "end_date": "2026-07-05",
        "slot_count": 24,
        "slots": [
            {
                "day_of_week": 3,
                "date": "2026-07-01",
                "duration_string": "30 minutes",
                "range_start": "2026-07-01T09:00:00-07:00",
                "range_end": "2026-07-01T09:30:00-07:00",
                "provider_id": "prov_789",
                "facility_id": "loc_1",
                "facility_name": "Main Office"
            }
        ]
    }
}
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.

Authorizations

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

Body

application/json
​
start_date
string<date>
required

Start date for the availability window in ISO 8601 format (YYYY-MM-DD).

​
end_date
string<date>
required

End date for the availability window in ISO 8601 format (YYYY-MM-DD). When 1 provider is supplied, end_date may be up to 5 days after start_date. When 2-10 providers are supplied, end_date must equal start_date.

​
provider_ids
string[]
required

EMR provider IDs to compute availability for (1-10).

Required array length: 1 - 10 elements
​
buffer
integer

Buffer in minutes to add after appointments of visit_type. Same semantics as GET /availability.

Required range: 0 <= x < 60
​
visit_type
string

Used with buffer. Same semantics as GET /availability.

​
calculation_method
enum<string>
default:gaps

Availability calculation strategy. Same semantics as GET /availability.

Available options:
gaps,
slots,
equal_slots
​
daily_appointment_limit
integer

Same semantics as GET /availability. Requires daily_limit_type.

Required range: x >= 1
​
daily_limit_type
string

Same semantics as GET /availability. Requires daily_appointment_limit.

​
provider_type
enum<string>
Available options:
primary,
secondary
​
fallback_to_default_hours
boolean

Same semantics as GET /availability.

​
max_slot_duration
integer

Same semantics as GET /availability.

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

Same semantics as GET /availability.

​
location_ids
string[]

EHR location IDs to filter slots by facility_id.

Response

Request accepted for processing. Results are delivered via webhook.

​
success
boolean
​
message
string
​
job_id
string