Quickstart - Heify Docs

Heify turns voice recordings into structured data. You define what to extract, Heify does the rest: transcription, field extraction, AI summaries, quality scoring, and analytics — all through a pipeline you control.

How the Pipeline Works

Every transcription in Heify flows through the same building blocks:

Configuration

The template that defines how to process audio: what fields to extract, whether to summarize, which language, custom vocabulary, and webhooks.

Evaluator

An optional quality-scoring rubric. Define criteria with weights that sum to 100 — Heify scores every call against them automatically.

Participant

An optional person profile — a support agent, job candidate, salesperson, or any individual. Attach a participant to a transcription to track their performance over time.

Transcription

The result: full transcript, extracted fields, AI summary, evaluation score, and more — ready to query or export.

Only a Configuration is required. Evaluators and Participants are optional modules you can add when you need quality scoring or per-person performance tracking.

Choose Your Path

Use the Sandbox
Integrate the API

The Sandbox is Heify’s browser-based interface. No code required — create configurations, upload audio, and explore results in minutes.

Go to sandbox.heify.com and enter your email address.Heify uses passwordless authentication — no passwords to set or remember. After you submit your email:

A 6-digit OTP code is sent to your inbox
Enter the code in the Sandbox (you have 3 minutes before it expires)
You’re in — your session lasts 30 days

You can paste the full 6-digit code directly into the first field and it fills in automatically.

Configure your API key

Before you can transcribe, the Sandbox needs an API key linked to your account.Open API Keys & Sandbox from the top-left menu (or follow the yellow banner on the Dashboard). Your sandbox key auto-provisions and auto-configures — no manual steps needed. The status indicator turns green: Ready.

Your sandbox key is automatically shared across devices. Log in from any browser and it’s already configured.

Create a Configuration

A Configuration tells Heify what to do with each audio file.

Go to Configurations → Create Configuration
Give it a Tag (a name, e.g. support-calls-v1)
Toggle Automatic Summary on if you want an AI-generated executive summary per call
Add Extraction Fields to pull structured data from conversations:

Field name	Type	Description
`customer_sentiment`	string	Overall sentiment: POSITIVE, NEGATIVE, or NEUTRAL
`call_reason`	string	Main reason the customer called
`resolved`	boolean	Whether the issue was resolved during the call

(Optional) Add custom vocabulary — product names, internal terms, abbreviations — to improve transcription accuracy
Click Create Configuration

Use the Quick Actions shortcuts to add common fields (sentiment analysis, quality rating, next action) with a single click.

Transcribe your first audio

Go to Transcribe in the sidebar
Select your Configuration from the dropdown
(Optional) Select an Evaluator and/or a Participant if you have them
Choose how to submit:
- Upload file — drag & drop or click to browse (MP3, WAV, MP4, WebM, AAC, and more)
- URL — paste a public link to an audio file
Click Process

Once submitted, a link appears to open the transcription detail directly. The transcription is processed asynchronously — if you see a Processing status, wait a moment and click the Refresh button to check for updates.

Review your results

Once processing is complete (status: Completed), click the transcription to open the detail view:

Full transcript with speaker labels and timestamps
Extracted fields — the structured data you defined (e.g. resolved: true, call_reason: "billing issue")
AI Summary — if you enabled it in the configuration
Evaluation — score, pass/fail status, and per-criterion feedback (if you used an evaluator)
Export to PDF — the full report in one click

The Heify API lets you submit audio, retrieve results, and query analytics programmatically. All endpoints use POST and return a standard JSON envelope.

All requests require:

Content-Type: application/json
x-api-key: <YOUR_API_KEY> header

All responses follow this shape:

// Success
{ "data": { ... } }

// Error
{ "error": { "message": "...", "code": 400 } }

Get your API key

Click Auto-provision to create a sandbox key instantly, or
Click Add new key to create a named production key

Copy the key — you’ll use it as the x-api-key header on every request.

Create a Configuration

A Configuration is the reusable template that tells Heify what to extract from audio.

curl -X POST https://api.heify.com/create-configuration \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "tag": "support-calls-v1",
    "summary": true,
    "summary_language": "en",
    "extraction_fields": [
      {
        "name": "customer_sentiment",
        "type": "string",
        "description": "Overall sentiment of the customer: POSITIVE, NEGATIVE, or NEUTRAL"
      },
      {
        "name": "resolved",
        "type": "boolean",
        "description": "Whether the customer issue was resolved during the call"
      }
    ]
  }'

import requests

