Core Objects

Heify is built around four core objects. Understanding their structure is essential for working with the API effectively.

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
`extraction_fields`	`array<object>`	No	Structured data fields to extract via AI (max 10)
`summary`	`boolean`	No	Generate an AI summary (default: `false`)
`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
`created_at`	`string`	Auto-generated	ISO 8601 creation timestamp

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"`)
`type`	`string`	Yes	Data type: `string`, `number`, `boolean`, `array`
`description`	`string`	Yes	Instructions for the AI — the more specific, the more accurate

Define a bounded set of possible values in the description for consistent results. For example: “Classify the sentiment. Must be one of: POSITIVE, NEGATIVE, NEUTRAL.”

Webhooks

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

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,
  "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"
}

Evaluator

An Evaluator is a quality-scoring template made up of criteria. When attached to a transcription, the AI evaluates the conversation against each criterion and produces a score. Evaluators are optional — use them when you need automated quality assurance.

Fields

Field	Type	Required	Description
`evaluator_id`	`string`	Auto-generated	Unique identifier (UUID)
`client_id`	`string`	Auto-assigned	Your account identifier
`tag`	`string`	Yes	Name of the evaluator (not updatable after creation)
`description`	`string`	No	Description of the evaluator’s purpose
`language`	`string`	No	Language used for evaluation (`"df"` = auto-detect)
`context`	`any`	No	Additional context to guide the AI evaluation
`criteria`	`array<object>`	Yes	List of evaluation criteria (min 1, max 10)
`created_at`	`string`	Auto-generated	ISO 8601 creation timestamp
`updated_at`	`string`	Auto-updated	ISO 8601 last-modified timestamp

Criteria

Each criterion defines one aspect of the evaluation.

Field	Type	Description
`id`	`string`	Criterion UUID (auto-generated)
`name`	`string`	Name of the criterion
`description`	`string`	Instructions for the AI to evaluate this criterion
`type`	`string`	`boolean`, `scale`, or `strict` (see below)
`weight`	`number`	Percentage contribution to the total score (ignored for `strict`)

Criterion types:

boolean — Pass/fail. If the criterion passes, its weight is added to the total score.
scale — Scored 1–5 (1 = Poor, 5 = Excellent). Contributes (value / 5) × weight to the score. Fails if the result is below 3.
strict — Critical criterion. If it fails, critical_fail_triggered is set to true on the result, regardless of the overall score. The weight is always forced to 0.

Example

{
  "evaluator_id": "b2c3d4e5-f6a7-8901-2345-678901bcdef0",
  "client_id": "client-uuid",
  "tag": "Customer Service Standard",
  "description": "Evaluates call quality for the support team.",
  "language": "en",
  "context": "Inbound customer support calls for a SaaS product.",
  "criteria": [
    {
      "id": "c1d2e3f4-...",
      "name": "Greeting",
      "description": "Did the agent greet the customer with the standard opening phrase?",
      "type": "BOOLEAN",
      "weight": 20
    },
    {
      "id": "d2e3f4g5-...",
      "name": "No offensive language",
      "description": "Did the agent use any rude or inappropriate language?",
      "type": "STRICT",
      "weight": 0
    },
    {
      "id": "e3f4g5h6-...",
      "name": "Issue resolved",
      "description": "Was the customer's issue fully resolved by the end of the call?",
      "type": "BOOLEAN",
      "weight": 80
    }
  ],
  "created_at": "2025-01-15T10:00:00.000000",
  "updated_at": "2025-01-15T10:00:00.000000"
}

Participant

A Participant represents an individual whose performance is tracked across transcriptions — a support agent, job candidate being interviewed, salesperson, or any person. Participants are optional — use them when you need per-person analytics.

Fields

Field	Type	Required	Description
`participant_id`	`string`	Auto-generated	Unique identifier (UUID)
`client_id`	`string`	Auto-assigned	Your account identifier
`tag`	`string`	Yes	Name or identifier of the participant (e.g. agent name, candidate name, employee ID)
`metadata`	`object`	No	Free-form key-value pairs for any additional data
`created_at`	`string`	Auto-generated	ISO 8601 creation timestamp
`updated_at`	`string`	Auto-updated	ISO 8601 last-modified timestamp

When updating metadata, the new object fully replaces the previous one (PUT semantics). To update a single field without losing the rest, fetch the participant first, modify the object locally, and send the complete updated metadata.

Example

{
  "participant_id": "c3d4e5f6-a7b8-9012-3456-789012cdef01",
  "client_id": "client-uuid",
  "tag": "Sarah Johnson",
  "metadata": {
    "email": "sarah.johnson@example.com",
    "role": "Senior Support Agent",
    "department": "Customer Success",
    "employee_id": "EMP-0042"
  },
  "created_at": "2025-01-15T10:00:00.000000",
  "updated_at": "2025-01-15T10:00:00.000000"
}

Transcription

A Transcription represents a single audio or video processing job. Its structure evolves as the job moves through its lifecycle.

Fields

Field	Type	Description
`transcription_id`	`string`	Unique identifier (UUID)
`status`	`string`	Current status: `PENDING`, `IN_PROGRESS`, `COMPLETED`, `FAILED`
`configuration_id`	`string`	ID of the configuration used
`configuration_tag`	`string`	Tag of the configuration used
`evaluator_id`	`string`	ID of the evaluator used (if any)
`participant_id`	`string`	ID of the participant associated (if any)
`name`	`string`	Custom name (`null` if not set)
`group`	`string`	Review group (`null` if not set)
`duration`	`number`	Duration in seconds
`details`	`object`	Full results — only present when `COMPLETED`
`error`	`object`	Error details — only present when `FAILED`

