# Ring a Human

> Ring a Human lets an AI agent hand a phone call to a real person. The agent creates a call task (phone number, goal, brief); a vetted human caller claims it, dials from their own phone during the lead's local calling hours, and reports the outcome back. Use it whenever a phone call would move things forward and an AI voice can't legally or credibly make it (US TCPA: AI voices count as "artificial voice" calls).

## Try it first: sandbox (no key, no signup)

MCP: https://ringahuman.com/sandbox/mcp (no auth) · REST: POST https://ringahuman.com/api/sandbox/tasks
Same tools and response shapes as production, but calls are simulated and nobody is dialed. Status goes open → claimed → completed in ~8s. The phone's last 4 digits pick the outcome: 0100 booked, 0101 conversation, 0102 voicemail, 0103 no_answer, 0104 gatekeeper, 0105 not_interested, 0106 wrong_number, 0107 do_not_call, 0199 never claimed. Use 555 numbers, e.g. (512) 555-0100. webhook_url works too. Outside the lead's calling hours (9am–8pm local), the sandbox fast-forwards to the next window and says so in calling_window; production would wait.

## Set up (do these steps for your user)

1. Get an API key. Ask your user for their work email and company, then:

   curl -X POST https://ringahuman.com/api/signup \
     -H "Content-Type: application/json" \
     -d '{"email":"USER_EMAIL","company":"COMPANY"}'

   No email verification: the response immediately contains `api_key` (starts with `rah_live_`, shown once), `free_calls`, a ready-made `mcp` config and a `dashboard` link. Store the key as a secret (e.g. RINGAHUMAN_API_KEY). Never print it into chat logs or commit it.
   Free calls: 2 with a work email, 1 with a personal email. After that, tasks are saved with status "review" until the user picks a plan at https://ringahuman.com/dashboard/billing (they're then dispatched automatically). Tell the user this.

2. Connect the MCP server (Streamable HTTP, stateless): https://ringahuman.com/mcp with header `Authorization: Bearer <api_key>`.

   - Claude Code:
     claude mcp add --transport http ringahuman https://ringahuman.com/mcp --header "Authorization: Bearer $RINGAHUMAN_API_KEY"
   - Cursor / Claude Desktop / other JSON configs:
     {"mcpServers":{"ringahuman":{"url":"https://ringahuman.com/mcp","headers":{"Authorization":"Bearer <api_key>"}}}}
   - No MCP? Use the REST API below with the same key.

3. Wire it into the workflow your user cares about (e.g. "when a new lead submits the form, create a call task within 5 minutes"). Send a webhook_url so outcomes flow back automatically.

## Tools (MCP) / endpoints (REST)

- create_call_task / POST /api/tasks: queue a call for a human. Returns the task.
- get_call_task / GET /api/tasks/{id}: status, lead local time, and outcome once completed.
- list_call_tasks / GET /api/tasks?status=: recent tasks.
- cancel_call_task / POST /api/tasks/{id}/cancel: pull a call before anyone dials (e.g. the lead replied by email).
- add_do_not_call / POST /api/dnc: put a number on your account's do-not-call list (cancels your open tasks for it).
- get_billing_status / GET /api/billing: free calls remaining, whether a card is on file, pricing, and whether new tasks will dispatch.
- create_checkout_link / POST /api/billing/checkout {"plan": "payg|starter|growth|scale"}: returns a Stripe Checkout URL. Give it to your user; queued tasks dispatch automatically once they pay.

## create_call_task fields

- phone (required): US number, any format.
- goal (required): one sentence, e.g. "Book a 15-minute call to walk through their website grade".
- brief (required, 10–4000 chars): what the caller reads before dialing. Include: why now (what the lead just did and when), 2–3 specifics about them, the one ask, and answers to the two likeliest objections. One concrete number and one link the caller can mention out loud work best.
- consent (required): the legal basis. One of inquiry (they contacted you within ~90 days), express_written, existing_customer, b2b_main_line (a business's published main number). Only create tasks you have a real basis for.
- state (2-letter) or timezone (IANA): required, used to enforce 9am–8pm local calling hours.
- business_name, lead_name: shown to the caller.
- links: up to 10 {label, url} the caller can open (report, site preview, CRM record).
- deadline_minutes: expire if not called in time.
- webhook_url: receives {"event":"task.completed","task":{...}} when the caller logs the outcome.
- external_ref: your own ID, echoed back.

## Outcomes

task.outcome.disposition is one of: booked, conversation, not_interested, gatekeeper, voicemail, no_answer, wrong_number, do_not_call. Notes and meeting_at come with it. do_not_call numbers are added to your account's do-not-call list; never re-queue them.

## Billing

Pricing is a pure utility: $1 per minute of call time, rounded up, with a 2-minute minimum per completed call. No monthly fee, no booking fees. Free calls first (2 with a work email). After that the user adds a card once: call create_checkout_link and give them the link. Completed tasks report outcome.call_seconds and outcome.billed_minutes.

## Response SLA
A human dials within 5 minutes, counted inside the lead's calling hours. Each task returns `sla.dial_by`. When you create a task outside calling hours, tell your user when it's due ("shortly after 9am their time").

## Rules the system enforces

- A human places every call by tapping Call on their own phone. No autodialer, no AI voice.
- Calls only 9am–8pm in the lead's timezone; tasks outside the window wait.
- Per-account do-not-call list, checked at creation and again right before dialing. Opt-outs logged on your calls are added automatically.
- One open task per phone number at a time, per account.
- Full audit trail. Calls are not recorded.

## Errors

JSON {"error": "..."} (MCP: isError with the same message). 400 invalid field · 401 bad key · 404 not found · 409 on DNC, duplicate open task, or task no longer open.

## More

- How it works: https://ringahuman.com/how-it-works/
- API reference: https://ringahuman.com/docs/
- Is AI cold calling legal? https://ringahuman.com/guides/ai-cold-calling-tcpa/
- Contact: hello@ringahuman.com

## Agent skill
A ready-made SKILL.md for Claude Code and other skill-aware agents: https://ringahuman.com/skills/ringahuman/SKILL.md