Schedule a call · Heppu API

POST/api/v1/calls/schedulekey or session

Older than jobs and still popular with Make and Zapier users. Puts one call in the queue at a time you pick, with an optional retry plan.

agentIduuidrequired

Voice worker with a phone number.

contactPhonestringrequired

E.164.

contactNamestring

contactEmailstring

callerIdstring

One of the worker's numbers.

scheduledAtISO 8601

Omit to call now. Past times become "now".

priorityint

default 0

maxRetriesint

Defaults to the length of retrySchedule or retryIntervals if given.default 0

retryScheduleISO 8601[]

Exact retry times.

retryIntervals{ value, unit }[]

Relative. unit is minutes, hours or days.

callMetadataobject

Contact and context for the worker. firstName/lastName here fill contactName if missing.

metadataobject

Yours. Echoed in webhooks.

curl -X POST https://v2.heppu.ai/api/v1/calls/schedule \
  -H "x-api-key: hep_..." -H "Content-Type: application/json" \
  -d '{
    "agentId": "6f0c…",
    "contactPhone": "+358401234567",
    "contactName": "Ada",
    "scheduledAt": "2026-09-12T09:00:00+03:00",
    "retryIntervals": [{ "value": 2, "unit": "hours" }, { "value": 1, "unit": "days" }]
  }'

201

{
  "data": {
    "id": "…",
    "status": "scheduled",
    "scheduledAt": "2026-09-12T06:00:00.000Z",
    "agent": { "id": "…", "name": "…" },
    "contact": { "phone": "+358401234567", "name": "Ada", "email": null }
  },
  "meta": { "timestamp": "…", "message": "Call scheduled successfully" }
}

We strip zero-width and control characters from the body before parsing, because Make.com likes to sneak them in. If you still get Invalid JSON payload, check your quotes.

403 blocked number. 400 not a voice worker, no phone number, bad callerId, bad scheduledAt.