A phone call API with a human caller
Some answers only come from ringing a business. The HumanCalls REST API hands that call to a real person. You send the number, the goal and the fields you want back. You get typed answers, a summary, the recording and a transcript.
Sign up an agent and verify the workspace
An agent can create its own workspace, but a person has to confirm it. Documentation is public. API calls use a bearer key.
POST /v1/signupwithowner_emailandagent_name. Save the returnedapi_keysecurely, because it is shown once.- The key stays pending until the owner clicks the emailed link. Ask your human to verify. Do not try to get around this step.
GET /v1/accountwithAuthorization: Bearer <api_key>. Readstatus,available_cents,available_minutesandnext_stepbefore you queue work. A verified workspace gets 10 free minutes.- If more credit is needed, give the owner the
top_up_url. Credit is bought through Stripe Checkout by the owner. An agent cannot buy credit through the API.
Create a call with POST /v1/calls
Four fields are required: to, business, on_behalf_of and goal. Optional fields include context, script, business_timezone (IANA), metadata (string values), max_minutes (1 to 120, default 10) and collect, with up to 25 output fields. Each field has a lower_snake_case name and a type of string, number, boolean or date, plus an optional description and required flag.
curl -X POST https://humancalls.ai/v1/calls \
-H "Authorization: Bearer $HC_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: harbor-sku-7712-check-1" \
-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},
"delivery_date": {"type": "date", "description": "Earliest delivery date"}
},
"delivery": {"mode": "polling"}
}'The task is saved at once, then checked before anyone dials. Requests that are prohibited, such as sales or debt collection, are declined at no charge. Your caller sticks to the goal and does not buy, book or agree to anything you did not authorize. See how our callers work.
Idempotency, errors and limits
Send an Idempotency-Key that is unique to each task. If a network error leaves you unsure, retry with the same key and the same body.
| Response | Meaning |
|---|---|
| 202 | Task created |
| 200 | Idempotent replay of a matching request |
| 409 | Same key reused with a different body, or delivery_required / connection_not_verified |
402 insufficient_credits | No task queued. Lower max_minutes or ask the owner to top up |
403 account_not_verified | The owner has not verified yet. Suspended accounts also get 403 |
| 429 | Too many requests. Wait for Retry-After |
Each account can create ten new tasks a minute and keep three open tasks per destination number. Idempotent replays do not count. POST /v1/calls/:id/cancel works only while a task is queued or assigned.
Polling or a verified webhook connection
New agent accounts must choose. Either pass delivery: {mode: 'polling'} or use a verified connection.
Polling. Call GET /v1/calls/:id. Status moves from queued to assigned, dialing and in_progress, then ends as completed, failed, no_answer, declined or canceled. Results include outcome, outcome_notes, summary, duration_seconds, billed_minutes, cost_usd, recording_url and transcript_url. The recording and transcript can arrive after completion, so keep polling until the URLs appear. Fetch them with your bearer key.
Webhook connection. POST /v1/connections with a name and HTTPS URL returns an id and signing_secret. Install the secret, then POST /v1/connections/:id/verify. Your receiver must answer a signed challenge with the right HMAC proof. A plain 200 is not enough. Once verified, make it the default or pass its connection_id per task. Never send both delivery and webhook_url.
Terminal events are call.completed, call.failed, call.no_answer, call.declined and call.canceled. Failed deliveries retry after 1m, 5m, 30m, 2h, 5h, 10h and 24h. Redirects are not followed.
Verify HC-Signature in outline
- Read the header
HC-Signature: t=<unix>,v1=<hex>. - Reject the request if the timestamp is more than 300 seconds from now.
- Compute HMAC-SHA256 with your signing secret over the timestamp, a dot, and the raw body.
- Compare digests in constant time.
- Deduplicate on
event_idand save the event before you return 2xx.
A 2xx only means you received the event. Use metadata.agent_job_id to resume the job that asked for the call.
Credits and what a call costs
Each task reserves max_minutes of credit. At completion you pay $1 per connected minute, rounded up, including phone menus and hold. A 492-second call bills 9 minutes, or $9. Calls that never connect, declined requests and canceled calls cost $0, and unused reserved credit is released. More on the pricing page.
Questions
- Is the caller an AI voice?
- No. A real, trained person makes every call. They say who they are and who they are calling for, and tell the business the call is recorded.
- Can my AI agent sign up by itself?
- It can call /v1/signup and get a key, but the owner must verify the emailed link before any task can be created.
- Do I need a webhook?
- No. Pass delivery mode polling and read GET /v1/calls/:id. Webhooks need a verified connection with signed delivery.
- Which numbers can I call?
- Businesses in the United States and Canada, during the business's local hours. The full reference is in the docs.
Related
- Add a phone call tool to any MCP clientConnect any MCP client to HumanCalls over Streamable HTTP with OAuth 2.1 or an API key. Seven tools let a real person call a business and return the answers.
- Add a phone call step to an n8n workflowUse HumanCalls from n8n: one HTTP Request node asks a real person to phone a business, and a second reads back typed answers your workflow can branch on.
- A human caller or an AI voice agent?When should an AI agent's phone call be made by a real person, and when by an AI voice agent? An honest comparison of cost, speed, accuracy and disclosure.
Try it with 10 free minutes
$1 per connected minute after that, and nothing when nobody picks up.