From 9186a1268fffd64c23e5a5eea15080720e663395 Mon Sep 17 00:00:00 2001 From: roshan Date: Sat, 8 Nov 2025 10:07:19 -0800 Subject: [PATCH] updated docs to include compliance plan reference for structured outputs --- .../structured-outputs-quickstart.mdx | 151 ++++++++++++++++++ fern/security-and-privacy/hipaa.mdx | 74 +++++++++ 2 files changed, 225 insertions(+) diff --git a/fern/assistants/structured-outputs-quickstart.mdx b/fern/assistants/structured-outputs-quickstart.mdx index ea57ed043..cf4d7474f 100644 --- a/fern/assistants/structured-outputs-quickstart.mdx +++ b/fern/assistants/structured-outputs-quickstart.mdx @@ -647,6 +647,157 @@ The extracted data (the `result` field from the API response) will look like thi When accessing via API, this data is nested inside the structured output object at `call.artifact.structuredOutputs[outputId].result`. The Dashboard shows the complete structure including the output ID and name. +## HIPAA Compliance & Storage Settings + + +**Important for HIPAA users:** When HIPAA mode is enabled, Vapi does not store structured outputs by default. This protects privacy but limits your ability to view structured outputs in Insights and Call Logs. + + +### Understanding the default behavior + +When your organization or assistant has HIPAA mode enabled (`hipaaEnabled: true`): +- **Structured outputs are NOT stored** - Results are generated but not persisted in Vapi's systems +- **Limited visibility** - You cannot view outputs in the Dashboard's Call Logs or Insights +- **Privacy first** - This ensures sensitive data is not retained +- **Webhook access only** - You can still receive outputs via webhooks during the call + +This default behavior protects patient privacy and ensures compliance with HIPAA regulations. + +### Enabling storage for non-sensitive outputs + +For structured outputs that extract **non-sensitive, non-PHI information**, you can override this behavior using the `compliancePlan.forceStoreOnHipaaEnabled` setting. + + +**Your responsibility:** You must ensure that any structured output with storage enabled does NOT extract or generate PHI or sensitive data. + + +#### Safe use cases for storage override + +Enable storage for these types of non-sensitive outputs: + +- **Boolean outcomes**: `appointmentBooked: true/false`, `callSuccessful: true/false` +- **General categories**: `issueCategory: "billing" | "technical" | "general"` +- **Satisfaction scores**: `csatScore: 1-10` +- **Call metrics**: `sentiment: "positive" | "neutral" | "negative"` +- **Success indicators**: `issueResolved: boolean`, `followUpRequired: boolean` + +#### Never enable storage for these + +**Do not** enable storage for outputs that extract: +- Patient names, dates of birth, or contact information +- Diagnosis, treatment, or medication information +- Medical record numbers or identifiers +- Social security numbers +- Credit card or payment details + +### Configuration examples + + + + 1. Navigate to **Structured Outputs** in the left sidebar + 2. Create or edit a structured output + 3. Expand the **Compliance Settings** section + 4. Enable the toggle for "Enable Storage of Structured Outputs while on HIPAA Mode" + 5. **Recommendation**: Only enable if your output does not extract sensitive information + + + +```bash +# Creating a HIPAA-safe structured output with storage enabled +curl -X POST https://api.vapi.ai/structured-output \ + -H "Authorization: Bearer $VAPI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Appointment Booked", + "type": "ai", + "description": "Boolean indicator of whether appointment was booked", + "schema": { + "type": "boolean", + "description": "Whether an appointment was successfully booked during the call" + }, + "compliancePlan": { + "forceStoreOnHipaaEnabled": true + } + }' +``` + + + +```typescript +import { VapiClient } from "@vapi-ai/server-sdk"; + +const vapi = new VapiClient({ token: process.env.VAPI_API_KEY! }); + +// Safe: Boolean outcome, no PHI +const structuredOutput = await vapi.structuredOutputs.create({ + name: "Appointment Booked", + type: "ai", + description: "Boolean indicator of whether appointment was booked", + schema: { + type: "boolean", + description: "Whether an appointment was successfully booked during the call" + }, + compliancePlan: { + forceStoreOnHipaaEnabled: true // Safe because output contains no PHI + } +}); + +// Update existing structured output to enable storage +await vapi.structuredOutputs.update(structuredOutput.id, { + compliancePlan: { + forceStoreOnHipaaEnabled: true + } +}); +``` + + + +```python +from vapi import Vapi +import os + +vapi = Vapi(token=os.environ.get("VAPI_API_KEY")) + +# Safe: Boolean outcome, no PHI +structured_output = vapi.structured_outputs.create( + name="Appointment Booked", + type="ai", + description="Boolean indicator of whether appointment was booked", + schema={ + "type": "boolean", + "description": "Whether an appointment was successfully booked during the call" + }, + compliance_plan={ + "forceStoreOnHipaaEnabled": True + } +) + +# Update existing structured output to enable storage +vapi.structured_outputs.update( + structured_output.id, + compliance_plan={ + "forceStoreOnHipaaEnabled": True + } +) +``` + + + + +**IMPORTANT:** Only set `forceStoreOnHipaaEnabled: true` if you are certain your structured output does NOT extract PHI or sensitive data. Review your schema carefully before enabling storage. + + +### Best practices for HIPAA compliance + +1. **Default to privacy**: Keep storage disabled for all outputs that might contain PHI +2. **Review schemas carefully**: Ensure your extraction logic cannot accidentally capture sensitive data +3. **Use specific schemas**: Design narrow schemas that target only non-sensitive data +4. **Test thoroughly**: Verify outputs don't contain PHI before enabling storage +5. **Document decisions**: Maintain records of which outputs have storage enabled and why +6. **Regular audits**: Periodically review stored outputs to ensure compliance + +For more information about HIPAA compliance with Vapi, see our [HIPAA Compliance Guide](/security-and-privacy/hipaa). + ## Next steps diff --git a/fern/security-and-privacy/hipaa.mdx b/fern/security-and-privacy/hipaa.mdx index d79acb2cc..6881fcd47 100644 --- a/fern/security-and-privacy/hipaa.mdx +++ b/fern/security-and-privacy/hipaa.mdx @@ -97,6 +97,80 @@ When enabling HIPAA compliance, only HIPAA compliant providers may be chosen. +## Structured Outputs with HIPAA Mode + +When HIPAA mode is enabled, Vapi does not store structured outputs by default. This protects privacy but limits your ability to use structured outputs in Insights and Call Logs. For non-sensitive outputs, you can override this behavior. + + + + By default, when HIPAA mode is on, Vapi doesn't store structured outputs. This keeps data private but limits your ability to use structured outputs in Insights and Call Logs. + + You can enable storage for specific structured outputs using the `compliancePlan.forceStoreOnHipaaEnabled` setting. This allows you to store non-sensitive outputs even when HIPAA mode is active. + + **Important:** Your organization is responsible for ensuring that any structured output with storage enabled does NOT extract or generate PHI or sensitive data. Only use this for non-sensitive information. + + + + Enable storage ONLY for structured outputs that extract non-sensitive, non-PHI information. + + **Safe use cases:** + - Boolean outcomes: `appointmentBooked: true/false` + - Call success indicators: `issueResolved: true/false` + - General categories: `issueCategory: "billing" | "technical" | "general"` + - Satisfaction scores: `csatScore: 1-10` + - Call sentiment: `sentiment: "positive" | "neutral" | "negative"` + + **Never enable storage for:** + - Patient diagnosis information + - Medical record numbers + - Social security numbers + - Credit card details + - Patient names, dates of birth, or contact information + - Treatment plans or medication information + + **Warning:** Enabling storage for outputs containing PHI violates HIPAA compliance and your BAA with Vapi. + + + + You can enable storage for specific structured outputs via the Dashboard or API. + + **Via Dashboard:** + 1. Navigate to **Structured Outputs** in the left sidebar + 2. Create or edit a structured output + 3. Expand the **Compliance Settings** section + 4. Enable the toggle for "Enable Storage of Structured Outputs while on HIPAA Mode" + 5. Only enable if your output does not extract sensitive information + + **Via API:** + + When creating a structured output: + ```json + { + "name": "Appointment Booked", + "type": "ai", + "schema": { + "type": "boolean", + "description": "Whether an appointment was successfully booked" + }, + "compliancePlan": { + "forceStoreOnHipaaEnabled": true + } + } + ``` + + When updating a structured output: + ```json + { + "compliancePlan": { + "forceStoreOnHipaaEnabled": true + } + } + ``` + + **IMPORTANT:** Only set `forceStoreOnHipaaEnabled: true` if you are certain your structured output does NOT extract PHI or sensitive data. Your organization is responsible for ensuring compliance. Misuse could result in BAA violations. + + + ## Best Practices