# Best practices & use cases

Choose the fields you need, describe how to extract them, and test the results on representative conversations. Use the schemas below as starting points for your Assistant's `dataExtractionSchema`.

## Design focused schemas

* Extract only the data points you actually need. A smaller, well-scoped schema is easier to test and refine than a broad one.
* Prefer flat structures over deeply nested objects when the data allows it.
* Each additional field gives you another extraction result to validate. If a field is "nice to have" rather than essential, leave it out.

**Prefer this:**

```json
{
  "type": "object",
  "properties": {
    "motive": { "type": "string" },
    "product": { "type": "string" },
    "issueResolved": { "type": "boolean" }
  },
  "required": ["motive", "product", "issueResolved"],
  "additionalProperties": false
}
```

**Over this:**

```json
{
  "type": "object",
  "properties": {
    "motive": { "type": "string" },
    "product": { "type": "string" },
    "issueResolved": { "type": "boolean" },
    "sentiment": { "type": "string" },
    "language": { "type": "string" },
    "summary": { "type": "string" },
    "keywords": { "type": "array", "items": { "type": "string" } },
    "followUpNeeded": { "type": "boolean" },
    "department": { "type": "string" },
    "priority": { "type": "string" }
  },
  "required": ["motive", "product", "issueResolved", "sentiment", "language", "summary", "keywords", "followUpNeeded", "department", "priority"],
  "additionalProperties": false
}
```

***

## Guide the LLM with descriptions

* Always include a `description` field on each property. The LLM uses these descriptions to understand what to extract and from which parts of the conversation.
* Describe the information to extract. For example, use "The main reason why the user is calling" for `motive`.
* Be specific about edge cases in the description. For instance, specify what value to use when the caller does not mention a product.

**Example:**

```json
{
  "type": "object",
  "properties": {
    "motive": {
      "type": "string",
      "description": "The main reason why the user is calling."
    },
    "product": {
      "type": "string",
      "description": "The product or service the conversation relates to, as mentioned by the caller."
    }
  },
  "required": ["motive", "product"],
  "additionalProperties": false
}
```

***

## Use enums for categorisation

The example below is a `properties` fragment to place inside an object schema.

* When a field has a known set of possible values, define them as an `enum`. This constrains the LLM output to your predefined categories, making downstream processing predictable.
* Keep enum values concise and mutually exclusive.
* If the list of possible values is open-ended, use a free-text `string` instead of trying to enumerate every possibility.

**Example:**

```json
{
  "motive": {
    "type": "string",
    "description": "The main reason why the user is calling.",
    "enum": ["Technical Support", "Billing", "Appointment request", "General enquiry"]
  },
  "urgency": {
    "type": "string",
    "description": "How urgent the caller's request is, based on the tone and content of the conversation.",
    "enum": ["low", "medium", "high"]
  }
}
```

***

## Handle optional data with nullable fields

The example below is a `properties` fragment to place inside an object schema.

* Use nullable types such as `["string", "null"]` for fields that may not be mentioned in the conversation.
* Include guidance in the `description` about when `null` is the appropriate value. This helps the LLM distinguish between "the caller did not mention it" and "the caller said something ambiguous".

**Example:**

```json
{
  "referralSource": {
    "type": ["string", "null"],
    "description": "How the caller heard about the service, or null if not mentioned during the conversation."
  }
}
```

