aionboarding/ai-patient-onboarding/POSTMAN_COLLECTION_GUIDE.md

Postman Collection Import & Usage Guide

API System: AI Patient Onboarding API v1.0.0
Environment: Local / Staging / Production
Collection File: AI-Patient-Onboarding.postman_collection.json
Environment File: AI-Patient-Onboarding-Local.postman_environment.json

---

1. Quick Start Import Instructions

1. Open Postman Desktop Application.
2. Click Import (top-left button).
3. Select both files:
   • AI-Patient-Onboarding.postman_collection.json
   • AI-Patient-Onboarding-Local.postman_environment.json
4. Select environment "AI-Patient-Onboarding-Local" from the environment dropdown in the top-right corner.

---

2. Collection Hierarchy

AI Patient Onboarding API
├── 00 - Health
│   └── Get Service Health Status (GET /health)
├── 01 - Authentication
│   └── Test Bearer Auth Token Validation
├── 02 - Patient Onboarding (Text)
│   ├── Start Text Onboarding (POST /v1/onboarding/start) -> auto-saves {{session_id}}
│   ├── Send Patient Message (POST /v1/onboarding/{{session_id}}/message)
│   └── Complete Text Onboarding (POST /v1/onboarding/{{session_id}}/complete)
├── 03 - Voice Onboarding
│   ├── Start Voice Onboarding (POST /v1/voice-onboarding/start) -> auto-saves {{voice_session_id}} & {{audio_id}}
│   ├── Voice Turn - Text Fallback (POST /v1/voice-onboarding/{{voice_session_id}}/turn)
│   ├── Complete Voice Onboarding (POST /v1/voice-onboarding/{{voice_session_id}}/complete)
│   └── Get Synthesized Audio File (GET /v1/voice-onboarding/audio/{{audio_id}})
├── 04 - Documents
│   └── Upload Patient Document (POST /v1/documents/{{session_id}}/upload)
├── 05 - Validation Tests
│   └── Reject Negative Age Input (age = -50 -> 422)
├── 06 - Authorization / IDOR Security Tests
│   └── Reject Cross-Patient IDOR Access (Patient B -> Patient A Session -> 403)
└── 07 - Security & Auth Tests
    └── Reject Unauthenticated Request (Missing Token -> 401)

---

3. Dynamic Variable Chaining

The collection automatically passes state between requests using Postman Environment variables:

• Running Start Text Onboarding extracts session_id from response JSON and sets {{session_id}}.
• Subsequent requests (Send Patient Message, Complete Text Onboarding, Upload Patient Document) dynamically consume {{session_id}}.
• Running Start Voice Onboarding extracts session_id and audio_id into {{voice_session_id}} and {{audio_id}}.

---

4. Running via Postman Collection Runner / Newman CLI

If Newman CLI is installed locally:

newman run AI-Patient-Onboarding.postman_collection.json -e AI-Patient-Onboarding-Local.postman_environment.json