Skip to Content
APIEndpointsCalls

Calls

A call is a single phone conversation between an Akol AI agent and a contact. Calls always belong to a Campaign and a Business.

List calls

GET /api/v1/calls?page=1&limit=20&direction=inbound&status=COMPLETED

Filters:

  • direction — inbound | outbound
  • status — RINGING | IN_PROGRESS | COMPLETED | FAILED | VOICEMAIL
  • outcome — completed | transferred | voicemail_left | hung_up | ...
  • sentiment — positive | neutral | negative
  • businessId, campaignId, agentId, phoneNumberId
  • startDate, endDate — ISO-8601, filters by startedAt

Get one call

GET /api/v1/calls/:id

Response:

{
  "success": true,
  "data": {
    "id": "call_xxx",
    "businessId": "biz_xxx",
    "campaignId": "cmp_xxx",
    "agentId": "agt_xxx",
    "phoneNumberId": "pn_xxx",
    "direction": "inbound",
    "fromNumber": "+15551234567",
    "toNumber": "+15557654321",
    "callerName": "Alice (existing contact)",
    "status": "COMPLETED",
    "outcome": "completed",
    "startedAt": "2026-04-18T14:21:42.000Z",
    "endedAt":   "2026-04-18T14:23:10.000Z",
    "durationSeconds": 88,
    "sentiment": "positive",
    "summary": "Caller asked about hours and booked a Saturday slot.",
    "tags": ["appointment", "first-time"],
    "transcript": [
      { "speaker": "agent",  "text": "Thanks for calling.", "timestamp": 0 },
      { "speaker": "caller", "text": "Are you open Saturday?", "timestamp": 2400 }
    ]
  }
}

recordingUrl is excluded from this response. Fetch the audio separately:

GET /api/v1/calls/:id/audio

Returns the recording. Audio is typically audio/wav or audio/mp3 depending on the campaign’s recording settings.

Place an outbound call

POST /api/v1/calls
Idempotency-Key: <uuid>
Content-Type: application/json
 
{
  "campaignId": "cmp_xxx",
  "toNumber": "+15551234567",
  "fromPhoneNumberId": "pn_xxx"
}

Returns 201 with the new call ID. The call is queued and will be placed within ~2 seconds. Subscribe to the call.started and call.ended webhook events to track progress.

429 if the campaign is paused or the account has hit its monthly minute limit (and overage is disabled).

End a call in progress

POST /api/v1/calls/:id/end

Forces the call to end immediately. Useful for testing or manual abort.

Export transcripts

GET /api/v1/calls/:id/transcript

Returns the call’s transcript as JSON. (Other formats — txt, srt — are on the roadmap but not yet exposed by the API. Format the JSON yourself in the meantime.)

Last updated on
BusinessesCampaigns