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

Text Onboarding & Document API Reference

Implementation Sources: app/api/onboarding.py, app/api/documents.py

---

1. POST /v1/onboarding/start

Starts a new text-based clinical onboarding intake session.

Request Headers:

Content-Type: application/json
Authorization: Bearer test_token_PAT-10023

Request Body (StartOnboardingRequest):

{
  "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):

{
  "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:

Content-Type: application/json
Authorization: Bearer test_token_PAT-10023

Request Body (SendMessageRequest):

{
  "message": "I have had severe chest tightness and shortness of breath for 2 days."
}

Successful Response (200 OK - SendMessageResponse):

{
  "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:

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):

{
  "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):

{
  "confirmed": true
}

Successful Response (200 OK - CompleteOnboardingResponse):

{
  "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
}