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

# SDOH Screening & Social Needs — Integration

> Feature ID: CL-18 Status: ✅ Implemented Spec Reference: CL-18-sdoh-screening-social-needs.md Last Updated: 2026-02-23 Last Verified: 2026-02-23

**Feature ID:** CL-18\
**Status:** ✅ Implemented\
**Spec Reference:** [CL-18-sdoh-screening-social-needs.md](../../../specs/cl/specs/CL-18-sdoh-screening-social-needs.md)\
**Last Updated:** 2026-02-23\
**Last Verified:** 2026-02-23

***

## Overview

CL-18 adds SDOH screening (e.g. PRAPARE, AHC-HRSN), social needs tracking, community resource referrals, and ICD-10-CM Z-code (Z55–Z65) documentation. Integration is via patient chart (CL-01), comprehensive assessment (CL-02), PF-70 code library, and an optional event for analytics/workflow.

***

## Integration Points (from Spec)

| Dependency                        | Pattern  | Purpose                                                                 |
| --------------------------------- | -------- | ----------------------------------------------------------------------- |
| PF-01 (Organizations & Sites)     | Direct   | Multi-tenant isolation                                                  |
| PF-02 (RBAC)                      | Direct   | Role-based access; permission keys (PF-30)                              |
| PF-08 (Profiles)                  | Direct   | screened\_by, referred\_by, audit columns                               |
| PF-70 (Medical Terminology)       | Platform | ICD-10-CM Z55–Z65 for SDOH documentation                                |
| CL-01 (Patient Chart)             | Internal | SDOH screenings and referrals visible on chart; Z-codes on problem list |
| CL-02 (Comprehensive Assessments) | Internal | SDOH element may link to or trigger standalone screening                |

***

## API / Data Contracts

* **Screenings:** `cl_sdoh_screenings` (chart\_id, instrument, screened\_at, screened\_by, responses JSONB, needs\_identified\[], custom\_fields). No public REST API; access via Supabase client and RLS.
* **Referrals:** `cl_social_referrals` (chart\_id, screening\_id, resource\_name, resource\_type, need\_category, status, referred\_at, referred\_by, outcome\_notes, outcome\_at, custom\_fields). Same access pattern.
* **Z-codes:** PF-70 code library provides type-ahead and validation for Z55–Z65; link from screening or problem list (CL-01).

***

## Event Contracts

* **Published (optional):** `cl_sdoh_screening_completed` — for analytics/workflow.

**Payload (final schema in EVENT\_CONTRACTS.md when implemented):**

| Field              | Type        | Source / Notes                                                                                       |
| ------------------ | ----------- | ---------------------------------------------------------------------------------------------------- |
| `event_id`         | UUID        | Unique event instance                                                                                |
| `screening_id`     | UUID        | `cl_sdoh_screenings.id`                                                                              |
| `chart_id`         | UUID        | `cl_sdoh_screenings.chart_id` (primary reference; consumers resolve patient via `cl_patient_charts`) |
| `organization_id`  | UUID        | Tenant context                                                                                       |
| `needs_identified` | TEXT\[]     | Copy of `cl_sdoh_screenings.needs_identified` at event time                                          |
| `screened_at`      | TIMESTAMPTZ | Optional; for event ordering                                                                         |

Consumers MUST resolve patient identity from `chart_id`; `patient_id` is not in the payload (see EVENT\_CONTRACTS.md).

* **Consumed:** None for MVP.

***

## Security and RLS

* **Tables:** `cl_sdoh_screenings`, `cl_social_referrals` — RLS enabled; org-scoped via SECURITY DEFINER helpers; UPDATE policies with WITH CHECK per constitution §5.2.4.
* **PHI:** Screening responses and referral data are PHI; no PHI in logs or external AI.
* **Permissions:** `cl.sdoh_screenings.view` / `.create`, `cl.social_referrals.view` / `.create` / `.update`; seed via migration (PF-30).

***

## Related Docs

* [CL-18 Spec](../../../specs/cl/specs/CL-18-sdoh-screening-social-needs.md)
* [CL-01 Patient Chart](./patient-chart-clinical-summary-integration.md) — Chart shell, problem list
* [CL-02 Comprehensive Assessments](./comprehensive-assessments-integration.md) — Assessment linkage
* [PF-70 Medical Terminology](./medical-terminology-code-libraries-integration.md) — Z-code library
* [docs/architecture/integrations/index.md](index.md)