AgentCall — Phone Numbers for AI Agents\r

\r You have access to the AgentCall API for phone numbers, SMS, voice calls, and AI voice calls.\r \r

Authentication\r

\r All requests require: Authorization: Bearer \x3CAGENTCALL_API_KEY>\r \r The API key is available in the AGENTCALL_API_KEY environment variable.\r \r

Base URL\r

\r https://api.agentcall.co\r \r For a complete plain-text API reference: GET https://api.agentcall.co/llms.txt\r \r

Phone Numbers\r

\r Provision a number:\r

POST /v1/numbers/provision\r
Body: { "type": "local", "country": "US", "label": "my-agent" }\r
Types: local ($2/mo), tollfree ($4/mo), mobile ($3/mo), sim ($8/mo, Pro only)\r
Response: { "id": "num_xxx", "number": "+12125551234", "type": "local", ... }\r
```\r
\r
**List numbers:**\r
```\r
GET /v1/numbers\r
Query: ?limit=20&country=US&type=local\r
```\r
\r
**Get number details:**\r
```\r
GET /v1/numbers/:id\r
```\r
\r
**Release a number (irreversible):**\r
```\r
DELETE /v1/numbers/:id\r
```\r
\r
## SMS\r
\r
**Send SMS:**\r
```\r
POST /v1/sms/send\r
Body: { "from": "num_xxx", "to": "+14155551234", "body": "Hello!" }\r
"from" can be a number ID or E.164 phone string\r
```\r
\r
**Get inbox:**\r
```\r
GET /v1/sms/inbox/:numberId\r
Query: ?limit=20&otpOnly=true\r
```\r
\r
**Get a specific message:**\r
```\r
GET /v1/sms/:messageId\r
```\r
\r
**Wait for OTP code (long-polls up to 60 seconds):**\r
```\r
GET /v1/sms/otp/:numberId\r
Query: ?timeout=60000\r
Response: { "otp": "482913", "message": { ... } }\r
```\r
\r
## Voice Calls\r
\r
**Start an outbound call:**\r
```\r
POST /v1/calls/initiate\r
Body: { "from": "num_xxx", "to": "+14155551234", "record": false }\r
```\r
\r
**Start an AI voice call (Pro plan, $0.20/min):**\r
The AI handles the entire conversation autonomously based on your systemPrompt.\r
```\r
POST /v1/calls/ai\r
Body: {\r
  "from": "num_xxx",\r
  "to": "+14155551234",\r
  "systemPrompt": "You are calling to schedule a dentist appointment for Tuesday afternoon.",\r
  "voice": "alloy",\r
  "firstMessage": "Hi, I'd like to schedule an appointment please.",\r
  "maxDurationSecs": 600\r
}\r
Voices (pick based on user's desired tone):\r
- alloy: neutral, balanced (default)\r
- ash: warm, conversational\r
- ballad: expressive, melodic\r
- coral: clear, professional\r
- echo: resonant, deep\r
- sage: calm, authoritative, confident\r
- shimmer: bright, energetic\r
- verse: smooth, articulate\r
```\r
\r
**List call history:**\r
```\r
GET /v1/calls\r
Query: ?limit=20\r
```\r
\r
**Get call details:**\r
```\r
GET /v1/calls/:callId\r
```\r
\r
**Get AI call transcript:**\r
```\r
GET /v1/calls/:callId/transcript\r
Response: { "entries": [{ "role": "assistant", "text": "...", "timestamp": "..." }], "summary": "..." }\r
```\r
\r
**Hang up an active call:**\r
```\r
POST /v1/calls/:callId/hangup\r
```\r
\r
## Webhooks\r
\r
**Register a webhook:**\r
```\r
POST /v1/webhooks\r
Body: { "url": "https://example.com/hook", "events": ["sms.inbound", "sms.otp", "call.status"] }\r
Events: sms.inbound, sms.otp, call.inbound, call.ringing, call.status, call.recording, number.released\r
```\r
\r
**List webhooks:**\r
```\r
GET /v1/webhooks\r
```\r
\r
**Rotate webhook secret:**\r
```\r
POST /v1/webhooks/:id/rotate\r
```\r
\r
**Delete a webhook:**\r
```\r
DELETE /v1/webhooks/:id\r
```\r
\r
## Usage & Billing\r
\r
**Get usage breakdown:**\r
```\r
GET /v1/usage\r
Query: ?period=2026-02\r
```\r
\r
## Phone Number Format\r
\r
All phone numbers must be E.164: `+{country code}{number}`, e.g. `+14155551234`\r
\r
## Common Workflows\r
\r
### Test your app's SMS verification (QA)\r
1. `POST /v1/numbers/provision` with `{ "type": "local" }` — get a test number\r
2. Enter the number into your staging app's verification form\r
3. `GET /v1/sms/otp/:numberId?timeout=60000` — wait for the verification code\r
4. Assert the code arrives and your app accepts it\r
5. `DELETE /v1/numbers/:id` — release the test number\r
\r
### AI voice call\r
1. `POST /v1/numbers/provision` with `{ "type": "local" }` — get a number (if you don't have one)\r
2. `POST /v1/calls/ai` with `{ "from": "num_xxx", "to": "+1...", "systemPrompt": "..." }` — start the call\r
3. Wait for the call to complete\r
4. `GET /v1/calls/:callId/transcript` — get the full conversation transcript\r
\r
## Error Codes\r
- **401**: Invalid or missing API key\r
- **403 plan_limit**: Plan limit reached (upgrade to Pro at agentcall.co/dashboard)\r
- **404**: Resource not found\r
- **422**: Validation error (check request body)\r
- **429**: Rate limit exceeded (100 req/min)\r