clqms-be/docs/api_contract_patient_registration.md

# Patient Registration API Contract

**Version:** 1.0.0
**Base URL:** `/api/v1`

---

## 1. Patients (`/patients`)

### GET /patients
Retrieve list of patients.

**Query Parameters:**
- `page` (int, default: 1)
- `limit` (int, default: 20)
- `search` (string) - Search by name, MRN (PatientID), or phone.

**Response (200 OK):**
```json
{
  "data": [
    {
      "InternalPID": 1001,
      "PatientID": "MRN-2025-0001",
      "NameFirst": "John",
      "NameLast": "Doe",
      "Gender": 1,
      "Birthdate": "1990-05-15",
      "MobilePhone": "+1234567890",
      "EmailAddress1": "john.doe@example.com"
    }
  ]
}
```

---

### POST /patients
Register a new patient.

**Request Body:**
```json
{
  "PatientID": "MRN-2025-0002",
  "AlternatePID": "ALT-123",            // Optional
  "Prefix": "Mr.",                        // Optional
  "NameFirst": "Jane",
  "NameMiddle": "Marie",                  // Optional
  "NameLast": "Doe",
  "NameMaiden": null,                     // Optional
  "Suffix": null,                         // Optional
  "Gender": 2,                            // 1=Male, 2=Female (example)
  "Birthdate": "1992-08-20",
  "PlaceOfBirth": "New York",             // Optional
  "Street_1": "123 Main St",
  "Street_2": "Apt 4B",                   // Optional
  "City": "Metropolis",
  "Province": "NY",
  "ZIP": "10001",
  "Phone": "555-0100",                    // Optional
  "MobilePhone": "555-0199",
  "EmailAddress1": "jane.doe@example.com",
  "MaritalStatus": 1,                     // 1=Single, 2=Married, etc.
  "Religion": 1,                          // Optional ID
  "Race": 1,                              // Optional ID
  "Citizenship": "USA"                    // Optional
}
```

**Response (201 Created):**
```json
{
  "message": "Patient created successfully",
  "data": {
    "InternalPID": 1002,
    "PatientID": "MRN-2025-0002",
    "CreateDate": "2025-12-16T10:00:00Z"
  }
}
```

---

### GET /patients/{id}
Get full details of a specific patient.

**Response (200 OK):**
```json
{
  "data": {
    "InternalPID": 1001,
    "PatientID": "MRN-2025-0001",
    "NameFirst": "John",
    "NameLast": "Doe",
    "identifiers": [
      {
        "PatIdtID": 5,
        "IdentifierType": "Passport",
        "Identifier": "A12345678"
      }
    ],
    "relations": [],
    "comments": []
  }
}
```

---

### PUT /patients/{id}
Update patient demographics.

**Request Body:**
```json
{
  "NameLast": "Smith",
  "MobilePhone": "555-9999",
  "EmailAddress1": "john.smith@example.com"
}
```

**Response (200 OK):**
```json
{
  "message": "Patient updated successfully",
  "data": { "InternalPID": 1001 }
}
```

---

## 2. Patient Identifiers (`/patients/{id}/identifiers`)

### POST /patients/{id}/identifiers
Add an identifier (SSN, Passport, Driver's License) to a patient.

**Request Body:**
```json
{
  "IdentifierType": "SSN",
  "Identifier": "000-11-2222",
  "EffectiveDate": "2020-01-01", // Optional
  "ExpirationDate": "2030-01-01" // Optional
}
```

**Response (201 Created):**
```json
{
  "message": "Identifier added",
  "data": { "PatIdtID": 15 }
}
```

---

## 3. Patient Comments (`/patients/{id}/comments`)

### POST /patients/{id}/comments
Add a comment to a patient record.

**Request Body:**
```json
{
  "Comment": "Patient requests wheelchair assistance upon arrival."
}
```

**Response (201 Created):**
```json
{
  "message": "Comment added",
  "data": { "PatComID": 42 }
}
```

---

## 4. Patient Relations (`/patients/{id}/relations`)
*Note: Pending Schema Update (Currently `patrelation` is missing columns)*

### POST /patients/{id}/relations
Add a family member or emergency contact.

**Request Body:**
```json
{
  "RelatedPID": 1050,         // If relation is also a patient
  "RelationType": "Spouse",   // Requires schema update to store this
  "IsEmergency": true         // Requires schema update
}
```

**Response (201 Created):**
```json
{
  "message": "Relation added",
  "data": { "PatRelID": 8 }
}
```

---

## 5. Patient Attachments (`/patients/{id}/attachments`)

### POST /patients/{id}/attachments
Upload a file for a patient (insurance card, ID scan).

**Request (Multipart/Form-Data):**
- `file`: (Binary File)
- `Address`: (string, optional description or file path reference)

**Response (201 Created):**
```json
{
  "message": "File uploaded",
  "data": {
    "PatAttID": 99,
    "Address": "/uploads/patients/1001/scan_id.pdf"
  }
}
```