Before quoting allowances or taking a paid action, call get_plan (or GET /v1/account) and use the returned offerVersion, trial, limits, billingStatus and summary. New live_trial_72h_v1 accounts have a one-time 72-hour trial starting at successful number allocation, 300 managed inbound AI seconds total and five verified-destination SMS attempts; card verification is required first. No monthly reset, automatic upgrade or Free overage. Existing free_monthly_v1 accounts retain assigned monthly allowances. Live OTP extraction, outbound calls, BYOK and Premium Voice require Pro for new trial accounts. Explain payment_method_required, payment_recovery_required, trial expiry and quota errors; stop retrying them. Share the returned setup/upgrade link when the user wants to proceed, let the human complete card/payment steps, then reread get_plan before retrying. Do not assume saving a card upgrades the account, or promise a released number can be recovered. Pro is $19.99/month plus number rental and usage. Do not auto-run upgrade_to_pro just because another tool failed. Honor the user's authorization for any real-world action. Read https://api.agentcall.co/llms.txt for the current reference.

New accounts receive a one-time 72-hour live trial with one US/Canada local number, 300 managed inbound AI seconds (five minutes) total, and five SMS send attempts to verified destinations. Card verification is required before number allocation; the clock starts when allocation succeeds. There is no monthly reset or automatic paid subscription. Live OTP extraction and outbound calls require Pro.

Pro is $19.99/month plus number rental and usage: local/mobile numbers $2/month each, toll-free $2.50/month, outbound SMS $0.015/message, standard outbound voice $0.035/min, managed AI voice $0.40/min, BYOK voice $0.10/min plus your AI provider's charges, or Premium Voice $0.59/min. AI calls round up to whole minutes per call. New-account destination/business verification can still apply after upgrading.

After trial expiry, the number is held for at least 48 hours before release, with a successful expiry notice before release becomes eligible. A delayed notice extends the hold. Trial expiry and number retention are separate; stored configuration and results remain available. Upgrading during the hold preserves the number.

# AgentCall API — Complete Reference for AI Agents

> Base URL: https://api.agentcall.co
> Auth: Authorization: Bearer <AGENTCALL_API_KEY>
> Phone format: E.164 — +{country code}{number}, e.g. +14155551234

## Phone Numbers

POST /v1/numbers/provision
  Body: { "type": "local", "country": "US", "label": "my-agent" }
  Types: local ($2/mo), tollfree ($2.50/mo), mobile ($2/mo)
  Response: { "id": "num_xxx", "number": "+12125551234", "type": "local", ... }

GET /v1/numbers
  Query: ?limit=20&country=US&type=local
  Response: { "data": [...], "hasMore": false }

GET /v1/numbers/:id
  Response: { "id": "num_xxx", "number": "+12125551234", ... }

DELETE /v1/numbers/:id
  Releases the number. Irreversible, stops billing immediately.

## SMS

POST /v1/sms/send
  Body: { "from": "num_xxx", "to": "+14155551234", "body": "Hello!" }
  "from" can be a number ID or E.164 string
  Response: { "id": "msg_xxx", "status": "queued", ... }

GET /v1/sms/inbox/:numberId
  Query: ?limit=20&otpOnly=true
  Response: { "data": [{ "id": "msg_xxx", "from": "+1...", "body": "...", "otp": "482913" }] }

GET /v1/sms/:messageId
  Response: { "id": "msg_xxx", "body": "...", "otp": "482913", ... }

GET /v1/sms/otp/:numberId
  Long-polls for up to 60 seconds waiting for an OTP code.
  Query: ?timeout=60000
  Response: { "otp": "482913", "message": { ... } }

## Voice Calls

POST /v1/calls/initiate
  Body: { "from": "num_xxx", "to": "+14155551234", "record": false }
  Response: { "id": "call_xxx", "status": "queued", ... }

GET /v1/calls/prompt-templates
  Public — no auth. Returns 5 ready-made system prompt templates for AI voice calls:
  receptionist, lead-qualifier, appointment-booker, customer-support, call-screener.
  Each template has [BRACKETED] placeholders to fill in with your business details,
  plus a recommended voice and maxDurationSecs.
  Use one of these instead of writing a system prompt from scratch — vague prompts
  cause the AI to hallucinate (e.g. invent pricing tiers).
  Full guide: https://agentcall.co/docs/voice-prompts

