# 05 — Patients

← [Back to index](README.md)

---

## `GET /patients?query=&page=1&pageSize=20`
Search + paginate. `query` matches name **or** phone. Defaults `page=1`, `pageSize=20`.

**Response `200` — `PaginatedPatients`**
```json
{
  "items": [
    {
      "id": "p1",
      "fullName": "محمد علي حسن",
      "dateOfBirth": "1985-03-12T00:00:00Z",
      "gender": "male",
      "phone": "01001234567",
      "lastVisitAt": "2026-05-20T09:00:00Z",
      "hasAllergyAlert": true
    }
  ],
  "page": 1,
  "pageSize": 20,
  "totalCount": 67
}
```
`items[]` is the **PatientSummary** shape. `hasAllergyAlert` = patient has any recorded
allergy (drives a UI badge — derive from medical record).

---

## `GET /patients/{id}`
**Response `200` — full `Patient`**
```json
{
  "id": "p1",
  "fullName": "محمد علي حسن",
  "dateOfBirth": "1985-03-12T00:00:00Z",
  "gender": "male",
  "phone": "01001234567",
  "phoneAlt": null,
  "email": null,
  "nationalId": null,
  "address": null,
  "bloodType": "a_pos",
  "emergencyContact": { "name": "سارة", "phone": "01009998888", "relation": "زوجة" },
  "insurance": { "provider": "مصر للتأمين", "policyNumber": "POL-123" },
  "lastVisitAt": "2026-05-20T09:00:00Z",
  "createdAt": "2024-01-10T12:00:00Z"
}
```

---

## `POST /patients`
**Request** — Patient without `id`/`createdAt` (server assigns). Required: `fullName`,
`dateOfBirth`, `gender`, `phone`. Everything else nullable. Same nested
`emergencyContact` / `insurance` objects.
**Response `201`** — the created Patient.

## `PUT /patients/{id}`  *(PATCH also acceptable)*
**Request** — Patient fields to update. **Response `200`** — updated Patient.

## `DELETE /patients/{id}`
**Soft delete only** (never hard-erase medical records). **Response `200`/`204`**.

---

## Field contracts

### `Patient`
| Field | Type | Nullable | Notes |
|---|---|---|---|
| `id` | string | no | |
| `fullName` | string | no | |
| `dateOfBirth` | datetime | no | date (time may be 00:00) |
| `gender` | string | no | [Gender](11-enums.md) |
| `phone` | string | no | |
| `phoneAlt` | string | yes | |
| `email` | string | yes | |
| `nationalId` | string | yes | **encrypt at rest** |
| `address` | string | yes | |
| `bloodType` | string | no | [BloodType](11-enums.md), default `unknown` |
| `emergencyContact` | object | yes | `EmergencyContact` |
| `insurance` | object | yes | `InsuranceInfo` |
| `lastVisitAt` | datetime | yes | |
| `createdAt` | datetime | yes | server-set |

### `PatientSummary` (list rows)
`id`, `fullName`, `dateOfBirth`, `gender`, `phone`, `lastVisitAt?`, `hasAllergyAlert` (bool).

### `EmergencyContact`
`name` (req), `phone` (req), `relation?` (free text — e.g. "زوجة"، "أب").

### `InsuranceInfo`
`provider` (req), `policyNumber` (req — **encrypt at rest**).

### `PaginatedPatients`
`items` (PatientSummary[]), `page` (int), `pageSize` (int), `totalCount` (int).
