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
}

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