Results & schemas

Schema, result, and evidence

Current behavior

After a call finishes, Cleo prepares a summary and attempts to extract the requested fields from available conversation evidence. Published values must match the submitted schema and pass recipient-evidence and protected-value checks. Provider diagnostics are not substituted for your requested result.

result_extraction.status distinguishes pending processing, complete results, incomplete information, unavailable processing, and invalid candidates. A schema-valid result can still be incomplete when nullable fields are unknown. Missing fields use JSON Pointer paths such as /saturday_hours. Evidence entries contain a field path, recipient transcript sequence, and supporting quote.

Choose a schema

Define the business answers you need. Use nullable types for information the recipient may not provide, and distinguish a missing answer from an explicit negative response. For example:

{
  "type": "object",
  "properties": {
    "saturday_hours": {
      "type": [
        "string",
        "null"
      ]
    },
    "basic_tune_up_price": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "saturday_hours",
    "basic_tune_up_price"
  ],
  "additionalProperties": false
}

The extractor also supports scalar and array result roots. An unconstrained object schema accepts an empty object and does not establish that useful answers were collected. Preserve the original schema when retrying an uncertain submission.

Interpret the response

result_schema_valid: true means the published value passed schema validation and publication checks. It does not prove factual accuracy, that quoted words establish every interpretation, or that the recipient carried out a booking or cancellation. Compare the summary, evidence, missing fields, and your success criteria.

Call completion and result preparation are separate. Stop active-call polling at a terminal call state. If extraction is still pending, make bounded later reads or syncs of that same call; do not create another call to obtain a result. Explicit sync can retry failed extraction without redialing. Summary preparation can be unavailable; terminal responses then include captured speaker-labeled transcript turns when available.