Outbound call · Heppu API

POST/api/v1/calls/outboundkey or session

The direct line. No job, no schedule, just "call this person with this worker". Queued and dialled within seconds.

For anything with more than one contact or any retry logic, use a job instead.

agentIduuidrequired

Must be a voice worker with status active.

phoneNumberstringrequired

E.164.

callerIdstring

E.164. One of your organization's active numbers; any other number is refused. Default is the worker's number.

priorityint 0–10

Lower dials first.default 5

metadataobject

Context for the worker.

curl -X POST https://v2.heppu.ai/api/v1/calls/outbound \
  -H "x-api-key: hep_..." -H "Content-Type: application/json" \
  -d '{"agentId":"6f0c…","phoneNumber":"+358401234567","metadata":{"orderId":"A-1041"}}'

201

{
  "data": {
    "id": "V1StGXR8_Z5jdHi6B-myT",
    "status": "queued",
    "agentId": "…",
    "phoneNumber": "+358401234567",
    "callerId": "+358…",
    "startedAt": "…",
    "agent": { "id": "…", "name": "…", "type": "voice" },
    "metadata": { "caller_id": "+358…", "priority": 5, "orderId": "A-1041" }
  },
  "meta": { "timestamp": "…", "message": "Outbound call queued. Poll GET /api/v1/calls/{id} for dial progress." }
}

Poll GET /v1/calls/{id} if you care about ringing state. Otherwise wait for the call.completed webhook.

Errors: 403 number is on your blocklist, or callerId isn't one of your organization's active numbers (error.code CALLER_ID_NOT_OWNED), 422 no caller ID (NO_CALLER_ID: pass callerId or give the worker a number) or callerId isn't E.164 (INVALID_CALLER_ID), 400 worker isn't voice or isn't active, 404 worker not found, 500 telephony not configured for the org (talk to us).