# 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).

## 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: block a number across the whole network.

## 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).
- payout_cents (default 600), bonus_cents (default 5000, paid when booked).
- 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 blocked network-wide; never re-queue them.

## Billing

Pay as you go ($6/attempt, $50/booked meeting) or plans with included calls (Starter $99/mo for 20, Growth $399/mo for 100, Scale $999/mo for 300). Usage beyond included calls is metered via Stripe. The user manages plans and API keys at https://ringahuman.com/dashboard (sign in with an API key).

## 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.
- Shared do-not-call list, checked at creation and again right before dialing.
- One open task per phone number at a time.
- 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