Structured outputs quickstart

Overview

This quickstart guide will help you set up structured outputs to automatically extract customer information from phone calls. In just a few minutes, you’ll create a structured output, link it to an assistant, and test data extraction.

What are structured outputs?

Structured outputs are AI-powered analysis and extraction tools that intelligently process conversation data after calls end. They go beyond simple data extraction to provide intelligent analysis and evaluation. They work by:

1. Processing complete call context - After the call ends, structured outputs analyze the full transcript, messages, tool call results, and call metadata
2. Intelligent extraction & analysis - Based on your schema, they can extract data, evaluate outcomes, analyze sentiment, determine success criteria, and summarize complex interactions
3. Validating and formatting - Results are validated against your schema rules and formatted into clean, structured JSON
4. Delivering insights - The processed data and insights are available via API or webhooks once analysis is complete

When are structured outputs generated?

Structured outputs are processed:

• After call completion - The full conversation is analyzed once the call ends
• Processing time - Typically completes within a few seconds after call termination
• Available via - Call artifacts in the API response or webhook events

What data do structured outputs have access to?

When processing, structured outputs can analyze:

• Complete transcript - The full conversation between assistant and customer
• Messages history - All messages exchanged during the call
• Tool call results - Outcomes from any tools or functions executed
• Assistant context - System prompts and configuration used during the call

Why use structured outputs?

Beyond simple data extraction:

• Call evaluation - Determine if objectives were met (appointment booked, issue resolved)
• Sentiment analysis - Understand customer satisfaction and emotional state
• CSAT scoring - Extract customer satisfaction scores from feedback
• Intelligent summaries - Generate contextual summaries of complex conversations
• Success metrics - Evaluate agent performance and call outcomes

Operational benefits:

• Automate data entry - No more manual transcription or form filling
• Ensure consistency - Every call captures the same structured information
• Enable integrations - Automatically sync data to CRMs, ticketing systems, or databases
• Improve analytics - Structured data is easier to analyze and report on

What you’ll build

A customer support assistant that automatically extracts:

• Customer name and contact details
• Issue description and priority
• Requested follow-up actions

Prerequisites

Step 1: Create your structured output

Define what information you want to extract using a JSON Schema. JSON Schema is a standard for describing data structures - learn more about JSON Schema here.

1
{
2
  "type": "object",
3
  "properties": {
4
    "customer": {
5
      "type": "object",
6
      "properties": {
7
        "name": {"type": "string", "description": "Customer full name"},
8
        "email": {"type": "string", "format": "email", "description": "Customer email"},
9
        "phone": {"type": "string", "description": "Customer phone number"}
10
      },
11
      "required": ["name"]
12
    },
13
    "issue": {
14
      "type": "object",
15
      "properties": {
16
        "description": {"type": "string", "description": "Issue description"},
17
        "category": {
18
          "type": "string",
19
          "enum": ["billing", "technical", "general", "complaint"],
20
          "description": "Issue category"
21
        },
22
        "priority": {
23
          "type": "string",
24
          "enum": ["low", "medium", "high", "urgent"],
25
          "description": "Priority level"
26
        }
27
      },
28
      "required": ["description", "category"]
29
    },
30
    "followUp": {
31
      "type": "object",
32
      "properties": {
33
        "required": {"type": "boolean", "description": "Whether follow-up is needed"},
34
        "method": {
35
          "type": "string",
36
          "enum": ["email", "phone", "none"],
37
          "description": "Preferred follow-up method"
38
        },
39
        "notes": {"type": "string", "description": "Additional notes for follow-up"}
40
      }
41
    }
42
  },
43
  "required": ["customer", "issue"]
44
}

Step 2: Create and test a call

Now test your structured output by making a call.

Step 3: Retrieve extracted data

After the call ends, retrieve the extracted information:

