Back to HomeDeveloper API
Home/API Overview

Developer API

VOCAL API Overview

Use the VOCAL API to submit call data, retrieve analysis results, access structured signals and KPI outputs, and trigger operational workflows through webhook or export-friendly integrations.

What the API Is Used For

Ingest Calls

Submit recordings and metadata context, or connect source-driven ingestion workflows to start analysis.

Retrieve Analysis

Fetch summaries, findings, metrics, transcripts, and call-level intelligence artifacts.

Operational Automation

Drive review queues, CRM updates, alerts, and workflow actions from structured outputs.

Reporting and Export

Access structured records for BI pipelines, governance workflows, and downstream reporting systems.

Typical API Workflow

  1. 1. Authenticate and establish tenant-scoped access.
  2. 2. Submit call data plus metadata context (or trigger source-connected ingestion).
  3. 3. Platform processes transcription, analysis, and KPI mapping asynchronously.
  4. 4. Retrieve results through API resources or event-driven notification patterns.
  5. 5. Push outputs into CRM, BI, QA, or workflow automation systems.

Core API Resource Categories

Authentication

API key/JWT-based access control with tenant and role-aware constraints.

Calls

Call retrieval, processing status visibility, call detail resources, and export-oriented pathways.

Analysis Results

Findings, summaries, entities, metrics, and KPI-linked output bundles.

Transcripts

Transcript and speaker-aware conversation artifacts for review and downstream analysis.

Webhooks / Events

Inbound source callbacks and event-driven integration patterns for processing lifecycle workflows.

Exports / Downstream Access

Structured JSON/CSV retrieval patterns designed for analytics and operational systems.

Representative Examples

The payloads below are representative examples for integration design. They illustrate typical shapes and should not be treated as a fixed endpoint contract for every deployment.

Example Request (Representative)

POST /calls
{
  "call_id": "call_2026_001",
  "media_url": "https://media.example.com/recordings/call_2026_001.wav",
  "started_at": "2026-03-11T14:02:18Z",
  "source": "telephony_platform",
  "metadata": {
    "direction": "inbound",
    "agent_id": "agent_42",
    "customer_id": "cust_908",
    "campaign": "renewal_q1"
  },
  "business_context": {
    "queue": "support_tier_1",
    "priority": "standard"
  }
}

Example Response (Representative)

{
  "call_id": "call_2026_001",
  "status": "completed",
  "processed_at": "2026-03-11T14:06:41Z",
  "transcript": {
    "available": true,
    "resource": "/api/calls/call_2026_001/transcript"
  },
  "summary": "Customer requested pricing clarification and accepted follow-up.",
  "findings": [
    { "type": "objection", "category": "pricing", "confidence": 0.84 },
    { "type": "intent", "category": "follow_up_commitment", "confidence": 0.77 }
  ],
  "signals": ["pricing_objection", "buying_signal", "follow_up_required"],
  "metrics": {
    "sentiment_score": 0.62,
    "qa_score": 0.81,
    "follow_up_reliability_index": 0.74
  }
}

Example Webhook Event (Representative)

{
  "event": "analysis.completed",
  "call_id": "call_2026_001",
  "status": "completed",
  "processed_at": "2026-03-11T14:06:41Z",
  "result_resource": "/api/calls/call_2026_001"
}

API Design Principles

  • - Structured, explainable outputs over opaque model-only summaries.
  • - Asynchronous processing support for real-world audio workflows.
  • - Metadata-aware ingestion to improve downstream attribution and quality.
  • - Separation between source call artifacts and derived intelligence outputs.
  • - Export-friendly response structures for reporting and automation.
  • - Terminology and KPI alignment with dashboard and docs governance references.

Who Uses the API

  • Developers
  • RevOps and operations engineers
  • BI and analytics teams
  • QA workflow owners
  • Internal automation agents

Common Integration Patterns

  • - Telephony platform -> VOCAL -> CRM notes/tasks.
  • - VOCAL outputs -> BI pipeline and dashboard models.
  • - VOCAL findings -> QA review queue and exception workflows.
  • - VOCAL event/output states -> webhook-driven automation systems.

Implementation Notes and Caveats

  • - Processing may be asynchronous and can require polling or event-based retrieval.
  • - Transcript and signal quality depend on source audio quality and speaker conditions.
  • - Metadata completeness materially improves attribution and KPI interpretation quality.
  • - KPI interpretation should align with canonical definitions and governance notes.
  • - Example payloads on this page are representative and non-binding.

Related Pages