# HumanCalls Base URL: https://humancalls.ai A human caller completes business phone tasks for your agent. US and Canada numbers only. Public access: owners can sign up with any email address and must verify it before creating tasks. Documentation is public; API calls use their own bearer key. ## Get started 1. POST /v1/signup with JSON {"owner_email":"owner@example.com","agent_name":"Purchasing agent"}. 2. Save the returned api_key securely; it is shown once. It is pending until the owner confirms the emailed link. Ask your human to verify. Do not try to bypass verification. 3. GET /v1/account with Authorization: Bearer . A verified workspace receives 10 free minutes. Use status, available_cents, available_minutes, and next_step to decide whether work can proceed. 4. If more credit is needed, give the owner top_up_url. Credits are purchased through Stripe Checkout; the agent cannot make a purchase by API. 5. POST /v1/calls with Authorization, Content-Type: application/json, and an Idempotency-Key unique to this task. Example body: {"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"}} ## Task contract Required inputs: to, business, on_behalf_of, goal. Optional inputs: context, script, business_timezone (IANA), metadata (string values), collect (up to 25 fields), webhook_url (HTTPS), max_minutes (1–120, default 10). Output fields: lower_snake_case names mapped to {type, description?, required?}. Types: string, number, boolean, date. Bare type strings remain accepted. 202 creates a task; a matching idempotent replay returns 200. Reusing a key with a different body returns 409. 402 insufficient_credits means no task was queued. Lower max_minutes or ask the owner to top up. 403 account_not_verified means the owner still needs to verify. Suspended accounts also return 403. ## Follow the task GET /v1/calls/:id; GET /v1/calls?limit=20&starting_after=&status=completed. Queued -> assigned -> dialing -> in_progress -> completed, failed, no_answer, declined, or canceled. POST /v1/calls/:id/cancel only while queued or assigned. Results contain outcome (typed values; null when an optional answer was unavailable), outcome_notes, summary, duration_seconds, billed_minutes, cost_usd, recording_url, transcript_url, metadata. Recordings and transcripts may arrive after the completion event. Poll the task until the URLs are present. Fetch media URLs with your bearer key. Transcript JSON includes sentences with speaker, text, start_seconds and end_seconds. ## Credits and delivery Each task reserves max_minutes multiplied by its rate. Calls are charged at completion for connected time, including phone menus and hold, rounded up to a minute. 492 seconds -> 9 minutes -> $9 at the standard rate. Never-connected, declined, and canceled calls cost zero. Unused reserved credit is released. New agent accounts and newly issued dashboard API keys must use a verified connection or explicitly pass delivery:{mode:'polling'}. A verified default is inherited. Existing integrations keep legacy webhook_url behavior. Dashboard users can view results without webhooks. Events: call.completed, call.failed, call.no_answer, call.declined, call.canceled. Verify HC-Signature: t=,v1=. Reject timestamps more than 300 seconds away and compare digests in constant time. Deduplicate on event_id / HC-Event-ID across retries and replays. Persist before returning 2xx. Failed deliveries retry after 1m, 5m, 30m, 2h, 5h, 10h, and 24h. No redirects. Docs: /docs OpenAPI: /v1/openapi.yaml or /v1/openapi.json Dashboard: /app Support: support@humancalls.ai Call results: optional checklist strings add explicit requirements. AI builds a goal/context checklist, fills draft analysis.outcome from saved transcripts, and reports confirmed/missing/unclear checks with evidence. call.media_ready and call.analysis_ready are progress events; wait for a terminal event for the caller-reviewed result. See /docs for version 0.3.0. Intake: tasks are saved immediately, then checked before dialing. intake_status is pending, allowed, review_required, blocked, or failed. Uncertain/failed checks hold dialing; prohibited requests are declined without charge. intake_questions are optional missing-detail suggestions. POST /v1/calls/:id/additions with {"id":"","text":"details"} before the first dial to append information (3,000 characters, ten additions maximum); identical UUID/text retries are idempotent. Additions reset safety clearance and increment request_revision. Never include passwords, verification codes, full card details, or Social Security numbers. call.intake_reviewed is a progress webhook; poll for current state. Creation is limited to ten new tasks/minute/account and three open tasks/account/destination; 429 includes Retry-After. Idempotent creation replays are exempt. ## Agent connection setup POST /v1/connections {name,url} returns id and signing_secret. Requires an owner-issued key with connections_manage permission (new self-provisioned keys have it). Install the secret in your receiver, POST /v1/connections/:id/verify {}, then poll GET /v1/connections/:id. Verification is a signed challenge; return proof=HMAC-SHA256(secret, 'human-calls-verification:'+challenge). A generic 200 is not enough. After status=verified, PATCH /v1/connections/:id {make_default:true}. Or select delivery:{mode:'webhook',connection_id:'conn_...'} per task. Never combine delivery and webhook_url. 409 delivery_required or connection_not_verified creates no task or credit hold. GET /v1/calls/:id/delivery reports queued/delivering/retrying/delivered/failed/disabled and attempts. POST /v1/calls/:id/delivery/replay {} resends the saved event; management keys may specify connection_id to reroute. GET /v1/events?call_id=...&after_sequence=0 supports durable event polling. Verified connections receive {object:'event',event_id,event,schema_version,occurred_at,sequence,terminal,data:}. Legacy endpoints retain flat {event,...call} plus additive event metadata. Final reviewed results trigger terminal events; progress events are opt-in. Agent receivers must store/deduplicate and resume the originating job; a 2xx means receipt, not agent execution. Correlate via metadata.agent_job_id. Guide: /agent-connection-guide.md. Runnable receiver: /receiver.mjs; adapter/setup instructions: /receiver-readme.md. ## Chat apps (MCP) MCP server (Streamable HTTP): https://humancalls.ai/mcp. OAuth 2.1 with PKCE; discovery at https://humancalls.ai/.well-known/oauth-protected-resource. Existing hc_live_ keys also work as Bearer tokens. Tools: request_call, get_call, list_calls, cancel_call, answer_question, add_details, get_account. Results are read with get_call; nothing is pushed. Setup steps for Claude, ChatGPT, Claude Code and other MCP clients: https://humancalls.ai/connect ## Pages - [Home](https://humancalls.ai/): what HumanCalls does and how a call works - [Pricing](https://humancalls.ai/pricing): $1 per connected minute, $0 if nobody answers, 10 free minutes - [API docs](https://humancalls.ai/docs): quickstart, inputs and outputs, credits, webhooks - [Connect a chat app](https://humancalls.ai/connect): setup steps for Claude, ChatGPT, Claude Code and other MCP clients - [Trust & process](https://humancalls.ai/trust): what callers always do and never do - [Full docs in one file](https://humancalls.ai/llms-full.txt) - [Use cases](https://humancalls.ai/use-cases): What people and AI agents use HumanCalls for: stock checks, appointment questions, quotes, opening hours and other answers that only come by phone. - [Integrations](https://humancalls.ai/integrations): Connect HumanCalls to ChatGPT, Claude, Claude Code, Cursor, n8n and any MCP client or HTTP workflow, so your assistant can ask a person to make a call. - [Compare](https://humancalls.ai/vs): How a real person on the phone compares with AI voice agents and other ways to get an answer from a business, and when each one is the better choice. - [Guides](https://humancalls.ai/blog): Practical guides on getting AI agents to make phone calls: what works, what does not, and how to keep a person in the loop where it matters. - [How to make an AI agent call a business](https://humancalls.ai/blog/ai-agent-phone-calls): Three ways to make an AI agent phone a business: build a voice agent, hand the call to a person over an API, or do it yourself. Includes a worked example. - [Can ChatGPT make phone calls?](https://humancalls.ai/blog/can-chatgpt-make-phone-calls): ChatGPT cannot ring an ordinary business line by itself. Here is what voice mode does, what AI voice agents do, and how to have a real person call for you. - [An MCP server for phone calls](https://humancalls.ai/blog/mcp-server-for-phone-calls): The HumanCalls MCP server lets Claude, ChatGPT and other clients ask a real person to phone a business. Address, sign-in and the seven tools. - [Make phone calls from ChatGPT](https://humancalls.ai/integrations/chatgpt): Add HumanCalls to ChatGPT and ask for a phone call in plain words. A real person calls the business and ChatGPT shows you the answers, cost and recording. - [HumanCalls in Claude Code](https://humancalls.ai/integrations/claude-code): Add the HumanCalls MCP server to Claude Code with one command, so an agent working in your terminal can ask a real person to phone a business for an answer. - [Make phone calls from Claude](https://humancalls.ai/integrations/claude): Add HumanCalls to Claude as a custom connector. Ask for a call in your own words and a real person phones the business, then Claude shows what they said. - [HumanCalls in Cursor](https://humancalls.ai/integrations/cursor): Add the HumanCalls MCP server to Cursor so its agent can ask a real person to phone a business and bring back typed answers, a summary and the recording. - [Add a phone call step to an n8n workflow](https://humancalls.ai/integrations/n8n): Use 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. - [Ask about an appointment by phone](https://humancalls.ai/use-cases/appointment-availability): Have a real person phone a garage, salon, contractor or office to ask about appointment times and prices, and book only if you said they may. - [Confirm opening hours with a phone call](https://humancalls.ai/use-cases/business-hours): Listings go stale. Have a real person phone a business to confirm today's opening hours, holiday hours or whether a service is offered before you travel. - [Check stock and price by phone](https://humancalls.ai/use-cases/check-stock): Have a real person phone a supplier or store to confirm stock, price and lead time, and get the answers back as typed fields your team or AI agent can use. - [Collect quotes by phone](https://humancalls.ai/use-cases/get-quotes): Have a real person phone several vendors with the same questions and return price, lead time and terms as comparable fields for you or your AI agent. - [Call a supplier to check order status](https://humancalls.ai/use-cases/order-status): Have a real person phone a supplier about an order or delivery and bring back the status, the expected date and the name of who they spoke to. - [A human caller or an AI voice agent?](https://humancalls.ai/vs/ai-voice-agents): 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.