1
{
2
  "550e8400-e29b-41d4-a716-446655440001": {
3
    "name": "Support Ticket",
4
    "result": {
5
      "customer": {
6
        "name": "John Smith",
7
        "email": "john@example.com",
8
        "phone": "+1234567890"
9
      },
10
      "issue": {
11
        "description": "Unable to login to account, receiving error message",
12
        "category": "technical",
13
        "priority": "urgent"
14
      },
15
      "followUp": {
16
        "required": true,
17
        "method": "email",
18
        "notes": "Customer needs immediate assistance with login issue"
19
      }
20
    }
21
  }
22
}

Expected output

The extracted data (the result field from the API response) will look like this:

1
{
2
  "customer": {
3
    "name": "John Smith",
4
    "email": "john@example.com",
5
    "phone": "+1234567890"
6
  },
7
  "issue": {
8
    "description": "Unable to login to account, receiving error message",
9
    "category": "technical",
10
    "priority": "urgent"
11
  },
12
  "followUp": {
13
    "required": true,
14
    "method": "email",
15
    "notes": "Customer needs immediate assistance with login issue"
16
  }
17
}

HIPAA Compliance & Storage Settings

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.

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

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.

Next steps

Common patterns

Multiple extractions

You can attach multiple structured outputs to extract different types of data:

1
{
2
  artifactPlan: {
3
    structuredOutputIds: [
4
      "550e8400-e29b-41d4-a716-446655440001",    // Customer details extraction
5
      "550e8400-e29b-41d4-a716-446655440002",    // Appointment requests extraction  
6
      "550e8400-e29b-41d4-a716-446655440003"     // Satisfaction feedback extraction
7
    ]
8
  }
9
}

Example: Intelligent analysis with multiple outputs

Structured outputs can perform sophisticated analysis beyond simple data extraction. Here’s a real example showing various types of intelligent evaluation:

1
{
2
  "2ca00f20-f2c3-4d74-af2e-52842be5885c": {
3
    "name": "informationOnFileIsCorrect",
4
    "result": false
5
  },
6
  "4748e1aa-6c7a-49e6-bbde-c4365ef69c6e": {
7
    "name": "Appointment Rescheduled",
8
    "result": false
9
  },
10
  "4d4bac33-2cea-43d4-a3b3-4554932b8933": {
11
    "name": "CSAT",
12
    "result": 8
13
  },
14
  "7898e478-c8dc-4ff8-a3f6-4a46555a957f": {
15
    "name": "Appointment Booked",
16
    "result": true
17
  },
18
  "a0ca58b1-c343-4628-b088-bf53aabacab9": {
19
    "name": "Call Summary",
20
    "result": "The user called to schedule a consultation appointment for next week, specifically on Wednesday afternoon..."
21
  },
22
  "b5a390d8-87c5-4015-b1ad-ed237201bdf0": {
23
    "name": "Success Evaluation - Pass/Fail",
24
    "result": true
25
  }
26
}

This example demonstrates intelligent extraction capabilities:

• Call outcome evaluation: Appointment Booked (true) - Analyzed if the call’s objective was achieved
• Data verification: informationOnFileIsCorrect (false) - Evaluated if customer data needed updates
• Success metrics: Success Evaluation - Pass/Fail (true) - Determined overall call success based on multiple criteria
• CSAT extraction: CSAT (8) - Extracted satisfaction score from customer feedback
• Intelligent summarization: Call Summary - Generated contextual summary of the conversation
• Process tracking: Appointment Rescheduled (false) - Tracked specific actions taken during the call

Each output analyzes the complete call context including transcript, tool results, and metadata to provide actionable insights.

Validation patterns

Common validation patterns for reliable extraction:

1
{
2
  "email": {
3
    "type": "string",
4
    "format": "email",
5
    "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
6
  },
7
  "phone": {
8
    "type": "string",
9
    "pattern": "^\\+?[1-9]\\d{1,14}$"
10
  },
11
  "zipCode": {
12
    "type": "string",
13
    "pattern": "^\\d{5}(-\\d{4})?$"
14
  }
15
}

Tips for success

Troubleshooting

Get help

Need assistance? We’re here to help:

• API Documentation
• Discord Community
• Support