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

# Event & API Reference

> Payload (IDs only — no PHI): ``typescript { lead_id: string; // UUID contact_id: string; // UUID organization_id: string; // UUID correlation_id: string; // Fo…

**Spec:** `specs/ce/specs/CE-29-lead-to-patient-conversion-pipeline.md`\
**Status:** ✅ Complete\
**Last Updated:** 2026-03-28

***

## Events

### `ce_lead_converted_to_patient`

| Field           | Value                                                                   |
| --------------- | ----------------------------------------------------------------------- |
| **Publisher**   | CE (`useLeadMutations.convertLead`)                                     |
| **Subscribers** | PM-01 (patient registration), PM-38 (appointment automation), Analytics |
| **Delivery**    | At-least-once (FW-16)                                                   |
| **Idempotency** | `correlation_id` — subscribers must deduplicate                         |

**Payload (IDs only — no PHI):**

```typescript theme={null}
{
  lead_id: string;        // UUID
  contact_id: string;     // UUID
  organization_id: string; // UUID
  correlation_id: string;  // Format: "{lead_id}_to_{type}_{timestamp}"
  converted_to_type: string;
  converted_to_id?: string;
  converted_by: string;    // UUID (user)
  converted_at: string;    // ISO 8601
}
```

### `ce_lead_converted_to_resident`

Same payload schema as above. Subscribers: RH-01 (admission), PM-39 (waitlist), Analytics.

### `ce_lead_converted` *(deprecated)*

Legacy event maintained for backward compatibility with CE-17 consumers. Same payload. New consumers should use the granular events above.

***

## Audit Table: `ce_lead_conversions`

**Pattern:** INSERT-only (no UPDATE/DELETE policies). Immutable audit trail.

| Column            | Type        | Notes                                                           |
| ----------------- | ----------- | --------------------------------------------------------------- |
| `id`              | UUID        | PK                                                              |
| `organization_id` | UUID        | Tenant isolation (FK → pf\_organizations)                       |
| `lead_id`         | UUID        | FK → ce\_leads                                                  |
| `conversion_type` | TEXT        | `lead_to_patient`, `lead_to_resident`, `lead_to_both`           |
| `correlation_id`  | TEXT        | Idempotency key                                                 |
| `patient_id`      | UUID        | Nullable — set by PM-01 subscriber                              |
| `resident_id`     | UUID        | Nullable — plain UUID (no FK until RH-01 creates rh\_residents) |
| `converted_by`    | UUID        | User who triggered conversion                                   |
| `notes`           | TEXT        | Optional (max 500 chars)                                        |
| `custom_fields`   | JSONB       | Extension point                                                 |
| `created_at`      | TIMESTAMPTZ | Conversion timestamp                                            |
| `created_by`      | UUID        | Audit                                                           |

***

## Permissions

| Key                          | Description             |
| ---------------------------- | ----------------------- |
| `ce.lead-conversions.view`   | View conversion history |
| `ce.lead-conversions.create` | Trigger lead conversion |

Mapped to: `org_admin`, `platform_admin`

***

## Idempotency Rules

1. Each conversion generates a unique `correlation_id` in format `{lead_id}_to_{conversion_type}_{timestamp}`. The `correlation_id` is created **once per user intent** and must be reused unchanged across retries or double-submits — it is not regenerated on each attempt.
2. For `lead_to_both`, two audit records are inserted (one per type) with distinct correlation IDs
3. Downstream subscribers (PM-01, RH-01) MUST check `correlation_id` before creating entities
4. Duplicate delivery with same `correlation_id` returns success without creating a second record (enforced by UNIQUE constraint on `(organization_id, lead_id, conversion_type, correlation_id)`)

***

## References

* **Full Spec:** `specs/ce/specs/CE-29-lead-to-patient-conversion-pipeline.md`
* **Integration Doc:** `docs/architecture/integrations/CE-29-LEAD-CONVERSION-INTEGRATION.md`
* **Event Contracts:** `docs/architecture/integrations/EVENT_CONTRACTS.md`
* **CE-17 (deprecated):** `specs/ce/specs/CE-17-ce-rh-admission-handoff.md`