# 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`](file:///c:/Users/Lenovo/New%20folder%20%282%29/ai-patient-onboarding/AI-Patient-Onboarding.postman_collection.json)  
**Environment File**: [`AI-Patient-Onboarding-Local.postman_environment.json`](file:///c:/Users/Lenovo/New%20folder%20%282%29/ai-patient-onboarding/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:

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