Trigger Call API

Agency plan required

The Trigger Call endpoint lets you programmatically initiate outbound calls. Use it to connect your CRM, internal tools, or automation workflows to BuildVoiceAI.

POST/api/v1/calls/trigger

Initiate an outbound call to the specified phone number using the given agent.

Request

Headers

Header	Value	Required
`Authorization`	`Bearer your_api_key`	Yes
`Content-Type`	`application/json`	Yes

Body Parameters

Field	Type	Required	Description
`phone_number`	string	Yes	Phone number in E.164 format (e.g., `+15551234567`)
`agent_id`	string	No	UUID of the agent to use. Falls back to the default agent if omitted.
`name`	string	No	Caller name, passed to the agent’s prompt as context
`email`	string	No	Caller email, passed to the agent’s prompt as context
`metadata`	object	No	Arbitrary key-value pairs passed through to webhooks and call records

If you omit agent_id, the call uses the default agent configured in Integrations → API & Webhooks. Make sure a default agent is set if you plan to omit this field.

Example Request


curl -X POST https://app.buildvoiceai.com/api/v1/calls/trigger \
  -H "Authorization: Bearer bvai_sk_1a2b3c4d5e6f7g8h9i0j" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "metadata": {
      "source": "hubspot",
      "deal_id": "deal_12345"
    }
  }'

Response

Success (200)


{
  "success": true,
  "call_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "status": "initiated"
}

Field	Type	Description
`success`	boolean	Always `true` for successful requests
`call_id`	string	Unique identifier for the initiated call
`status`	string	Initial call status — always `initiated`

Error Responses

Status	Error	Cause
`400`	`Invalid phone number format`	Phone number is not in E.164 format
`400`	`Agent not found`	The specified `agent_id` does not exist
`400`	`No agent specified and no default agent configured`	No `agent_id` provided and no default agent is set
`400`	`Agent has no phone number assigned`	The agent needs a phone number to make outbound calls
`401`	`Invalid API key`	The API key is missing or incorrect
`403`	`API access is disabled`	API access has been toggled off
`429`	`Rate limit exceeded`	More than 100 requests per minute

Phone Number Format

Phone numbers must be in E.164 format:

Start with + followed by the country code
No spaces, dashes, or parentheses
Examples: +15551234567 (US), +447911123456 (UK), +61412345678 (AU)

⚠️

Calls will fail if the phone number is not in E.164 format. The API does not attempt to normalize phone numbers.

Using Metadata

The metadata field accepts any JSON object. This data is:

Stored with the call record in the dashboard
Included in webhook payloads when the call completes
Available in the call detail view

Common use cases for metadata:

Tracking the source system (source: "hubspot")
Passing deal or ticket IDs for CRM linkback
Tagging calls for campaign tracking
Including custom context for reporting

Use Cases

Trigger from a CRM

When a lead enters a specific pipeline stage in HubSpot or GHL, use the API to automatically call them:


# Called from your CRM webhook handler
curl -X POST https://app.buildvoiceai.com/api/v1/calls/trigger \
  -H "Authorization: Bearer bvai_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+15551234567", "agent_id": "...", "metadata": {"pipeline": "new-leads"}}'

Trigger from Zapier or Make

Use an HTTP action in Zapier or Make to call this endpoint when a trigger fires (new form submission, new CRM contact, etc.).

💡

Include meaningful metadata with every API call. It makes debugging and reporting much easier when you can trace a call back to its source.

Calling Window

Calls respect the calling window configured on the agent. If you trigger a call outside the agent’s allowed calling hours, the call will be queued and executed when the window opens, or rejected depending on your agent settings.