Calendar Management

Calendar Management

DELPHOS calendar management covers three areas: searching available appointment slots, managing provider profiles with their scheduling configuration, and defining recurring schedule templates or one-off overrides.

---

Slot Search

Search for available appointment slots across one or more providers.

GET /v1/scheduling/slots

Query parameters

Parameter	Type	Required	Description
date_from	date	Yes	Start of search range (today or future)
date_to	date	Yes	End of search range (max 30 days from date_from)
appointment_type_id	UUID	Yes	Type of appointment being booked
provider_id	UUID	No*	Filter by specific provider profile
specialty	string	No*	Cross-provider search by specialty name (max 200 chars)
location_id	UUID	No	Filter by location
duration_minutes	integer	No	Override the default appointment duration
limit	integer	No	Max slots to return (1-200, default 50)
cursor	string	No	Pagination cursor from previous response

Note

At least one of provider_id or specialty must be provided. Providing provider_id targets a single provider (target latency under 50ms). Providing specialty searches across all providers offering that specialty (target latency under 200ms).

curl

curl "https://your-instance.delphos.app/v1/scheduling/slots?date_from=2026-05-15&date_to=2026-05-22&appointment_type_id=660e8400-e29b-41d4-a716-446655440001&provider_id=550e8400-e29b-41d4-a716-446655440000&limit=20" \
  -H "x-api-key: YOUR_API_KEY"

Python

import httpx

response = httpx.get(
    "https://your-instance.delphos.app/v1/scheduling/slots",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "date_from": "2026-05-15",
        "date_to": "2026-05-22",
        "appointment_type_id": "660e8400-e29b-41d4-a716-446655440001",
        "provider_id": "550e8400-e29b-41d4-a716-446655440000",
        "limit": 20,
    },
)
data = response.json()
for slot in data["slots"]:
    print(slot["date"], slot["start_time"], "-", slot["end_time"])

Response fields (SlotSearchResponse)

Field	Type	Description
slots	array	List of AvailableSlot objects
total	integer	Number of slots in this page
search_ms	integer	Server-side search duration in milliseconds
next_cursor	string or null	Cursor for the next page; null if no more results

AvailableSlot fields

Field	Type	Description
provider_id	UUID	Provider profile UUID
provider_name	string	Provider display name
specialty	string	Specialty for this slot
location	object	Location with id and name keys
date	date	Slot date
start_time	string	Start time formatted as HH:MM
end_time	string	End time formatted as HH:MM
available	boolean	Whether the slot is currently bookable
score	float	Relevance score (always 1.0 in current version)

---

Provider Profiles

Provider profiles link a doctor record to scheduling configuration. Each doctor can have one profile per tenant.

Create a provider profile

POST /v1/scheduling/providers

Field	Type	Required	Default	Description
doctor_id	UUID	Yes	—	UUID of the existing doctor record
default_appointment_duration_minutes	integer	No	30	Default appointment duration
buffer_between_appointments_minutes	integer	No	0	Buffer time between appointments
max_daily_appointments	integer	No	null	Max appointments per day (null = unlimited)
max_concurrent_appointments	integer	No	1	Max overlapping appointments
primary_location_id	UUID	No	null	Primary location UUID
specialties	array of strings	No	[]	Scheduling-relevant specialties
is_accepting_new_patients	boolean	No	true	Whether accepting new patient bookings
metadata	object	No	{}	Additional metadata

Returns 201. Returns 409 if a profile already exists for this doctor.

List provider profiles

GET /v1/scheduling/providers

Optional filters: specialty, is_active, is_accepting_new_patients. Uses cursor-based pagination with limit (1-100, default 20) and cursor.

Get a provider profile

GET /v1/scheduling/providers/{provider_id}

Update a provider profile

PUT /v1/scheduling/providers/{provider_id}

All fields are optional. Only provided fields are updated.

Deactivate a provider profile

DELETE /v1/scheduling/providers/{provider_id}

Soft-delete — sets is_active = false. Returns 204. Does not remove associated templates or overrides.

---

Schedule Templates

Templates define recurring weekly availability patterns. Each template belongs to a provider and location combination, has a date range, and contains a list of time slots.

List templates

GET /v1/scheduling/providers/{provider_id}/templates

Returns all active templates with their slots.

Create a template

POST /v1/scheduling/providers/{provider_id}/templates

curl

curl -X POST "https://your-instance.delphos.app/v1/scheduling/providers/PROVIDER_ID/templates" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Consultas Regulares",
    "location_id": "550e8400-e29b-41d4-a716-446655440004",
    "effective_from": "2026-05-01",
    "effective_until": "2026-12-31",
    "slots": [
      {"day_of_week": 1, "start_time": "08:00", "end_time": "12:00", "slot_type": "available"},
      {"day_of_week": 3, "start_time": "08:00", "end_time": "12:00", "slot_type": "available"},
      {"day_of_week": 5, "start_time": "08:00", "end_time": "12:00", "slot_type": "available"}
    ]
  }'

Python

import httpx

response = httpx.post(
    f"https://your-instance.delphos.app/v1/scheduling/providers/{provider_id}/templates",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "name": "Consultas Regulares",
        "location_id": "550e8400-e29b-41d4-a716-446655440004",
        "effective_from": "2026-05-01",
        "effective_until": "2026-12-31",
        "slots": [
            {"day_of_week": 1, "start_time": "08:00", "end_time": "12:00", "slot_type": "available"},
            {"day_of_week": 3, "start_time": "08:00", "end_time": "12:00", "slot_type": "available"},
            {"day_of_week": 5, "start_time": "08:00", "end_time": "12:00", "slot_type": "available"},
        ],
    },
)
template = response.json()

Returns 201. Returns 409 if the slots conflict with an existing template at another location for the same provider.

Update a template

PUT /v1/scheduling/providers/{provider_id}/templates/{template_id}

Deactivate a template

DELETE /v1/scheduling/providers/{provider_id}/templates/{template_id}

Soft-delete — returns 204.

---

Schedule Overrides

Overrides take precedence over recurring templates for a specific date. Use them for holidays, vacation days, or extra working days.

List overrides

GET /v1/scheduling/providers/{provider_id}/overrides

Create an override

POST /v1/scheduling/providers/{provider_id}/overrides

Field	Type	Required	Description
override_date	date	Yes	The specific date to override
override_type	string	Yes	"blocked", "modified", or "added"
(additional fields vary by type)

Override types:

Type	Description
blocked	Provider unavailable (holiday, vacation, sick leave)
modified	Different hours than the regular template for this date
added	Extra working day not in the regular template

Returns 201. Returns 409 if an override already exists for this date.

Delete an override

DELETE /v1/scheduling/providers/{provider_id}/overrides/{override_id}

Hard-delete — permanently removes the override. Returns 204.

---

Cross-Location Conflict Detection

Check whether a provider’s schedule templates overlap across multiple locations.

GET /v1/scheduling/providers/{provider_id}/cross-location-conflicts

Optional query parameters: date_from, date_to to filter by effective date range.

Returns CrossLocationConflictsListResponse listing any time windows where the provider is scheduled at more than one location simultaneously.

View full multi-location schedule

GET /v1/scheduling/providers/{provider_id}/locations-schedule

Returns the complete schedule view across all locations for the provider.