Welcome to PatientPulse. This guide will take you from zero to your first API call in under 5 minutes, then walk you through the core concepts for building production healthcare applications on top of the platform.
PatientPulse is a FastAPI (Python) monolith with 452 endpoints covering the full clinical, billing, AI, and interoperability stack. PulseVault is an Express (Node.js) mobile BFF with 88 endpoints for the Android patient app. Both share a PostgreSQL database.
Visit the Developer Portal, sign up, and copy your sandbox publishable and secret keys.
PP_API_BASE_URL=https://api.patientpulse.in PP_API_KEY=pp_sandbox_sk_your_key_here DATABASE_URL=postgresql://user:pass@localhost:5432/pp_dev JWT_SECRET=your_jwt_secret_min_32_chars ABDM_INTEGRATION_ENABLED=true ABDM_CONNECTOR_MODE=stub
curl -X POST https://api.patientpulse.in/auth/patient/request-otp \
-H "Content-Type: application/json" \
-H "X-API-Key: pp_sandbox_sk_your_key_here" \
-d '{
"phone": "+919876543210",
"channel": "sms"
}'{"status": "otp_sent", "expires_in": 300, "channel": "sms"}
curl -X POST https://api.patientpulse.in/auth/patient/verify-otp \
-H "Content-Type: application/json" \
-H "X-API-Key: pp_sandbox_sk_your_key_here" \
-d '{
"phone": "+919876543210",
"otp": "123456"
}'
# Returns: access_token, user objectcurl https://api.patientpulse.in/auth/me \
-H "Authorization: Bearer <access_token>"
# Book an appointment
curl -X POST https://api.patientpulse.in/appointments \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"patient_id": "pat_abc123",
"doctor_id": "doc_xyz",
"slot_id": "slot_001",
"visit_type": "opd"
}'PatientPulse supports three authentication methods depending on the user type:
Phone-based OTP via Twilio SMS or WhatsApp. Primary patient flow. Returns JWT + HttpOnly refresh cookie.
Exchange a Google ID token for a PatientPulse session. Used by the web patient portal.
SAML 2.0 SSO for clinic staff. Initiated via the SSO endpoint, per-org IdP config required.
OTP requests are rate-limited. Configurable via AUTH_OTP_PHONE_LIMIT_PER_15_MIN (default: 5) and AUTH_LOGIN_IP_LIMIT_PER_5_MIN (default: 10). Exceeding limits returns HTTP 429.
| Environment | Base URL | Key Prefix | Notes |
|---|---|---|---|
| Sandbox | https://sandbox.patientpulse.in | pp_sandbox_sk_ | No real data. ABDM stub mode. Free. |
| Production | https://api.patientpulse.in | pp_live_sk_ | Live ABDM, Razorpay, Twilio. Paid plans. |
| Local | http://localhost:8000 | any | Self-hosted via Docker or uvicorn. |
Run PatientPulse locally with uvicorn (Python backend) and the frontend Vite dev server.
# Clone and set up cd Healthcare_app/backend pip install -r requirements.txt cp .env.example .env # fill in your values # Run database migrations python -m app.db.migrate # Start the API server (port 8000) uvicorn app.main_monolith:app --reload --port 8000
cd Healthcare_app/frontend
npm install
npm run dev # Vite dev server on port 5173cd Vault/backend/node-express
npm install
cp .env.example .env
npm run dev # Express on port 3000version: '3.9' services: db: image: postgres:16 environment: POSTGRES_DB: patientpulse POSTGRES_USER: pp_user POSTGRES_PASSWORD: pp_pass ports: ["5432:5432"] api: build: ./Healthcare_app/backend ports: ["8000:8000"] env_file: .env depends_on: [db] vault-api: build: ./Vault/backend/node-express ports: ["3000:3000"] env_file: vault.env depends_on: [db]
PatientPulse has 249 configurable environment variables. Here are the essential ones to get started:
| Variable | Required | Description |
|---|---|---|
| JWT_SECRET | required | Min 32 chars. Used to sign JWT access tokens. |
| DATABASE_URL | required | PostgreSQL connection string. |
| APP_ENV | required | development | production |
| TWILIO_ACCOUNT_SID | for OTP | Required for live OTP delivery. |
| RAZORPAY_KEY_ID | for payments | Required for payment flows. |
| ABDM_CONNECTOR_MODE | optional | stub (dev) or live (prod). Default: stub. |
| AI_ENABLED | optional | true to enable AI endpoints. Requires OPENAI_API_KEY or AI_LOCAL_MODEL_URL. |
| OPENAI_API_KEY | for AI | OpenAI key for cloud LLM. Or use AI_LOCAL_MODEL_URL for Ollama. |
Patients are the central entity. A patient has a profile, appointment history, medical records, prescriptions, and an optional ABHA identity link.
// Create a patient profile const patient = await fetch('https://api.patientpulse.in/profiles', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Ramesh Kumar', phone: '+919876543210', date_of_birth: '1985-04-15', gender: 'male', }), }).then(r => r.json()); // Get patient profile const profile = await fetch( `https://api.patientpulse.in/patient/profile`, { headers: { 'Authorization': `Bearer ${token}` } } ).then(r => r.json());
AI features are behind the AI_ENABLED=true flag. Three main AI endpoints are available:
POST /ai/interpret-lab-report — pass a record ID to get structured AI analysis of lab results with abnormal flags.
POST /ai/ambient-scribe — submit a consultation transcript; receive a SOAP clinical note.
GET /forecast — ML-driven OPD/Emergency patient volume prediction up to 14 days ahead.
Set AI_NO_RAW_PATIENT_DATA=true to automatically strip patient identifiers before any prompt reaches the LLM. Works with both OpenAI cloud and local Ollama.
PatientPulse ships a full ABDM connector. Start in stub mode (no NHA credentials required) and switch to live when you have your NHA sandbox registration.
ABDM_CONNECTOR_MODE=stubAll ABDM calls return realistic mock responses. No NHA registration needed.
Get your Health Facility ID, ABDM API key, and sandbox credentials.
ABDM_CONNECTOR_MODE=live + credentialsSet ABDM_CONNECTOR_BASE_URL and ABDM_CONNECTOR_API_KEY in your environment.
Set ABDM_AUTO_PUSH_ON_CONSULT=true — PatientPulse will automatically assemble and push FHIR R4 bundles to patients' ABHA health lockers after each completed consult.
PulseVault is the patient-facing Android app. It talks to its own Node.js Express backend, which can proxy requests to PatientPulse via environment flags.
Set NODE_AUTH_PROXY_ENABLED=true, NODE_PATIENT_DOMAIN_PROXY_ENABLED=true, and CANONICAL_BACKEND_BASE_URL=https://your-patientpulse-host/ to route all PulseVault API calls through to the canonical PatientPulse backend. This allows a zero-downtime migration without changing the Android app.