Skip to main content
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

FieldTypeRequiredDescription
configuration_idstringAuto-generatedUnique identifier (UUID)
client_idstringAuto-assignedYour account identifier
tagstringYesDescriptive name (max 255 characters)
vocabularyarray<string>NoCustom terms to improve recognition accuracy — fully replaced when updated
extraction_fieldsarray<object>NoStructured data fields to extract via AI (max 10) — see Extraction Fields
summarybooleanNoGenerate an AI summary (default: false)
custom_summarystringNoCustom prompt to guide the AI summary (max 300 chars)
summary_languagestringNoLanguage for the summary ("df" = auto-detect)
analytics_languagestringNoLanguage for analytics reports ("df" = auto-detect)
webhooksobjectNoURLs to notify on completion or failure — see Webhooks
created_atstringAuto-generatedISO 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.
FieldTypeRequiredDescription
namestringYesField identifier (e.g. "sentiment", "ticket_id") — 1–50 chars
typestringYesData type: string, number, boolean, array
descriptionstringYesInstructions 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

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.
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

FieldTypeDescription
success_urlstringPOST notification when the transcription completes
error_urlstringPOST 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"
}