Intake Appointment Automation — Integration Document

​

Overview

​

Integration Matrix

​

Event Contracts

​

Consumed Events

​

ce_screening_completed (from CE-28 via FW-16)

Canonical schema: See CE-28 Integration and EVENT_CONTRACTS.md for the authoritative payload definition.

{
  event_id: uuid;
  source: 'ce-28';
  timestamp: string; // ISO 8601
  correlation_id: uuid;
  organization_id: uuid;
  data: {
    screening_id: uuid;
    lead_id: uuid;
    disposition: 'proceed' | 'waitlist' | 'refer_out' | 'decline';
    clinical_flags: string[];
    asam_score: number | null;
    recommended_level_of_care: string | null;
    needs_clinical_escalation: boolean;
    screener_id: uuid;
    screening_date: string; // ISO 8601
    program_type: 'residential' | 'iop' | 'php' | 'outpatient';
    sla_status: 'on_time' | 'missed';
  };
}

​

Published Events

​

pm_appointment_created

{
  "event_type": "pm_appointment_created",
  "payload": {
    "appointment_id": "uuid",
    "patient_id": "uuid",
    "provider_id": "uuid",
    "organization_id": "uuid",
    "appointment_time": "ISO8601",
    "appointment_type": "intake_assessment",
    "screening_id": "uuid",
    "match_log_id": "uuid"
  }
}

​

pm_no_suitable_provider

{
  "event_type": "pm_no_suitable_provider",
  "payload": {
    "screening_id": "uuid",
    "patient_id": "uuid",
    "organization_id": "uuid",
    "program_type": "string",
    "reason": "no_available_provider",
    "match_log_id": "uuid"
  }
}

​

API Contracts

​

PM-05 Availability Query (consumed by PM-38)

• Returns: array of { provider_id, slot_time, slot_duration, location }

​

PM-03 Appointment Creation (consumed by PM-38)

• POST /api/scheduling/appointments with { patient_id, provider_id, slot_time, type: 'intake', modality, site_id }
• Returns: { appointment_id, status, appointment_time }

​

Coordinator Override

• PATCH /api/appointments/{id}/override — See spec API Design section.

​

Platform Layer Usage

​

Security

• All data scoped by organization_id; RLS enforced on pm_appointment_match_log
• Edge function uses service role for INSERT; SECURITY DEFINER helper for user-facing SELECT
• No PHI in event payloads beyond patient_id (resolvable by consumer with RLS)
• SMS content follows HIPAA minimum necessary standard

​

Dependencies

​

Open Questions

• PM-10 API contract finalization — Resolved: PM-05 for availability, PM-03 for appointment CRUD
• CE-28 event payload finalization (confirm modality_preference field name) — Resolved: field removed from payload; scheduling uses program_type and site preferences
• SMS consent: Confirm CE-28 captures TCPA consent for automated messaging