POST /v1/calls/ai
  AI-powered voice call — the AI handles the conversation autonomously.
  Pro plan only. $0.40/minute.
  Body: {
    "from": "num_xxx",
    "to": "+14155551234",
    "systemPrompt": "You are calling to schedule a dentist appointment for Tuesday afternoon.",
    "voice": "shimmer",
    "firstMessage": "Hi, I'd like to schedule an appointment please.",
    "maxDurationSecs": 600
  }
  Voices (pick based on desired tone — preview at GET /v1/calls/voices):
    shimmer: bright, energetic (default — recommended starting point)
    sage: calm, authoritative, confident
    ash: warm, conversational
    ballad: expressive, melodic
    coral: clear, professional
    echo: resonant, deep
    verse: smooth, articulate
    alloy: neutral, balanced
  Response: { "id": "call_xxx", "status": "queued", "voice": "shimmer", ... }

GET /v1/calls
  Query: ?limit=20
  Response: { "data": [...] }

GET /v1/calls/:callId
  Response: { "id": "call_xxx", "status": "completed", "duration": 45, ... }

GET /v1/calls/:callId/transcript
  Get the transcript of a completed AI voice call.
  Response: { "entries": [{ "role": "assistant", "text": "...", "timestamp": "..." }], "summary": "..." }

POST /v1/calls/:callId/hangup
  Terminates an active call.

## Inbound AI Voice

POST /v1/numbers/:numberId/inbound-config
  Configure how inbound calls to a US or Canada number are handled.
  In "ai" mode, a managed AI voice agent picks up incoming calls and follows the system prompt.
  New accounts get 300 managed inbound AI seconds total within a one-time 72-hour live trial, with card verification before number allocation. Exhaustion or expiry stops new trial calls; it does not create paid overage or a monthly reset. Existing Free accounts keep their assigned monthly offer. Read get_plan or GET /v1/account before quoting limits.
  Body (AI mode):
  {
    "mode": "ai",
    "systemPrompt": "You are the front desk for Acme Plumbing. Greet callers and take their name, address, and the issue.",
    "voice": "sage",
    "firstMessage": "Thanks for calling Acme Plumbing — how can I help?",
    "maxDurationSecs": 600
  }
  Voices: alloy | ash | ballad | coral | echo | sage | shimmer | verse
  Response: { "numberId": "num_xxx", "number": "+12125551234", "carrierTier": "primary", "config": { ... } }

GET /v1/numbers/:numberId/inbound-config
  Read the current inbound config.
  Response: { "numberId": "num_xxx", "number": "+12125551234", "carrierTier": "primary", "config": { ... } }

DELETE /v1/numbers/:numberId/inbound-config
  Clears the inbound config. Returns 204.

## Webhooks

POST /v1/webhooks
  Body: { "url": "https://example.com/hook", "events": ["sms.inbound", "sms.otp", "call.status"] }
  Events: sms.inbound, sms.otp, call.inbound, call.ringing, call.status, call.recording, call.transcript, number.released

GET /v1/webhooks
  Response: { "data": [...] }

POST /v1/webhooks/:id/rotate
  Rotates the signing secret. New secret is only shown once.

DELETE /v1/webhooks/:id
  Deactivates and removes the webhook.

## Usage & Billing

GET /v1/usage
  Query: ?period=2026-02
  Response: { "period": "2026-02", "totalCost": 12.50, "breakdown": [...] }

## Common Workflows

### Test your app's SMS verification (QA)
1. POST /v1/numbers/provision { "type": "local" } → get a test number
2. Enter the number into your staging app's verification form
3. GET /v1/sms/otp/:numberId?timeout=60000 → get the verification code
4. Assert the code arrives and your app accepts it
5. DELETE /v1/numbers/:id → release the test number

### AI voice call
1. POST /v1/numbers/provision { "type": "local" } → get number ID (if you don't have one)
2. POST /v1/calls/ai { "from": "num_xxx", "to": "+1...", "systemPrompt": "..." }
3. Wait for call to complete
4. GET /v1/calls/:callId/transcript → get the full conversation

### Inbound AI voice (auto-answer incoming calls)
1. POST /v1/numbers/provision { "type": "local", "country": "US" } → get a number
2. POST /v1/numbers/:numberId/inbound-config { "mode": "ai", "systemPrompt": "...", "voice": "sage", "firstMessage": "..." }
3. Anyone who calls the number gets answered by a managed AI voice agent that follows the prompt
4. DELETE /v1/numbers/:numberId/inbound-config → disable when you're done

## Error Codes
- 401: Invalid or missing API key
- 403 plan_limit_*: You've hit a Free plan limit. The error body carries upgradeUrl (https://agentcall.co/billing) and upgradeToolName (upgrade_to_pro, an MCP tool that returns a checkout link). Pro is $19.99/mo plus usage.
- 404: Resource not found
- 422: Validation error (check request body)
- 429: Rate limit exceeded (100 req/min)