# Data extraction

Set `dataExtractionSchema` on an Assistant to extract structured data after each conversation. The platform stores the result in the Exchange's `data` field.

## Overview

After the call ends, an extraction LLM analyses its messages and events during finalization. It attempts to produce a data object matching the configured schema.

The feature involves two entities:

| Entity    | Role                                                                             |
| --------- | -------------------------------------------------------------------------------- |
| Assistant | Holds the `dataExtractionSchema` that defines what data to extract.              |
| Exchange  | Stores the extracted output in its `data` field once the conversation completes. |

Extraction is enabled when `dataExtractionSchema` is set. When the field is `null` or absent, no extraction occurs.

***

## Data model

### The `dataExtractionSchema` field

The `dataExtractionSchema` field on the Assistant accepts a JSON Schema object that follows OpenAI's structured output format.

When set, the schema is checked at save time for valid JSON Schema and a subset of OpenAI's structured output constraints (see [Extraction Schema Reference](/docs/extraction-schema) for the constraints and common supported patterns).

**Example:**

```json
{
  "type": "object",
  "properties": {
    "motive": {
      "type": "string",
      "description": "The main reason why the user is calling.",
      "enum": ["Technical Support", "FAQ", "Appointment request"]
    },
    "issueResolved": {
      "type": "boolean",
      "description": "Whether the customer's issue was resolved during the call."
    }
  },
  "required": ["motive", "issueResolved"],
  "additionalProperties": false
}
```

### The `data` field

The Exchange's `data` field holds the output matching the schema used for extraction.

**Example Exchange response excerpt:**

```json
{
  "id": "e47f2c91-8b3a-4d5e-a012-7c6d9e8f1a2b",
  "assistantId": "a130b57c-d6d7-4a18-9111-219e3192a478",
  "status": "completed",
  "type": "voice",
  "data": {
    "motive": "Technical Support",
    "issueResolved": true
  }
}
```

***

## Workflow

### Step 1: define the extraction schema

Configure your Assistant with a `dataExtractionSchema`. You can set it when creating a new Assistant or by updating an existing one.

```http
PATCH /data_next/conversational/assistants/a130b57c-d6d7-4a18-9111-219e3192a478
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "dataExtractionSchema": {
    "type": "object",
    "properties": {
      "motive": {
        "type": "string",
        "description": "The main reason why the user is calling.",
        "enum": ["Technical Support", "FAQ", "Appointment request"]
      },
      "product": {
        "type": "string",
        "description": "The product or service the conversation relates to."
      },
      "issueResolved": {
        "type": "boolean",
        "description": "Whether the customer's issue was resolved during the call."
      }
    },
    "required": ["motive", "product", "issueResolved"],
    "additionalProperties": false
  }
}
```

**Response:**

```json
{
  "id": "a130b57c-d6d7-4a18-9111-219e3192a478",
  "name": "Customer Support Agent",
  "description": "A helpful assistant for customer inquiries",
  "instructions": "You are a helpful customer support agent. Be polite, concise, and solution-oriented.",
  "language": "en-US",
  "firstMessage": "Hello! How can I help you today?",
  "timezone": "Europe/Paris",
  "temperature": 0.3,
  "dataExtractionSchema": {
    "type": "object",
    "properties": {
      "motive": {
        "type": "string",
        "description": "The main reason why the user is calling.",
        "enum": ["Technical Support", "FAQ", "Appointment request"]
      },
      "product": {
        "type": "string",
        "description": "The product or service the conversation relates to."
      },
      "issueResolved": {
        "type": "boolean",
        "description": "Whether the customer's issue was resolved during the call."
      }
    },
    "required": ["motive", "product", "issueResolved"],
    "additionalProperties": false
  },
  "projectId": "d75cda49-4bf1-4a11-9a0e-cf0ab0fef66a",
  "organizationId": "82ff5ba7-a279-413e-856d-52e2db6cc70a",
  "createdAt": "2025-12-18T14:09:14.506Z",
  "updatedAt": "2025-12-20T09:32:01.112Z"
}
```

:::info{title="Note"}

If the schema is invalid, the API returns a `400` error with code `INVALID_JSON_SCHEMA` and a list of specific validation errors. See [Extraction Schema Reference](/docs/extraction-schema) for the full set of constraints.

:::

### Step 2: conduct a conversation

Run a conversation with the configured Assistant. Extraction starts automatically during finalization after the call ends. No additional API call is needed.

### Step 3: retrieve extracted data

After the Exchange reaches `status: "completed"`, query it and read the `data` field.

```http
GET /data_next/conversational/exchanges/e47f2c91-8b3a-4d5e-a012-7c6d9e8f1a2b
Authorization: Bearer <your-api-key>
```

**Response:**

```json
{
  "id": "e47f2c91-8b3a-4d5e-a012-7c6d9e8f1a2b",
  "assistantId": "a130b57c-d6d7-4a18-9111-219e3192a478",
  "traceId": "f82a1b3c-9d4e-5f6a-b7c8-d9e0f1a2b3c4",
  "audioUrl": "https://recordings.reecall.io/e47f2c91-8b3a-4d5e-a012-7c6d9e8f1a2b",
  "duration": 73,
  "status": "completed",
  "type": "voice",
  "messages": [
    {
      "message": "Hello! How can I help you today?",
      "from": "assistant",
      "time": "2025-12-20T10:00:00",
      "metadata": {}
    },
    {
      "message": "Hi, I'm having trouble with my internet connection.",
      "from": "user",
      "time": "2025-12-20T10:00:10",
      "metadata": {}
    },
    {
      "message": "I'm sorry to hear that. Let me help you troubleshoot the issue.",
      "from": "assistant",
      "time": "2025-12-20T10:00:20",
      "metadata": {}
    },
    {
      "message": "Thanks, that fixed it!",
      "from": "user",
      "time": "2025-12-20T10:00:30",
      "metadata": {}
    },
    {
      "message": "Glad I could help. Is there anything else I can assist you with?",
      "from": "assistant",
      "time": "2025-12-20T10:00:40",
      "metadata": {}
    },
    {
      "message": "No, that's all. Thank you!",
      "from": "user",
      "time": "2025-12-20T10:00:50",
      "metadata": {}
    }
  ],
  "events": [
    {
      "type": "session_start",
      "time": "2025-12-20T10:00:00",
      "data": {}
    },
    {
      "type": "session_end",
      "time": "2025-12-20T10:01:13",
      "data": {
        "durationSeconds": 73,
        "messageCount": {
          "user": 3,
          "assistant": 3,
          "total": 6
        },
        "eventCount": 1,
        "audioUrl": "https://recordings.reecall.io/e47f2c91-8b3a-4d5e-a012-7c6d9e8f1a2b"
      }
    }
  ],
  "resources": [],
  "data": {
    "motive": "Technical Support",
    "product": "Internet connection",
    "issueResolved": true
  },
  "projectId": "d75cda49-4bf1-4a11-9a0e-cf0ab0fef66a",
  "organizationId": "82ff5ba7-a279-413e-856d-52e2db6cc70a",
  "createdAt": "2025-12-20T10:00:00.000Z",
  "updatedAt": "2025-12-20T10:01:15.000Z"
}
```

The `data` field contains the structured extraction result. It can be `null` if no schema is configured or extraction fails. If a call transfers between Assistants, extraction uses the final Assistant's schema when present, otherwise the initial Assistant's schema.

## What's next

- [Extraction Schema Reference](/docs/extraction-schema)
- [Best practices & Use cases](/docs/best-practices-and-use-cases)