Status Lifecycle

PENDING

The job is queued and waiting to start.

IN_PROGRESS

The audio is being transcribed and analyzed.

COMPLETED

Processing finished. The details object contains all results.

FAILED

Processing failed. The error object explains why.

Groups

Use group to manage the review workflow for each transcription.

Value	Description
`PENDING_REVIEW`	Needs manual review
`UNDER_REVIEW`	Currently being reviewed
`ARCHIVED`	Completed and archived
`null`	No group assigned

Details Object (when COMPLETED)

Field	Type	Description
`language`	`string`	Detected language
`num_speakers`	`number`	Number of unique speakers identified
`created_at`	`string`	ISO 8601 — when processing started
`completed_at`	`string`	ISO 8601 — when processing finished
`conversation`	`object`	Full transcript with speaker-separated segments
`summary`	`object`	AI-generated summary (if enabled in the configuration)
`fields`	`object`	Extracted structured data (if configured)
`evaluation`	`object`	Quality score and criterion results (if an evaluator was used)

Example

{
  "transcription_id": "f0e9d8c7-b6a5-4321-fedc-ba9876543210",
  "status": "COMPLETED",
  "configuration_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "configuration_tag": "Sales Call Analysis",
  "evaluator_id": "b2c3d4e5-f6a7-8901-2345-678901bcdef0",
  "participant_id": "c3d4e5f6-a7b8-9012-3456-789012cdef01",
  "name": "call_2025_01_15.mp3",
  "group": "UNDER_REVIEW",
  "duration": 185.4,
  "details": {
    "language": "en",
    "num_speakers": 2,
    "created_at": "2025-01-15T10:00:00.123Z",
    "completed_at": "2025-01-15T10:03:45.789Z",
    "conversation": {
      "segments": [
        { "text": "Good morning, this is Sarah from support.", "speaker": "SPEAKER_00" },
        { "text": "Hi, I have an issue with my subscription.", "speaker": "SPEAKER_01" }
      ]
    },
    "summary": {
      "summary": "A support call where the customer reported a billing issue that was resolved by the agent."
    },
    "fields": {
      "fields": [
        { "name": "sentiment", "value": "POSITIVE" },
        { "name": "next_action", "value": "Send confirmation email" }
      ]
    },
    "evaluation": {
      "score": 90,
      "critical_fail_triggered": false,
      "criteria_results": [
        { "name": "Greeting", "passed": true },
        { "name": "No offensive language", "passed": true },
        { "name": "Issue resolved", "passed": true }
      ]
    }
  }
}

Supported Languages

The following languages are supported for transcriptions, summaries (summary_language), and analytics reports (analytics_language).

Use "df" for automatic language detection. For summary_language, the summary is generated in the detected language of each individual file. For analytics_language, the report uses the majority language across all files in the configuration.

Language	ISO Code
Afrikaans	`af`
Albanian	`sq`
Arabic	`ar`
Azerbaijani	`az`
Basque	`eu`
Belarusian	`be`
Bengali	`bn`
Bosnian	`bs`
Bulgarian	`bg`
Catalan	`ca`
Chinese	`zh`
Croatian	`hr`
Czech	`cs`
Danish	`da`
Dutch	`nl`
English	`en`
Estonian	`et`
Finnish	`fi`
French	`fr`
Galician	`gl`
German	`de`
Greek	`el`
Gujarati	`gu`

Language	ISO Code
Hebrew	`he`
Hindi	`hi`
Hungarian	`hu`
Indonesian	`id`
Italian	`it`
Japanese	`ja`
Kannada	`kn`
Kazakh	`kk`
Korean	`ko`
Latvian	`lv`
Lithuanian	`lt`
Macedonian	`mk`
Malay	`ms`
Malayalam	`ml`
Marathi	`mr`
Norwegian	`no`
Persian	`fa`
Polish	`pl`
Portuguese	`pt`
Punjabi	`pa`

Language	ISO Code
Romanian	`ro`
Russian	`ru`
Serbian	`sr`
Slovak	`sk`
Slovenian	`sl`
Spanish	`es`
Swahili	`sw`
Swedish	`sv`
Tagalog	`tl`
Tamil	`ta`
Telugu	`te`
Thai	`th`
Turkish	`tr`
Ukrainian	`uk`
Urdu	`ur`
Vietnamese	`vi`
Welsh	`cy`

Getting Started

Platform

Core Objects

Configuration

Fields

Extraction Fields

Webhooks

Example

Evaluator

Fields

Criteria

Example

Participant

Fields

Example

Transcription

Fields

Status Lifecycle

Groups

Details Object (when COMPLETED)

Example

Supported Languages

Getting Started

Core Objects

Platform

​Configuration

​Fields

​Extraction Fields

​Webhooks

​Example

​Evaluator

​Fields

​Criteria

​Example

​Participant

​Fields

​Example

​Transcription

​Fields

​Status Lifecycle

​Groups

​Details Object (when COMPLETED)

​Example

​Supported Languages

Configuration

Fields

Extraction Fields

Webhooks

Example

Evaluator

Fields

Criteria

Example

Participant

Fields

Example

Transcription

Fields

Status Lifecycle

Groups

Details Object (when COMPLETED)

Example

Supported Languages