Votel API
Build with the Votel API to create AI voice agents, send messages, manage contacts, trigger workflows, and retrieve results programmatically.
API sections
The API is organized to match the Votel app, so you can find endpoints for anything you do in the dashboard.
| App section | What you can do via the API |
|---|---|
| Conversations | Read inbox threads, send messages (SMS, email, WhatsApp), manage quick replies, configure channels |
| Calendars | Create booking pages, manage availability & staff, accept bookings, handle waitlists |
| Contacts | Create and search leads, import/export, custom fields, pipeline stages, activity timelines |
| Tasks | Create and assign tasks, custom task fields, saved task views |
| Agents | Build and deploy AI voice agents, manage versions, knowledge bases, TTS voices, AI generation |
| Activity | Query call logs, meeting logs, phone/widget/workflow reports, messaging logs |
| Workflows | Create automations, set triggers, enroll contacts, manage variables and campaigns |
| Communication | Send SMS and emails directly, manage email templates |
| Payments | Manage billing, products, and subscriptions |
| Click Tracking | Create tracking links, monitor clicks, conversions, landing pages, and traffic sources |
| Settings | API keys, users, sub-accounts, phone numbers, integrations, domains, and more |
Authentication
Authenticate every request with your API key in the X-API-Key header.
X-API-Key: sk_your_api_key_here
Create and manage API keys at app.votel.ai/settings/api-keys.
Keep your API key secret. Never expose it in client-side code or public repositories.
Make your first request
List your AI agents:
curl https://app.votel.ai/api/agents -H "X-API-Key: sk_your_api_key_here"
Response:
[{ "id": "a1b2c3d4-...", "name": "Sales Assistant", "enabled": true }]
If you get a 200 OK, you are ready to start building.
Python
import requests
response = requests.get(
"https://app.votel.ai/api/agents",
headers={"X-API-Key": "sk_your_api_key_here"},
)
print(response.json())
JavaScript
const response = await fetch("https://app.votel.ai/api/agents", {
headers: { "X-API-Key": "sk_your_api_key_here" },
});
const agents = await response.json();
console.log(agents);
PHP
$ch = curl_init("https://app.votel.ai/api/agents");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["X-API-Key: sk_your_api_key_here"],
]);
$response = curl_exec($ch);
curl_close($ch);
$agents = json_decode($response, true);
print_r($agents);
Base URL
https://app.votel.ai/api
All endpoints are relative to this base URL.
Request and response format
The API accepts and returns JSON. Set Content-Type: application/json on requests with a body.
When an error occurs, the response includes a detail message:
{
"detail": "Lead not found"
}
Status codes
| Code | Meaning |
|---|---|
200 | Success |
201 | Created |
400 | Bad request — check your parameters |
401 | Unauthorized — invalid or missing API key |
402 | Payment required — insufficient wallet balance |
403 | Forbidden — upgrade required or insufficient permissions |
404 | Not found |
429 | Rate limited — back off and retry |
500 | Server error |
Rate limits
When you hit a rate limit, the API returns 429 Too Many Requests with a Retry-After header. Design your integration to retry with exponential backoff.
Next steps
Pick the section that matches what you're building:
- Agents — deploy AI voice agents and manage knowledge bases
- Conversations — send and receive messages across channels
- Contacts — manage your leads and customers
- Workflows — automate multi-step processes
- Calendars — set up booking pages and availability
- Communication — send SMS and emails directly