A phone call as a capability.

Start with one task

Create an API key in your workspace and send it in the Authorization header. Every key belongs to a single account. Use Idempotency-Key to safely retry task creation.

curl https://humancalls.ai/v1/calls \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: your-unique-task-id' \
  -d '{
  "to": "+12125550100",
  "business": "Harbor Supply Co.",
  "on_behalf_of": "Acme Robotics",
  "goal": "Confirm stock and earliest delivery for SKU 7712",
  "max_minutes": 10,
  "collect": {
    "in_stock": {
      "type": "boolean",
      "required": true,
      "description": "Is SKU 7712 available now?"
    },
    "delivery_date": {
      "type": "date"
    }
  },
  "webhook_url": "https://your-app.com/hooks/calls"
}'

A new task returns 202 with its ID and status. A matching retry returns the same task with 200. Poll GET /v1/calls/:id or wait for a signed webhook.

Let your agent sign up

Send POST /v1/signup with owner_email and agent_name. The response includes a key once, with status pending_verification. The human owner must confirm the email link before that key can create tasks.

Until confirmation, the key can only call GET /v1/account. It returns balance, account status, and a dashboard URL to give the human. Owners can sign up with any email address and must verify it before the agent can create tasks.

Inputs in. Answers out.

Send the business phone, business name, who you're calling on behalf of, and the goal. Add context, a suggested script, a business timezone, and metadata when useful. Add optional checklist strings for specific things to confirm; AI also builds a checklist from the goal and context.

collect defines your outputs. Each field has a type (string, number, boolean, or date), an optional description, and an optional required flag. Legacy bare type strings are still accepted.

The result includes outcome, per-field outcome_notes, a summary, duration, cost, and authenticated recording/transcript URLs. Missing optional answers are null. After recordings and transcripts are saved, AI fills analysis.outcome and checks each requirement against the transcript. The caller reviews the answers and explains missing confirmations before submitting the final result. analysis.checks includes confirmed, missing, or unclear statuses with transcript evidence.

Credits & limits

Verified workspaces receive 10 free minutes. The default max_minutes is 10; choose 1–120. A new task reserves its maximum cost. If available credit is too low, the API returns 402 insufficient_credits without queuing the call.

Connected time is rounded up to a started minute. Canceling queued or assigned tasks releases the hold. Check GET /v1/account before creating work and use its top_up_url when credits run low.

Connect your agent

Register a receiving endpoint, verify its signing secret, and use it as your default. New agent accounts must select a verified connection or explicitly choose polling. Open setup guide

Verify every delivery

Events use HC-Signature: t=TIMESTAMP,v1=HEX_DIGEST. Compute HMAC-SHA256 with your connection signing secret (workspace secret for legacy endpoints) over timestamp + "." + rawBody; compare digests in constant time and reject timestamps outside five minutes. During rotation, accept any valid v1 signature.

Delivery is at least once. Deduplicate by event_id (HC-Event-ID), including manual replays. Retries run after 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours, and 24 hours. Persist the event before returning a 2xx response. Retries include jitter; permanent errors stop retries. Redirects are rejected.

Events include call.completed, call.failed, call.no_answer, call.declined, and call.canceled. Use the task page to inspect attempts and resend. call.media_ready and call.analysis_ready announce processing progress; wait for a terminal event for the submitted result.

API reference

Generated from this deployment's OpenAPI contract.