response = requests.post(
    "https://api.heify.com/create-configuration",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "YOUR_API_KEY"
    },
    json={
        "tag": "support-calls-v1",
        "summary": True,
        "summary_language": "en",
        "extraction_fields": [
            {
                "name": "customer_sentiment",
                "type": "string",
                "description": "Overall sentiment of the customer: POSITIVE, NEGATIVE, or NEUTRAL"
            },
            {
                "name": "resolved",
                "type": "boolean",
                "description": "Whether the customer issue was resolved during the call"
            }
        ]
    }
)

configuration_id = response.json()["data"]["configuration_id"]
print(f"Configuration created: {configuration_id}")

Response (201)

{
  "data": {
    "message": "Configuration created successfully",
    "configuration_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Save the configuration_id — you’ll use it every time you submit a transcription.

Submit audio for transcription

Choose the submission method that fits your use case:

From a URL
Upload a local file

If your audio is hosted online (S3, CDN, etc.), submit it directly:

curl -X POST https://api.heify.com/submit \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "configuration_id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://example.com/call-recording.mp3",
    "name": "Support call 2024-01-15"
  }'

import requests

response = requests.post(
    "https://api.heify.com/submit",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "YOUR_API_KEY"
    },
    json={
        "configuration_id": "550e8400-e29b-41d4-a716-446655440000",
        "url": "https://example.com/call-recording.mp3",
        "name": "Support call 2024-01-15"
    }
)

transcription_id = response.json()["data"]["transcription_id"]
print(f"Transcription started: {transcription_id}")

Response (201)

{
  "data": {
    "message": "Transcription created successfully",
    "transcription_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

For local files, use the two-step presigned upload:Step 1 — Request an upload URL:

curl -X POST https://api.heify.com/request-upload-url \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "configuration_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Support call 2024-01-15"
  }'

import requests

response = requests.post(
    "https://api.heify.com/request-upload-url",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "YOUR_API_KEY"
    },
    json={
        "configuration_id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Support call 2024-01-15"
    }
)

result = response.json()["data"]
upload_url = result["upload_url"]
transcription_id = result["transcription_id"]

Step 2 — Upload the file directly to S3:

curl -X PUT "UPLOAD_URL_FROM_PREVIOUS_STEP" \
  --upload-file "./call-recording.mp3"

with open("call-recording.mp3", "rb") as f:
    requests.put(upload_url, data=f)

print(f"Uploaded. Transcription ID: {transcription_id}")

The presigned URL expires in 5 minutes. Upload the file immediately after requesting the URL.

Supported formats: aac, aiff, amr, asf, flac, mp3, ogg, wav, webm, m4a, mp4

Retrieve the result

Transcription is asynchronous. Poll /get-transcription until status is COMPLETED or FAILED.

curl -X POST https://api.heify.com/get-transcription \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "transcription_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

import requests, time

def wait_for_transcription(transcription_id, api_key):
    while True:
        response = requests.post(
            "https://api.heify.com/get-transcription",
            headers={
                "Content-Type": "application/json",
                "x-api-key": api_key
            },
            json={"transcription_id": transcription_id}
        )
        result = response.json()["data"]
        status = result["status"]

        if status == "COMPLETED":
            return result
        elif status == "FAILED":
            raise Exception(result.get("error_message", "Transcription failed"))

        print(f"Status: {status} — waiting...")
        time.sleep(5)

result = wait_for_transcription(transcription_id, "YOUR_API_KEY")

A completed transcription returns:

Response (200)

{
  "data": {
    "transcription_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "COMPLETED",
    "configuration_tag": "support-calls-v1",
    "name": "Support call 2024-01-15",
    "duration": 312.4,
    "language": "en",
    "transcript": "Agent: Thank you for calling. How can I help you today? Customer: Hi, I have an issue with my invoice...",
    "summary": "The customer called regarding a billing discrepancy on their January invoice. The agent resolved the issue by applying a correction credit.",
    "extraction": {
      "customer_sentiment": "NEGATIVE",
      "resolved": true
    },
    "evaluation_score": null,
    "critical_fail_triggered": false,
    "group": null,
    "created_at": "2024-01-15T10:30:00.000000"
  }
}

Instead of polling, configure a webhook on your Configuration (webhooks.success_url) to receive a POST notification the moment processing completes.

What’s next from the API?

Add Quality Scoring

Create an Evaluator and pass evaluator_id when submitting — every transcription gets auto-scored

Track Participants

Create Participants and pass participant_id to build performance analytics per agent

Run Analytics

Call /analytics on any Configuration to analyze your full corpus with AI

Manage API Keys

Learn about key rotation, rate limits, and best practices

Success!

You’ve successfully transcribed your first audio/video file with Heify!

​How the Pipeline Works

Configuration

Evaluator

Participant

Transcription

​Choose Your Path

​What’s next from the API?

Add Quality Scoring

Track Participants

Run Analytics

Manage API Keys

​Success!

How the Pipeline Works

Choose Your Path

What’s next from the API?

Success!