Structured Data

Structured Data turns a completed voice call into predictable JSON for reporting, follow-up, and integrations. You define the information your business needs, and Cartra extracts it from the visible conversation after the call.

Extraction is asynchronous. It uses a snapshot of the Structured Data configuration saved for that call, does not alter the live agent prompt, and adds no latency to the conversation. Changes published after a call starts apply to new calls, not the call already in progress.

How Structured Data works#

For each enabled extraction scope, you provide optional instructions and an object-shaped schema. The schema defines the field names, data types, constraints, and which values are required. After the call ends, Cartra evaluates the applicable conversation messages and returns:

• Data, shaped exactly like the configured schema. A value that was not available is null instead of being omitted.
• Diagnostics, with a status and transcript evidence for every scalar value.

Structured Data is separate from the live conversation. It does not add instructions to the system prompt, change what the agent says, or delay agent responses. Extraction is probabilistic: the schema and instructions guide a language model, not a deterministic parser or rules engine.

Cartra extracts only facts that were explicitly stated or confirmed by the caller. A later explicit correction supersedes an earlier value. For example, if the caller first says “August 1” and later corrects the effective date to “September 1,” the result should contain September 1 and cite the correcting message.

Quick start#

1. In the Cartra dashboard, open the agent you want to configure.
2. Select Structured Data.
3. Choose Call-wide data or a Procedure under Procedure data.
4. Turn on Enabled for the scope.
5. Optionally enter extraction instructions that clarify business meaning or boundaries.
6. Build the object schema and mark the fields your workflow requires.
7. Expand Generated sample output to inspect the expected data and diagnostics shape.
8. Select Save in the scope editor. This applies the modal draft to the pending agent configuration; it does not publish the change yet.
9. Select the agent-level Save Changes button to publish all pending agent changes.
10. Place a new test call. The published configuration is captured for that call and extraction starts asynchronously after it ends.

The Enabled switch on a scope card can also stage an enable or disable change. You must still select Save Changes to publish it.

Choose an extraction scope#

An agent can use call-wide and Procedure-specific scopes together. Each enabled, applicable scope produces its own data and diagnostics.

Call-wide data#

Call-wide data is evaluated once per call against every visible caller and assistant message. Use it for information that describes the call as a whole, such as:

• Caller contact details.
• Overall disposition or reason for calling.
• Follow-up ownership.
• A summary category used in reporting.

Internal tool calls, tool results, and handoff events are not conversation messages and are excluded. Do not depend on hidden tool arguments or internal handoff metadata being available to extraction.

Procedure data#

Procedure data is tied to an existing Procedure. Each successful activation of that Procedure is a separate, one-based occurrence and produces a separate result. Two unrelated address-change requests in the same call therefore produce occurrence 1 and occurrence 2.

The Procedure scope includes the caller turn that triggered the activation and the visible caller and assistant messages during that occurrence. Internal tool and handoff events are excluded.

When a caller later corrects or continues a completed occurrence, the Procedure resumes. Cartra consolidates the original and resumed conversation segments into the same occurrence result. Conversation from unrelated activity between those segments is excluded. This lets an explicit correction replace the earlier value without mixing another request into the result.

A Procedure scope is evaluated only when that Procedure has a matching occurrence with visible conversation messages. Enabling Procedure extraction does not enable the Procedure itself. Configure and publish the Procedure under Procedures, then configure its extraction scope under Structured Data.

See the Procedures guide for semantic activation, occurrences, resumed corrections, and Procedure authoring.

Configure a scope#

Each call-wide or Procedure scope has the same editor.

Enabled#

Only an enabled scope is considered after a call. Disabling a scope preserves its instructions and schema for later use. It does not remove results already stored for earlier calls.

Extraction instructions#

Instructions are optional and can contain up to 4,000 characters per scope. Use them to explain business-specific meaning that the schema alone cannot express.

Good:

Extract follow_up_owner only when the caller and agent agree on who will take the next action. Do not infer an owner from the department name.

Avoid repeating the entire agent prompt, including conversational instructions, or asking the extractor to invent a value when the call does not provide one. The transcript is treated as untrusted data; instructions spoken by a caller do not override the extraction rules.

