Skip to content
DELPHOS DELPHOS

Scheduling API Reference

Scheduling API Reference

All scheduling endpoints require an x-api-key header. All request and response bodies use application/json unless noted otherwise.

Appointments

MethodPathDescription
POST/v1/scheduling/appointmentsCreate appointment
GET/v1/scheduling/appointmentsList appointments (cursor-paginated)
GET/v1/scheduling/appointments/{id}Get appointment detail with status history
PUT/v1/scheduling/appointments/{id}Update notes, room, or metadata (requires version)
DELETE/v1/scheduling/appointments/{id}Cancel appointment (shorthand)

Appointment Lifecycle

MethodPathTransitionBody fields
POST/v1/scheduling/appointments/{id}/confirmrequested → confirmedconfirmed_by (string, optional)
POST/v1/scheduling/appointments/{id}/check-inconfirmed → checked_inchecked_in_by (string, optional)
POST/v1/scheduling/appointments/{id}/startchecked_in → in_progressnone
POST/v1/scheduling/appointments/{id}/completein_progress → completednotes (string, optional)
POST/v1/scheduling/appointments/{id}/no-showconfirmed/checked_in → no_shownotes (string, optional)
POST/v1/scheduling/appointments/{id}/cancelrequested/confirmed/checked_in → cancelledreason, cancelled_by (both optional)
POST/v1/scheduling/appointments/{id}/reschedulecreates new appointmentnew_start_time, new_end_time, new_location_id, new_room_id, reason

Fields marked * are required.

AppointmentCreate required fields

FieldType
provider_profile_idUUID
patient_idUUID
appointment_type_idUUID
location_idUUID
start_timedatetime (UTC)
end_timedatetime (UTC)

Optional: room_id, source (default "api"), notes, internal_notes, external_reference, metadata.

Status codes

CodeMeaning
201Appointment created
200Operation succeeded
204Deleted/deactivated
404Appointment not found
409Conflict (double-booking) or invalid transition
422Validation error

Slots

MethodPathDescription
GET/v1/scheduling/slotsSearch available appointment slots

Required query parameters

ParameterType
date_fromdate
date_todate (max 30 days from date_from)
appointment_type_idUUID
provider_id OR specialtyUUID or string (at least one required)

Optional: location_id, duration_minutes, limit (default 50, max 200), cursor.

AvailableSlot fields

provider_id, provider_name, specialty, location (object with id/name), date, start_time (HH:MM), end_time (HH:MM), available (bool), score (float).

Locations

MethodPathDescription
POST/v1/scheduling/locationsCreate a location
GET/v1/scheduling/locationsList locations (cursor-paginated; ?include_inactive=true, ?city= filters)
GET/v1/scheduling/locations/{id}Get a location by ID
PUT/v1/scheduling/locations/{id}Update a location (partial; set is_active: true to reactivate)
DELETE/v1/scheduling/locations/{id}Soft-delete (is_active = false; idempotent)

LocationCreate required fields

Only name (1–255 chars) is required. Optional: address, city, state (UF, 2 chars), zip_code, phone, timezone (default America/Sao_Paulo), operating_hours, metadata. See Managing Locations for the full reference.

Providers

MethodPathDescription
POST/v1/scheduling/providersCreate provider profile
GET/v1/scheduling/providersList providers
GET/v1/scheduling/providers/{id}Get provider
PUT/v1/scheduling/providers/{id}Update provider
DELETE/v1/scheduling/providers/{id}Deactivate provider (soft delete, 204)

ProviderProfileCreate required fields

FieldType
doctor_idUUID

Optional: default_appointment_duration_minutes (default 30), buffer_between_appointments_minutes (default 0), max_daily_appointments, max_concurrent_appointments (default 1), primary_location_id, specialties, is_accepting_new_patients (default true), metadata.

Schedule Templates

MethodPathDescription
GET/v1/scheduling/providers/{id}/templatesList templates
POST/v1/scheduling/providers/{id}/templatesCreate template
PUT/v1/scheduling/providers/{id}/templates/{tid}Update template
DELETE/v1/scheduling/providers/{id}/templates/{tid}Deactivate template (soft delete, 204)

Schedule Overrides

MethodPathDescription
GET/v1/scheduling/providers/{id}/overridesList overrides
POST/v1/scheduling/providers/{id}/overridesCreate override (blocked, modified, or added)
DELETE/v1/scheduling/providers/{id}/overrides/{oid}Delete override (hard delete, 204)

Conflict Detection

MethodPathDescription
GET/v1/scheduling/providers/{id}/cross-location-conflictsCheck cross-location conflicts
GET/v1/scheduling/providers/{id}/locations-scheduleFull multi-location schedule view

Webhooks

MethodPathDescription
POST/v1/scheduling/webhooksCreate subscription
GET/v1/scheduling/webhooksList subscriptions
GET/v1/scheduling/webhooks/{id}Get subscription
PUT/v1/scheduling/webhooks/{id}Update subscription
DELETE/v1/scheduling/webhooks/{id}Deactivate subscription (soft delete, 204)
POST/v1/scheduling/webhooks/{id}/testSend test event
GET/v1/scheduling/webhooks/{id}/deliveriesDelivery history
GET/v1/scheduling/webhooks/dead-lettersDead-letter queue

Conversation Engine

MethodPathDescription
POST/v1/scheduling/conversationProcess conversation message (FSM multi-turn)
GET/v1/scheduling/conversation/{patient_id}/{channel}/stateGet FSM state (debug)
DELETE/v1/scheduling/conversation/{patient_id}/{channel}Clear conversation state

Natural Language Scheduling

MethodPathDescription
POST/v1/scheduling/natural-languageProcess NL scheduling request in Brazilian Portuguese

Request: { message: string, patient_id: UUID, ... }. Returns extracted entities and resolved database references.

Voice Scheduling

MethodPathDescription
POST/v1/scheduling/voiceProcess audio file for scheduling intent

Request: multipart/form-data with audio (file) and patient_id (UUID form field). Returns VoiceSchedulingResponse or VoiceClarificationResponse.

No-Show Prediction

MethodPathDescription
GET/v1/scheduling/no-show/appointments/{appointment_id}/riskSingle appointment risk score
GET/v1/scheduling/no-show/daily-risksBatch risk scores for a date (query: date)
GET/v1/scheduling/no-show/model-infoPrediction model metadata

NoShowRiskResponse fields

risk_score (float, 0–1), risk_level (low/medium/high), risk_factors (array), recommendation (string).

Waitlist

MethodPathDescription
POST/v1/scheduling/waitlistAdd patient to waitlist
GET/v1/scheduling/waitlistList waitlist entries
DELETE/v1/scheduling/waitlist/{id}Remove from waitlist (204)
GET/v1/scheduling/waitlist/position/{id}Get queue position

Common Error Responses

All scheduling endpoints use a consistent error format:

{
  "detail": "Human-readable error message"
}
HTTP CodeWhen it occurs
401Missing or invalid API key
403Insufficient permissions for this tenant
404Resource not found
409Conflict (double-booking, duplicate, or invalid status transition)
422Request body or query parameter validation failure
500Internal server error