aionboarding/ai-patient-onboarding/docs/ONBOARDING_API.md

# Text Onboarding & Document API Reference

**Implementation Sources**: [`app/api/onboarding.py`](file:///c:/Users/Lenovo/New%20folder%20%282%29/ai-patient-onboarding/app/api/onboarding.py), [`app/api/documents.py`](file:///c:/Users/Lenovo/New%20folder%20%282%29/ai-patient-onboarding/app/api/documents.py)

---

## 1. POST `/v1/onboarding/start`

Starts a new text-based clinical onboarding intake session.

### Request Headers:
```http
Content-Type: application/json
Authorization: Bearer test_token_PAT-10023
```

### Request Body (`StartOnboardingRequest`):
```json
{
  "patient": {
    "id": "PAT-10023",
    "name": "Kavitha Ramesh",
    "age": 35,
    "gender": "female",
    "phone": "+919876543210",
    "abha_id": "91-1234-5678-9012",
    "insurance_scheme": "PMJAY",
    "dietary_habits": "Vegetarian"
  },
  "category": {
    "type": "general",
    "code": "general_medicine",
    "name": "General Medicine"
  },
  "language": "en"
}
```

### Field Descriptions:

| Field | Type | Required | Validation Rules | Description |
| :--- | :--- | :--- | :--- | :--- |
| `patient.id` | string | **Yes** | Min length 1 | Unique patient identifier |
| `patient.name` | string | No | Optional | Full name of patient |
| `patient.age` | integer | No | $0 \le \text{age} \le 120$ | Patient age in years |
| `patient.gender` | string | No | Optional | Gender identity ("male", "female", "other") |
| `category.type` | string | **Yes** | `"general"` or `"speciality"` | Onboarding workflow type |
| `category.code` | string | **Yes** | Min length 1 | Specialty classification code |
| `category.name` | string | **Yes** | Min length 1 | Human-readable category display name |
| `language` | string | No | Default `"en"` | Preferred intake language |

### Successful Response (`200 OK` - `StartOnboardingResponse`):
```json
{
  "success": true,
  "session_id": "ONB-8F12A9C4",
  "patient_id": "PAT-10023",
  "category": {
    "type": "general",
    "code": "general_medicine",
    "name": "General Medicine"
  },
  "language": "en",
  "status": "in_progress",
  "stage": "symptoms",
  "message": "Hello Kavitha Ramesh! I am your clinical onboarding assistant. What symptoms are you experiencing today?"
}
```

---

## 2. POST `/v1/onboarding/{session_id}/message`

Sends a patient chat response to the AI intake orchestrator.

### Request Headers:
```http
Content-Type: application/json
Authorization: Bearer test_token_PAT-10023
```

### Request Body (`SendMessageRequest`):
```json
{
  "message": "I have had severe chest tightness and shortness of breath for 2 days."
}
```

### Successful Response (`200 OK` - `SendMessageResponse`):
```json
{
  "success": true,
  "session_id": "ONB-8F12A9C4",
  "stage": "medical_history",
  "message": "Thank you for sharing. Does the chest tightness radiate to your arm or jaw, and do you have any history of high blood pressure?",
  "status": "in_progress",
  "response_time_ms": 1529.74,
  "response_time_sec": 1.53
}
```

---

## 3. POST `/v1/documents/{session_id}/upload`

Uploads a medical document (lab report, prescription, discharge summary) for vision extraction.

### Request Headers:
```http
Content-Type: multipart/form-data
Authorization: Bearer test_token_PAT-10023
```

### Form Data Parameters:
- `file`: Binary file upload (**Allowed formats**: `image/jpeg`, `image/png`, `image/webp`, `application/pdf`). **Maximum size**: `10MB` (`10,485,760 bytes`).

### Successful Response (`200 OK` - `DocumentExtractionResponse`):
```json
{
  "success": true,
  "session_id": "ONB-8F12A9C4",
  "document_type": "lab_report",
  "summary": "Report indicates elevated HbA1c (7.2%) and stage 1 hypertension (130/85 mmHg).",
  "findings": [
    {
      "test": "HbA1c",
      "value": "7.2",
      "unit": "%",
      "interpretation": "Elevated"
    },
    {
      "test": "Blood Pressure",
      "value": "130/85",
      "unit": "mmHg",
      "interpretation": "Stage 1"
    }
  ],
  "medications_found": ["Metformin 500mg"],
  "allergies_found": ["Penicillin"],
  "message": "Medical document analyzed and integrated into onboarding session."
}
```

---

## 4. POST `/v1/onboarding/{session_id}/complete`

Finalizes the intake session and outputs the structured clinical EHR payload.

### Request Body (`CompleteOnboardingRequest`):
```json
{
  "confirmed": true
}
```

### Successful Response (`200 OK` - `CompleteOnboardingResponse`):
```json
{
  "success": true,
  "session_id": "ONB-8F12A9C4",
  "status": "completed",
  "result": {
    "patient_id": "PAT-10023",
    "abha_id": "91-1234-5678-9012",
    "phone": "+919876543210",
    "insurance_scheme": "PMJAY",
    "category": {
      "type": "general",
      "code": "general_medicine",
      "name": "General Medicine"
    },
    "chief_complaint": "Chest tightness and shortness of breath for 2 days",
    "symptoms": [
      {
        "name": "Chest tightness",
        "duration": "2 days",
        "severity": "severe",
        "description": "Triggered during exertion"
      }
    ],
    "medical_history": ["Prehypertension"],
    "medications": ["Metformin 500mg"],
    "allergies": ["Penicillin"],
    "dietary_habits": "Vegetarian",
    "additional_information": "Patient confirmed details.",
    "language": "en",
    "onboarding_completed": true
  },
  "message": "Onboarding successfully completed and saved to patient record.",
  "response_time_ms": 4075.41,
  "response_time_sec": 4.08
}
```