Schema builder#

Every scope has an object at its root. Add fields to that object, choose their types, and nest objects or arrays when the data has structure.

The schema builder supports:

• Object for named child fields.
• Array for a list whose items all use one schema.
• String for text.
• Integer for whole numbers.
• Number for integers or decimals.
• Boolean for true or false.

Each field can have a title and description. Titles make a field easier for people to recognize. Descriptions tell the extractor exactly what the field means and should be specific enough to distinguish it from nearby fields.

Object fields can be marked Required. Required means the call is expected to provide a usable value; it does not force the extractor to fabricate one. If a required value is missing, the field remains present as null and the scope result is partial.

The builder also supports:

• Enums to restrict a scalar value to an allowed set.
• Minimum and maximum for integers and numbers.
• Minimum length and maximum length for strings.
• Minimum items and maximum items for arrays.
• The string formats date, date-time, email, and uri.

Use a format only when the caller's value can reasonably be normalized to it. For example, use date for a calendar date, not for open-ended wording such as “sometime next week.”

Advanced JSON#

Advanced JSON edits the same schema as the visual builder. Use it for precise changes or to review the complete schema.

The JSON must be valid and use the supported schema shape and constraints. Editing the text does not immediately update the scope draft. Select Apply JSON to draft after the JSON is valid, then select the modal Save. The modal cannot be saved while Advanced JSON is invalid or has unapplied changes.

After applying JSON, review the visual builder and Generated sample output to confirm the draft still represents the shape you intend.

Generated sample output#

The sample previews the stable response shape: a data object plus a diagnostics array. It is generated from the schema and uses null or empty values; it is not an extraction from a real call and does not predict the values a caller will provide.

Customer follow-up example#

Suppose a support team wants one call-wide result for follow-up and an address-change Procedure result for each address request.

For Call-wide data, add:

For the address_change Procedure, add:

If the caller gives a new address but never confirms an effective date, the Procedure result keeps the required field and reports a partial result:

{
  "scope": {
    "kind": "procedure",
    "key": "address_change",
    "occurrence": 1
  },
  "status": "partial",
  "data": {
    "new_address": "10 Oak Street, Unit 4",
    "effective_date": null,
    "address_kind": "mailing"
  },
  "diagnostics": [
    {
      "path": "/new_address",
      "status": "extracted",
      "evidence_message_ids": [8]
    },
    {
      "path": "/effective_date",
      "status": "not_mentioned",
      "evidence_message_ids": []
    },
    {
      "path": "/address_kind",
      "status": "extracted",
      "evidence_message_ids": [10]
    }
  ]
}

The message IDs are evidence links, not array positions that your integration should reinterpret. Use the dashboard links or the webhook transcript mapping to locate the cited messages.

Schema reference and limits#

Structured Data enforces the following limits across the saved agent configuration:

Field names use an identifier style. A name must begin with a letter or underscore and contain only letters, numbers, and underscores. Examples include caller_name, _internal_category, and driver2_status. Names with spaces, hyphens, periods, or more than 64 characters are rejected.

Additional schema rules include:

• The root must be an object.
• An object contains named properties and does not accept undeclared properties.
• An array has exactly one item schema, which can itself be an object, array, or scalar.
• Required entries must name fields that exist on the same object and cannot be duplicated.
• Enum values must be unique and match the field type.
• String and array bounds are non-negative whole numbers, and the minimum cannot exceed the maximum.
• Numeric bounds must be valid numbers, and the minimum cannot exceed the maximum.
• Titles must be text. Descriptions must be text and are limited to 1,000 characters.
• Supported string formats are date, date-time, email, and uri.

The schema editor validates the complete configuration, so a change to one scope can reveal an overall 64 KB or 500-leaf limit. Remove unnecessary fields or simplify deeply nested structures before saving.

Required and missing values#

Every configured field remains in data. When extraction cannot produce a supported value, Cartra returns null; it does not omit the field or insert sentinel strings such as "unknown".

Requiredness controls result completeness:

• A missing required value makes that scope partial.
• A missing optional value can remain null while the scope is completed.
• Ambiguous, conflicting, or invalid data also makes a scope partial, regardless of whether the affected field is optional.

