Place an outbound call

1. Confirm authority and consent. Identify the recipient, purpose, local time, applicable calling/recording rules, and the evidence supporting the call. Do not infer consent. Check GET /v1/outbound-tcpa-confirmation. Recording the confirmation requires an authenticated organization admin in the dashboard; an API key cannot self-attest around the gate.
2. Validate resources. The from_number must support outbound calls. Use a deployed agent_id, supply a complete inline config, or omit both to use the number's outbound_agent; omission returns 400 if none is configured. Optional max_hold_seconds overrides the hold timeout for this call. Check balance before a production batch.
3. Create an idempotency key for each intended call so a retry cannot create a second call. Send per-call facts in variables, not instructions.
4. Place one controlled call. POST /v1/call requires from_number and to_number; it accepts agent_id, variables, and idempotency_key.

{
  "from_number": "${FROM_NUMBER}",
  "to_number": "${TO_NUMBER}",
  "agent_id": 12,
  "variables": {},
  "max_hold_seconds": 120,
  "idempotency_key": "${IDEMPOTENCY_KEY}"
}

curl --fail-with-body -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer $THUNDERPHONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-ThunderPhone-Client: skills/place-outbound-calls@1.0" \
  --data "$(jq -n --arg from "$FROM_NUMBER" --arg to "$TO_NUMBER" --argjson agent "$AGENT_ID" --arg key "$IDEMPOTENCY_KEY" '{from_number:$from,to_number:$to,agent_id:$agent,idempotency_key:$key}')"

import os, requests

payload = {"from_number": os.environ["FROM_NUMBER"], "to_number": os.environ["TO_NUMBER"],
           "agent_id": int(os.environ["AGENT_ID"]), "idempotency_key": os.environ["IDEMPOTENCY_KEY"]}
r = requests.post("https://api.thunderphone.com/v1/call", json=payload,
    headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}",
             "X-ThunderPhone-Client": "skills/place-outbound-calls@1.0"}, timeout=30)
r.raise_for_status()
print(r.json())

const response = await fetch("https://api.thunderphone.com/v1/call", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}`,
    "Content-Type": "application/json",
    "X-ThunderPhone-Client": "skills/place-outbound-calls@1.0" },
  body: JSON.stringify({ from_number: process.env.FROM_NUMBER, to_number: process.env.TO_NUMBER,
    agent_id: Number(process.env.AGENT_ID), idempotency_key: process.env.IDEMPOTENCY_KEY }),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

5. Interpret acceptance correctly. A 201 means initiation was accepted, not that a person answered or the conversation succeeded. A 202 can mean the provider outcome is not yet known. Preserve the returned call ID.
6. Poll and inspect. Use GET /v1/calls/{call_id} until terminal, then retrieve GET /v1/calls/{call_id}/transcript. Use webhooks for scale.
7. Switch to campaigns for volume. Use the run-campaign skill for contact imports, calling windows, pause/cancel controls, and aggregate statistics.

Deliverability checklist

Campaign pacing does not apply to POST /v1/call, so the caller's code does it:

• Choose a from_number with the contact's area code and reuse it for that person. Keep each number well under 100 calls a day.
• Call in the contact's local hours, and retry on another day at another time, not on a short loop.
• Send any heads-up text with POST /v1/sms only to people who agreed to it.
• Set the agent to leave a voicemail rather than hang up, and give the number an inbound agent so callbacks reach someone.
• Read answered_by on finished calls and watch GET /v1/phone-numbers/health. Retire a labeled number; never rotate fresh numbers to hide it.

See get outbound calls answered.

Errors

Source and safety rules

• Follow place outbound calls, outbound calling laws, and recording consent laws.
• Confirm fields and statuses in outbound calls and calls.
• Never infer consent, disguise caller identity, or represent initiation as completion.
• Do not include sensitive data in variables unless the conversation requires it.

See references/outbound-readiness.md.