AI Patient Onboarding API — Frontend Integration Guide

Version: 1.0.0
Target Audience: Frontend Engineers (React / React Native / Vue / Next.js / Mobile)
Backend Framework: FastAPI (Python 3.13)
Supported Protocols: HTTP/1.1 REST, JSON, Multipart/Form-Data Formats
Interactive API Documentation:

Swagger UI: {BASE_URL}/docs
ReDoc: {BASE_URL}/redoc
OpenAPI Schema: {BASE_URL}/openapi.json

1. Executive System Overview

The AI Patient Onboarding API is an enterprise multi-modal clinical intake system designed for hospitals, clinics, and digital health platforms. It automates patient registration, symptom intake, medical history collection, document extraction, and specialty triage before a physician consultation.

Key Capabilities for Frontend Applications:

Multi-Modal Onboarding:
- Text-Based Onboarding: Interactive chat-based intake powered by clinical LLM orchestrator.
- Voice-First Onboarding: Natural conversational voice intake supporting English (en-IN), Tamil (ta-IN), Hindi (hi-IN), Telugu (te-IN), Kannada (kn-IN), Malayalam (ml-IN), and Marathi (mr-IN) using Sarvam AI ASR/TTS.
Medical Document Analysis: Vision-based processing of lab reports, prescriptions, and discharge summaries (JPEG, PNG, WEBP, PDF up to 10MB).
Session-Based State Engine: Stateful intake tracking stored in persistent backend database.
Structured EHR Output: Automatic clinical JSON result extraction matching standard Electronic Health Record (EHR) models.

2. Server Base URLs & CORS Configuration

Server Base URLs:

Local Development: http://localhost:8000 or http://127.0.0.1:8000
Staging / Production: Configured via environment variable ({BASE_URL})

The backend enforces production-safe CORSMiddleware.

Allowed Origins: http://localhost:3000, http://localhost:5173, http://127.0.0.1:3000, http://127.0.0.1:5173, https://onboarding.skyheal.ai (configurable via CORS_ORIGINS).
Allowed Credentials: true (Access-Control-Allow-Credentials: true).
Allowed Headers: Authorization, Content-Type, X-API-Key, X-Patient-ID, X-Request-ID, Accept, Origin.
Exposed Headers: X-Request-ID.

3. Quick Start Integration Flow

[ Frontend App ]
       │
       ├── 1. POST /v1/onboarding/start (or /v1/voice-onboarding/start)
       │      └─► Returns session_id (e.g. "ONB-8F12A9C4" or "VOICE-D3CAEA5C")
       │
       ├── 2. POST /v1/onboarding/{session_id}/message (or /turn for voice)
       │      └─► Exchanges multi-turn symptom history & receiving AI responses
       │
       ├── 3. POST /v1/documents/{session_id}/upload (Optional)
       │      └─► Uploads medical reports / lab results
       │
       └── 4. POST /v1/onboarding/{session_id}/complete
              └─► Returns final structured EHR result (PatientOnboardingResult)

4. Documentation Index

To explore detailed specifications, refer to the following module guides:

Module Guide	Focus Area	Description
`AUTHENTICATION.md`	Security & Headers	Bearer tokens, `X-API-Key`, patient session isolation (IDOR protection).
`ONBOARDING_API.md`	Text & Document Intake	Full specification for text chat endpoints, document OCR, and session completion.
`VOICE_ONBOARDING_API.md`	Voice & Speech APIs	Audio streaming, WebSpeech fallbacks, multilingual Sarvam AI voice turns.
`ERROR_HANDLING.md`	Error Codes & SLAs	HTTP 401, 403, 413, 422, 429 status codes and SLA latency boundaries.
`FRONTEND_EXAMPLES.md`	TypeScript & React	Copy-pasteable React hooks, MediaRecorder voice capture, and fetch client examples.

5. Master API Endpoint Directory

HTTP Method	Endpoint Path	Auth Required	Rate Limit	Purpose
`GET`	`/health`	No	None	Service health check & AI provider status
`POST`	`/v1/onboarding/start`	Yes	30 req/min	Start text onboarding session
`POST`	`/v1/onboarding/{session_id}/message`	Yes	30 req/min	Send text intake message to AI
`POST`	`/v1/onboarding/{session_id}/complete`	Yes	30 req/min	Finalize text session & output structured result
`POST`	`/v1/voice-onboarding/start`	Yes	30 req/min	Start voice onboarding session
`POST`	`/v1/voice-onboarding/{session_id}/turn`	Yes	30 req/min	Process speech recording or text fallback turn
`POST`	`/v1/voice-onboarding/{session_id}/complete`	Yes	30 req/min	Finalize voice session & output structured result
`GET`	`/v1/voice-onboarding/audio/{audio_id}`	No	None	Stream TTS audio response (WAV/MP3)
`POST`	`/v1/documents/{session_id}/upload`	Yes	10 req/min	Upload medical document / report (10MB max)

6. Response Time & Timing Metadata

All interactive conversation endpoints append performance metadata to help frontend applications measure latency:

{
  "success": true,
  "session_id": "ONB-8F12A9C4",
  "response_time_ms": 1529.74,
  "response_time_sec": 1.53
}

response_time_ms: Backend processing duration in milliseconds (floating-point number).
response_time_sec: Backend processing duration in seconds (rounded to 3 decimal places).

5.8 KiB Raw Blame History