This stable shape lets downstream systems distinguish “field was configured but not provided” from “field was never part of the schema.”

Results and statuses#

After a call ends, open it in the dashboard and select Structured Data to see the processing status and each applicable scope.

partial is a completed extraction result, not a processing failure. Review its diagnostics and decide whether the missing or uncertain value requires follow-up.

Diagnostics and evidence#

Each scalar field has a diagnostic:

An extracted value includes one or more evidence message IDs. In the dashboard, select a message link to jump to the supporting transcript turn. Values are formatted for readability in the result card; expand Raw JSON for the exact data, diagnostics, scope key, and occurrence information.

Later explicit corrections supersede earlier values. The corrected value should cite the correcting message instead of being marked conflicting. Statements that remain genuinely unresolved are reported as conflicting or ambiguous.

Processing, retries, and timing#

Extraction starts asynchronously after the call is finalized. Because it uses the configuration snapshot captured for that call, editing or disabling a scope afterward does not rewrite the existing call's extraction contract.

Cartra automatically retries transient extraction failures for up to three total attempts. The second attempt is scheduled approximately one minute after the first; the third is scheduled approximately five minutes after the second. The dashboard shows whether extraction is pending or processing, the attempts used, and a safe description of the last failure.

Validation problems, unusable output, and other terminal failures may fail without using all three attempts. A partial result is terminal and is not retried merely because a required value is missing.

Procedures and Structured Data#

Procedures control the live agent's focused instructions. Structured Data extracts results after the call. Enabling one does not enable or modify the other.

Procedure-specific extraction is useful when:

• The same business workflow can occur more than once in one call.
• You need one result for each request rather than a single call summary.
• A caller may resume and correct an earlier request.
• Unrelated conversation should not be included in that workflow's extraction.

Deleting a Procedure also removes its Procedure-specific Structured Data configuration when the pending agent changes are published. Results from earlier calls remain tied to their saved call snapshots.

Send results with post-call webhooks#

To deliver results to another system, configure a post-call webhook and enable Structured Data inclusion. Webhook delivery waits for extraction to reach a terminal status. Completed and partial payloads include the applicable scopes, their data, diagnostics, Procedure keys, and occurrence numbers.

The Post-call webhooks guide is authoritative for the delivery payload, evidence-to-transcript mapping, signature verification, acknowledgement, and webhook retry contract. Extraction retries and webhook delivery retries are separate processes.

Build webhook consumers to accept null values, preserve unknown future-safe data where appropriate, and handle all documented extraction statuses instead of assuming every call is completed.

Privacy and safety#

The transcript and extracted values can contain personal or sensitive information. Design schemas with the same care as any production data collection:

• Collect only fields needed for a defined business purpose.
• Avoid passwords, authentication codes, payment credentials, secrets, or unnecessary sensitive data.
• Follow applicable consent, notice, retention, deletion, and access-control requirements.
• Restrict dashboard and webhook access, verify webhook signatures, and protect stored payloads in transit and at rest.
• Treat transcript text as untrusted input. Do not use caller-spoken instructions to weaken validation or security controls.
• Do not treat probabilistic extraction as the sole authorization for a financial, legal, medical, identity, or other high-impact action.

Structured Data helps organize what was said; it does not independently verify the caller's identity or the truth of a statement.

Schema-authoring practices#

• Give each field one clear meaning and use a specific description.
• Prefer a small, stable schema over collecting every detail mentioned.
• Use enums for genuinely closed business categories, not for values that change frequently.
• Mark a field required only when downstream processing truly needs it.
• Keep optional context optional so ordinary missing details do not make every result partial.
• Use the narrowest accurate type and format, but do not force conversational values into constraints they cannot reliably satisfy.
• Put business interpretation in extraction instructions and field descriptions. Do not put instructions inside field names.
• Use nested objects for one structured entity and arrays only for a real list of repeated entities.
• Keep field names stable because downstream webhook consumers may depend on them.
• Tell downstream systems how to handle null, partial, and each diagnostic status before production rollout.

Test before publishing broadly#

