Configuration

A Configuration is a reusable template that defines how audio/video files are processed. It sets the language, vocabulary, extraction fields, and optional features like summaries or webhooks. Every transcription requires a configuration.

Fields

Field	Type	Required	Description
`configuration_id`	`string`	Auto-generated	Unique identifier (UUID)
`client_id`	`string`	Auto-assigned	Your account identifier
`tag`	`string`	Yes	Descriptive name (max 255 characters)
`vocabulary`	`array<string>`	No	Custom terms to improve recognition accuracy — fully replaced when updated
`extraction_fields`	`array<object>`	No	Structured data fields to extract via AI (max 10) — see Extraction Fields
`summary`	`boolean`	No	Generate an AI summary (default: `false`)
`custom_summary`	`string`	No	Custom prompt to guide the AI summary (max 300 chars)
`summary_language`	`string`	No	Language for the summary (`"df"` = auto-detect)
`analytics_language`	`string`	No	Language for analytics reports (`"df"` = auto-detect)
`webhooks`	`object`	No	URLs to notify on completion or failure — see Webhooks
`created_at`	`string`	Auto-generated	ISO 8601 creation timestamp

tag cannot be changed after the configuration is created.

Extraction Fields

Each item in extraction_fields tells the AI what structured data to extract from the transcript.

Field	Type	Required	Description
`name`	`string`	Yes	Field identifier (e.g. `"sentiment"`, `"ticket_id"`) — 1–50 chars
`type`	`string`	Yes	Data type: `string`, `number`, `boolean`, `array`
`description`	`string`	Yes	Instructions for the AI — the more specific, the more accurate — 1–1000 chars

Field names are normalized on creation: converted to lowercase and special characters replaced with _. For example, "My Field!" becomes "my_field_".

Once a field is created, its type is immutable. Only description can be updated.

When updating extraction_fields, the submitted list uses a merge-by-name strategy: any field not included in the update is permanently removed. Always include all the fields you want to keep, even if you’re only changing one of them.

Best Practices for Extraction Fields

Use bounded responses

Define a clear, limited set of possible values to improve consistency and accuracy.

{
  "name": "sentiment",
  "type": "string",
  "description": "Classify the overall sentiment of the conversation. Must be one of: POSITIVE, NEGATIVE, or NEUTRAL."
}

This ensures the AI returns predictable, standardized values instead of open-ended descriptions.

Provide specific context

Give detailed descriptions and concrete examples to guide the AI toward more accurate results.Poor description:

{
  "name": "classification",
  "type": "string",
  "description": "Classifies the conversation"
}

Good description:

{
  "name": "issue",
  "type": "string",
  "description": "Classifies the conversation into one of: \"BILLING\", \"TECHNICAL\", \"GENERAL\". BILLING covers payment or invoice questions. TECHNICAL covers product bugs or setup issues. GENERAL covers all other topics."
}

The more context you provide, the better the extraction quality.

Provide clear, detailed descriptions for extraction fields. The more context you give, the more accurate the extraction will be.

Webhooks

Field	Type	Description
`success_url`	`string`	POST notification when the transcription completes
`error_url`	`string`	POST notification when the transcription fails

When updating a configuration, pass "webhooks": null to remove all webhook URLs.

Example

{
  "configuration_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "client_id": "client-uuid",
  "tag": "Sales Call Analysis",
  "vocabulary": ["CRM", "upsell", "churn"],
  "extraction_fields": [
    {
      "name": "sentiment",
      "type": "string",
      "description": "Overall sentiment of the conversation: POSITIVE, NEGATIVE, or NEUTRAL."
    },
    {
      "name": "next_action",
      "type": "string",
      "description": "The agreed next action with the customer, if any."
    }
  ],
  "summary": true,
  "custom_summary": "Focus on action items and next steps agreed by both parties.",
  "summary_language": "en",
  "analytics_language": "en",
  "webhooks": {
    "success_url": "https://example.com/webhooks/success",
    "error_url": "https://example.com/webhooks/error"
  },
  "created_at": "2025-01-15T10:00:00.000000+00:00"
}

Getting Started

Core Objects

Platform

Fields

Extraction Fields

Best Practices for Extraction Fields

Webhooks

Example

​Fields

​Extraction Fields

​Best Practices for Extraction Fields

​Webhooks

​Example

Fields

Extraction Fields

Best Practices for Extraction Fields

Webhooks

Example