> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Intake Appointment Automation — Integration Document

> Version: 1.0 Last Updated: 2026-03-27 Spec: specs/pm/specs/PM-38-intake-appointment-automation-provider-matching.md Status: ✅ Complete

**Version:** 1.0\
**Last Updated:** 2026-03-27\
**Spec:** `specs/pm/specs/PM-38-intake-appointment-automation-provider-matching.md`\
**Status:** ✅ Complete

***

## Overview

PM-38 auto-schedules intake appointments after CE-28 screening approval. This document maps cross-core integration points, event contracts, API contracts, and platform layer usage.

***

## Integration Matrix

| From  | To          | Pattern             | Event/API                                               | Status     |
| ----- | ----------- | ------------------- | ------------------------------------------------------- | ---------- |
| CE-28 | PM-38       | Event (FW-16)       | `ce_screening_completed` (disposition=proceed)          | 📝 Planned |
| CE-29 | PM-38       | Data (prerequisite) | `pm_patients` record exists before scheduling           | 📝 Planned |
| PM-38 | PM-05/PM-03 | API (internal)      | PM-05: query available slots; PM-03: create appointment | ✅ Complete |
| PM-38 | PM-39       | Event (FW-16)       | `pm_no_suitable_provider` → waitlist entry              | 📝 Planned |
| PM-38 | PM-40       | Event (FW-16)       | `pm_appointment_created` → pre-admission packet         | 📝 Planned |
| PM-38 | PM-41       | Data                | Match log analytics consumed by PM-41 dashboards        | 📝 Planned |
| PM-38 | PM-42       | Data                | Coordinator task queue pulls appointment status         | 📝 Planned |
| PM-38 | PM-02       | Data (optional)     | Insurance acceptance data for matching                  | 📝 Planned |
| PM-38 | RH-01       | Data (optional)     | Multi-pathway bed/program check                         | 📝 Planned |

***

## Event Contracts

### Consumed Events

#### `ce_screening_completed` (from CE-28 via FW-16)

> **Canonical schema:** See [CE-28 Integration](./intake-screening-integration.md) and [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md#ce_screening_completed) for the authoritative payload definition.

```typescript theme={null}
{
  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';
  };
}
```

**Filter:** PM-38 only acts when `disposition = "proceed"`.

### Published Events

#### `pm_appointment_created`

```json theme={null}
{
  "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"
  }
}
```

**Consumers:** PM-40 (pre-admission packet), PM-41 (analytics), CL-40 (clinical intake trigger).

#### `pm_no_suitable_provider`

```json theme={null}
{
  "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"
  }
}
```

**Consumer:** PM-39 (waitlist management).

***

## API Contracts

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

PM-05 provides provider schedule and availability data. PM-38 queries available slots filtered by specialty, site, insurance, and configurable availability window (`intake_match_availability_days`).

* Returns: array of `{ provider_id, slot_time, slot_duration, location }`

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

PM-03 provides appointment CRUD. PM-38 creates intake appointments after matching.

* `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

| Layer                 | Usage                                                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| FW-16 (Event)         | Subscribe to `ce_screening_completed`; publish `pm_appointment_created` and `pm_no_suitable_provider`                                |
| PF-05 (Org Context)   | Organization ID for tenant scoping                                                                                                   |
| PF-30 (Permissions)   | `pm.intake_match.view`, `pm.intake_match.override`, `pm.intake_match.configure`, `pm.appointments.create`, `pm.appointments.confirm` |
| PF-10 (Notifications) | Coordinator notifications on appointment creation, no-match, and override alerts                                                     |

***

## 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

| Dependency                                        | Required By | Status      | Notes                                              |
| ------------------------------------------------- | ----------- | ----------- | -------------------------------------------------- |
| PM-05/PM-03 API (slot query + appointment create) | Phase 1-2   | ✅ Complete  | PM-05 for availability; PM-03 for appointment CRUD |
| CE-28 event contract (`ce_screening_completed`)   | Phase 2     | 📝 Planned  | Payload schema above                               |
| CE-29 patient creation                            | Phase 2     | 📝 Planned  | Patient must exist in pm\_patients                 |
| PM-39 waitlist subscription                       | Phase 4     | 📝 Planned  | Consumes `pm_no_suitable_provider`                 |
| PM-02 insurance data (optional)                   | Phase 1     | Degraded-ok | Default to all-insurance if unavailable            |

***

## 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