Calls

Trigger a single call

POST /v1/calls — Rate limit: 30/minute
Scope: voice:calls:write

Places a single outbound call immediately using a campaign's voice agent and telephony config. The contact is upserted by phone number. Returns immediately — use the call_uuid to track progress via polling or webhooks.

Request body:

{
  "to": "+918888888888",
  "campaign_id": "flw_f1g2h3",
  "contact_name": "Priya Kumar",
  "metadata": {
    "product_interest": "Standing Desk Pro",
    "cart_value": 850
  }
}

Field	Type	Required	Notes
to	string	✓	E.164 phone number
campaign_id	string	✓	UUID of the campaign to use for voice agent + telephony config
contact_name	string	—	Used to upsert/create the contact
metadata	object	—	Merged into the contact's metadata

Response:

{
  "call_uuid": "cal_c1d2e3f4",
  "status": "dialing",
  "to": "+918888888888",
  "campaign_id": "flw_f1g2h3"
}

---

List calls

GET /v1/calls
Scope: voice:calls:read

Query parameters:

Param	Type	Notes
campaign_id	string	Filter by campaign UUID
contact_id	string	Filter by contact UUID
outcome	string	connected, voicemail, no-answer, failed
sentiment	string	positive, neutral, negative
date_from / date_to	date	ISO 8601
limit	integer	Default 50, max 100
offset	integer	Default 0

Response:

{
  "calls": [
    {
      "uuid": "cal_c1d2e3f4",
      "call_type": "outbound",
      "campaign_uuid": "flw_f1g2h3",
      "contact_uuid": "cst_c1d2e3",
      "from_number": "+15550010000",
      "to_number": "+14155550192",
      "duration": 113,
      "duration_formatted": "01:53",
      "outcome": "connected",
      "sentiment": "positive",
      "summary": "Customer interested in Standing Desk Pro, delivery timeline query.",
      "recording_url": "https://api.nextneural.ai/api/voice/calls/cal_c1d2e3f4/recording",
      "started_at": "2026-05-12T14:32:01Z",
      "ended_at": "2026-05-12T14:34:00Z"
    }
  ],
  "total": 891
}

---

Get call

GET /v1/calls/{call_uuid}
Scope: voice:calls:read

Returns the full call record including the complete transcript.

{
  "uuid": "cal_c1d2e3f4",
  "transcript": [
    { "speaker": "agent",    "text": "Hi, good morning! This is Aria calling from Luminary Home.", "timestamp": 0.0 },
    { "speaker": "customer", "text": "Oh hey, yes I was looking at that desk.",                   "timestamp": 6.2 }
  ],
  "key_details": { "extraction": { "..." : "..." }, "qms_scores": { "...": "..." } }
}

---

Get transcript

GET /v1/calls/{call_uuid}/transcript
Scope: voice:calls:read

Returns just the transcript array without the full call record.

---

Call statistics

GET /v1/calls/stats
Scope: voice:calls:read

Aggregated metrics for a campaign or date range.

Query parameters: campaign_id, date_from, date_to

Response:

{
  "total_calls": 891,
  "connected": 543,
  "voicemail": 124,
  "no_answer": 189,
  "failed": 35,
  "connect_rate": 0.61,
  "sentiment_breakdown": { "positive": 312, "neutral": 189, "negative": 42 },
  "avg_duration_seconds": 97
}

---

Live calls

GET /api/voice/calls/live

Returns currently active inbound calls. Useful for supervisor dashboards.

---

Get recording

GET /api/voice/calls/{call_uuid}/recording?token=<token>

Proxies the telephony provider MP3 with auth. Returns audio stream. Returns 404 if no recording exists or the contact opted out.

---

Write call metadata (workflow action)

POST /api/voice/calls/{call_uuid}/metadata — Rate limit: 30/minute

Allows an external workflow service to write structured extraction results back to a call record after processing. Merges into the key_details field.

{
  "key_details": {
    "extraction": {
      "outcome": { "call_outcome": "warm_transfer", "intent_score": 88 },
      "disposition": { "lead_stage": "Interested in Buying" },
      "next_action": { "type": "warm_transfer", "transfer_target": "sales_specialist" }
    },
    "qms_scores": { "opening": 3, "energy": 2, "probing": 3 }
  }
}

---

Transfer call (workflow action)

POST /api/voice/calls/{call_uuid}/transfer — Rate limit: 10/minute

Bridges an active call to a human agent queue. Only valid while the call is live.

{
  "target": "sales_specialist",
  "agent_brief": "Standing Desk Pro, $850, ready to buy, needs delivery within 3 days.",
  "context": { "intent_score": 88, "cart_value": 850 }
}

Field	Notes
target	Queue name configured in your org, e.g. sales_specialist, support_team
agent_brief	≤280 chars; shown to the receiving human agent
context	Arbitrary JSON attached to the transfer event

Errors: 409 if call is not active · 503 if no agents available

---

End call (workflow action)

POST /api/voice/calls/{call_uuid}/end — Rate limit: 10/minute

Terminates an active call. Used for DNC requests, hostile callers, or wrong-number dispositions.

{ "reason": "dnc_request" }

reason options: dnc_request, wrong_number, hostile_caller, workflow_close

---

Check agent availability (workflow action)

GET /api/voice/calls/agent-availability?target=sales_specialist — Rate limit: 30/minute

Returns whether human agents are available in a given queue before deciding between a warm transfer and an async handoff.

{
  "target": "sales_specialist",
  "available": true,
  "queue_depth": 2,
  "checked_at": "2026-05-12T14:32:00Z"
}