API Reference

Agency plan required

The BuildVoiceAI API gives you programmatic access to trigger outbound calls, receive call events via webhooks, and integrate voice AI into your own applications and workflows.

Base URL

All API requests are made to:


https://app.buildvoiceai.com/api/v1

All requests must use HTTPS. HTTP requests are rejected.

Authentication

Every API request requires an API key passed in the Authorization header:


Authorization: Bearer your_api_key_here

Generate API keys in Settings → API & Webhooks. See API Authentication for details on key management and rate limits.

Available Endpoints

Method	Endpoint	Description
POST	`/calls/trigger`	Trigger an outbound call

The API is currently focused on call triggering and webhook events. Additional endpoints for agent and client management are planned for future releases.

Webhooks

In addition to the REST API, BuildVoiceAI can send real-time event notifications to your server via webhooks. Configure a webhook URL to receive events when calls start, complete, or fail.

See Webhook Events for payload formats and configuration details.

Response Format

All API responses are returned as JSON. Successful responses include a success field:


{
  "success": true,
  "data": { ... }
}

Error responses include an error field with a human-readable message:


{
  "success": false,
  "error": "Invalid API key"
}

HTTP Status Codes

Code	Meaning
`200`	Request succeeded
`400`	Bad request — check your request body
`401`	Unauthorized — invalid or missing API key
`403`	Forbidden — API access is disabled or insufficient permissions
`404`	Not found — the requested resource does not exist
`429`	Rate limited — too many requests
`500`	Internal server error — retry or contact support

Rate Limits

API requests are limited to 100 requests per minute per API key. If you exceed this limit, you will receive a 429 response. See API Authentication for details.

Quick Start

Here is a minimal example to trigger an outbound call:


curl -X POST https://app.buildvoiceai.com/api/v1/calls/trigger \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "agent_id": "your-agent-uuid"
  }'

API Reference Pages

API Authentication — Key management, rate limits, and security
Trigger Call API — Trigger outbound calls programmatically
Webhook Events — Receive real-time call event notifications
Provider Comparison — Compare Retell, Vapi, and Bland features