Ingestion API

Overview

The Ingestion API is how you get conversation data into Heard programmatically. Use it when you’re building a custom integration that isn’t covered by Heard’s built-in integrations.

---

Submit Audio

POST /api/v1/ingest/audio

Submit an audio file for transcription and analysis.

Request

curl -X POST https://api.heard.ai/v1/ingest/audio \
  -H "X-API-Key: sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://storage.example.com/call-recording.wav",
    "metadata": {
      "source": "custom-pbx",
      "caller_phone": "+15550123",
      "agent_name": "Sarah Chen",
      "recorded_at": "2026-03-11T14:30:00Z"
    }
  }'

Parameter	Type	Required	Description
audio_url	string	✅	Public URL to the audio file
audio_file	binary	✅*	Or upload the file directly (multipart/form-data)
metadata.source	string		Label for the ingestion source
metadata.caller_phone	string		Phone number for identity resolution
metadata.agent_name	string		Name of the agent/representative on the call
metadata.recorded_at	string		ISO 8601 timestamp of the recording

*One of audio_url or audio_file is required.

Supported Formats

.wav, .mp3, .flac, .m4a, .webm, .ogg

Response

{
  "job_id": "job_abc123",
  "status": "processing",
  "estimated_duration_seconds": 45
}

---

Submit Transcript

POST /api/v1/ingest/transcript

Submit a text transcript directly (skip transcription).

Request

curl -X POST https://api.heard.ai/v1/ingest/transcript \
  -H "X-API-Key: sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "transcript_text": "Agent: Hi, how can I help you today?\nCustomer: I have a billing question...",
    "metadata": {
      "source": "zendesk-chat",
      "customer_email": "mike@acme.com",
      "channel": "chat"
    }
  }'

Parameter	Type	Required	Description
transcript_text	string	✅	The conversation transcript
metadata.source	string		Label for the ingestion source
metadata.customer_email	string		Email for identity resolution
metadata.customer_phone	string		Phone for identity resolution
metadata.channel	string		voice, email, chat, or meeting

Response

{
  "job_id": "job_def456",
  "status": "processing",
  "estimated_duration_seconds": 10
}

---

Error Handling

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid audio format. Supported: wav, mp3, flac, m4a, webm, ogg",
    "details": { "field": "audio_url" }
  }
}

Code	Meaning
VALIDATION_ERROR	Invalid input (bad format, missing field)
AUTH_ERROR	Invalid or expired API key
RATE_LIMITED	Too many requests
FILE_TOO_LARGE	Audio exceeds max size (500 MB)
UNSUPPORTED_FORMAT	Audio format not recognized