See [Nullable Fields](/docs/extraction-schema#nullable-fields) in the schema reference for the full syntax.

***

## Iterate and test

* Test your schema against real conversations before deploying to production. Review the extracted `data` on several Exchange records to verify the LLM is interpreting your descriptions correctly.
* If a field is consistently misclassified, refine its `description` or narrow its `enum` values rather than adding more fields.
* Start with a minimal schema and expand incrementally. Adding one or two fields at a time makes it easier to identify which change caused a regression in accuracy.

***

## Use cases

Copy a schema, adjust its descriptions and enum values for your use case, and set it as the Assistant's `dataExtractionSchema`.

### Support line

Extract the reason for the call, the affected product, how the issue was resolved, and any follow-up commitment.

```json
{
  "type": "object",
  "properties": {
    "motive": {
      "type": "string",
      "description": "The main reason why the caller is contacting support.",
      "enum": ["Technical issue", "Billing enquiry", "Account management", "Complaint", "Other"]
    },
    "product": {
      "type": ["string", "null"],
      "description": "The product or service the issue relates to, or null if not identified during the call."
    },
    "issueResolved": {
      "type": "boolean",
      "description": "Whether the caller's issue was fully resolved during this call."
    },
    "resolutionMethod": {
      "type": ["string", "null"],
      "description": "A brief description of how the issue was resolved, or null if the issue remains open."
    },
    "followUpRequired": {
      "type": "boolean",
      "description": "Whether a follow-up action (callback, escalation, ticket) was promised to the caller."
    }
  },
  "required": ["motive", "product", "issueResolved", "resolutionMethod", "followUpRequired"],
  "additionalProperties": false
}
```

**Example output:**

```json
{
  "motive": "Technical issue",
  "product": "Fibre broadband",
  "issueResolved": true,
  "resolutionMethod": "Router restarted remotely by the agent.",
  "followUpRequired": false
}
```

### User need qualification

Capture the caller's need, their profile, and a qualification outcome to route or prioritise the lead.

```json
{
  "type": "object",
  "properties": {
    "need": {
      "type": "string",
      "description": "A concise summary of what the caller is looking for."
    },
    "category": {
      "type": "string",
      "description": "The broad category that best fits the caller's need.",
      "enum": ["Product enquiry", "Service request", "Partnership", "Pricing", "Other"]
    },
    "companyName": {
      "type": ["string", "null"],
      "description": "The name of the caller's company, or null if they are an individual or did not mention it."
    },
    "budget": {
      "type": ["string", "null"],
      "description": "The caller's stated budget or budget range, or null if not discussed.",
      "enum": ["Under 1k", "1k-10k", "10k-50k", "Over 50k", null]
    },
    "urgency": {
      "type": "string",
      "description": "How urgently the caller needs a response, inferred from the tone and content of the conversation.",
      "enum": ["low", "medium", "high"]
    },
    "qualified": {
      "type": "boolean",
      "description": "Whether the caller's need matches the services offered and warrants a follow-up."
    }
  },
  "required": ["need", "category", "companyName", "budget", "urgency", "qualified"],
  "additionalProperties": false
}
```

**Example output:**

```json
{
  "need": "Looking for an AI voice assistant to handle after-hours calls for a dental practice.",
  "category": "Product enquiry",
  "companyName": "Bright Smile Dental",
  "budget": "1k-10k",
  "urgency": "medium",
  "qualified": true
}
```

### Appointment booking

Extract the details needed to confirm or follow up on a scheduling request.

```json
{
  "type": "object",
  "properties": {
    "appointmentType": {
      "type": "string",
      "description": "The type of appointment the caller wants to book.",
      "enum": ["Initial consultation", "Follow-up", "Annual review", "Urgent visit", "Other"]
    },
    "preferredDate": {
      "type": ["string", "null"],
      "description": "The caller's preferred date for the appointment (as mentioned in the conversation), or null if no preference was stated."
    },
    "preferredTimeSlot": {
      "type": ["string", "null"],
      "description": "The caller's preferred time of day, or null if no preference was stated.",
      "enum": ["morning", "afternoon", "evening", null]
    },
    "callerName": {
      "type": ["string", "null"],
      "description": "The full name of the person the appointment is for, or null if not provided."
    },
    "contactPhone": {
      "type": ["string", "null"],
      "description": "A phone number to confirm the appointment, or null if not provided."
    },
    "bookingConfirmed": {
      "type": "boolean",
      "description": "Whether a specific date and time were agreed upon during the call."
    }
  },
  "required": ["appointmentType", "preferredDate", "preferredTimeSlot", "callerName", "contactPhone", "bookingConfirmed"],
  "additionalProperties": false
}
```

**Example output:**

```json
{
  "appointmentType": "Initial consultation",
  "preferredDate": "next Tuesday",
  "preferredTimeSlot": "morning",
  "callerName": "Sophie Martin",
  "contactPhone": "+33 6 12 34 56 78",
  "bookingConfirmed": false
}
```

### FAQ

Identify which questions were asked, whether the Assistant was able to answer them, and any remaining gaps.

```json
{
  "type": "object",
  "properties": {
    "questions": {
      "type": "array",
      "description": "The distinct questions the caller asked during the conversation.",
      "items": {
        "type": "object",
        "properties": {
          "question": {
            "type": "string",
            "description": "A concise restatement of the caller's question."
          },
          "answered": {
            "type": "boolean",
            "description": "Whether the assistant provided a satisfactory answer to this question."
          }
        },
        "required": ["question", "answered"],
        "additionalProperties": false
      }
    },
    "allQuestionsAnswered": {
      "type": "boolean",
      "description": "Whether every question raised by the caller was answered during the conversation."
    },
    "topicCategory": {
      "type": "string",
      "description": "The primary topic area of the caller's questions.",
      "enum": ["Product features", "Pricing", "Account & billing", "Technical setup", "Policies", "Other"]
    }
  },
  "required": ["questions", "topicCategory", "allQuestionsAnswered"],
  "additionalProperties": false
}
```

**Example output:**

```json
{
  "questions": [
    { "question": "What are the supported languages?", "answered": true },
    { "question": "Is there a free trial?", "answered": true },
    { "question": "Can I export call recordings?", "answered": false }
  ],
  "allQuestionsAnswered": false,
  "topicCategory": "Product features"
}
```