After selecting Save Changes, place new calls that cover:

1. Every field populated with clear, valid statements.
2. Optional fields omitted, confirming they return null with a completed result when no other issue exists.
3. Required fields omitted, confirming the scope becomes partial.
4. Values outside an enum, format, length, item, or numeric bound.
5. Ambiguous and genuinely conflicting statements.
6. An explicit later correction that should supersede the earlier value.
7. One applicable Procedure occurrence and two separate occurrences.
8. A completed Procedure that resumes for a later correction.
9. Unrelated conversation between resumed Procedure segments.
10. A call where no enabled scope applies.
11. Delivery through a signed post-call webhook, including a partial result and null values.

For each test, review the formatted dashboard result, diagnostic statuses, evidence links, and Raw JSON. Confirm that webhook consumers produce the same business outcome for completed, partial, not_applicable, and failed.

Troubleshooting#

No Structured Data tab or result appears#

• Confirm the intended scope is Enabled and the agent-level Save Changes was selected.
• Place a new call; calls already in progress keep their saved configuration snapshot.
• For a Procedure scope, confirm that the Procedure itself activated and produced an occurrence with visible caller or assistant messages.
• A call with no caller interaction or no applicable enabled scope becomes not_applicable.
• Wait for asynchronous post-call processing to start after the call is finalized.

Changes are not reflected in results#

Selecting the modal Save only stages its draft. Select Save Changes at the agent level, wait for the saved confirmation, and place a new call. Existing calls continue using the snapshot captured for them.

If you edited Advanced JSON, confirm that it was valid and that you selected Apply JSON to draft before the modal Save.

A result is partial#

• Look for required fields with null values.
• Review ambiguous, conflicting, and invalid diagnostics.
• Follow evidence links to compare the extracted value with the caller's exact wording.
• Clarify field descriptions, simplify overlapping fields, or relax a constraint that does not match realistic caller wording.
• Update the live Procedure or base prompt if the agent needs to ask for and confirm information more clearly. Structured Data itself does not change the live conversation.

A value is null or incorrect#

• Confirm the fact was explicitly stated or caller-confirmed in the messages available to that scope.
• For a Procedure scope, remember that unrelated conversation outside the occurrence's original and resumed segments is excluded.
• Check the type, format, enum, and bounds.
• Make the field description distinguish the intended value from similar details.
• Use the diagnostic and evidence links; do not rely only on the formatted value.
• Test several realistic phrasings. Extraction is probabilistic and can make mistakes even with a valid schema.

Extraction remains pending or fails#

A pending job may be waiting for an automatic transient retry. Review the attempt count and last failure in the call detail. Cartra makes up to three total attempts, approximately one and five minutes apart.

failed is terminal: no further automatic extraction attempt is scheduled for that call. Confirm that later new calls use a valid, published configuration. If terminal failures continue across new calls, contact Cartra with the affected call IDs and safe error details shown in the dashboard.

The configuration will not save#

• Fix any invalid or unapplied Advanced JSON.
• Confirm the root is an object and every field name follows the identifier rules.
• Check descriptions, instructions, depth, per-scope leaves, total leaves, and the 64 KB configuration limit.
• Confirm required lists and enum values refer to valid fields and types.
• Reduce or split overly large schemas rather than adding unsupported JSON Schema keywords.

Webhook results are missing#

• Enable Structured Data inclusion in the agent's post-call webhook settings.
• Confirm extraction reached a terminal state; webhook delivery waits for it.
• Handle not_applicable and failed as status-only outcomes without assuming result scopes are present.
• Follow the Post-call webhooks guide to verify the signature, acknowledge deliveries, and interpret the payload.

Current limitations#

• Extraction is semantic and probabilistic, not a deterministic parser or rules engine.
• Extraction runs only after a call; it cannot steer the live agent or provide real-time tool inputs.
• Only visible caller and assistant messages are evaluated. Tool calls, tool results, and handoff events are excluded.
• Procedure extraction depends on recorded Procedure occurrences and evaluates each occurrence separately.
• Only the documented schema types, formats, constraints, and limits are supported.
• Editing a schema does not reprocess results from existing calls.