Skip to main content

​
Overview

The Avoca AI API provides programmatic access to our AI-powered communication and scheduling platform for home service businesses. This REST API enables developers to integrate Avoca’s voice AI, scheduling, messaging, and analytics capabilities into their applications.

​
Base URL

All API requests should be made to: 
https://api.avoca.ai/v1

​
Authentication

All API requests require authentication using an API key. Include your API key in the request headers: 
Authorization: Bearer YOUR_API_KEY
X-Workspace-ID: YOUR_WORKSPACE_ID
To obtain your API credentials, log in to your Avoca Dashboard and navigate to Settings → API Keys.

​
Rate Limiting

To ensure fair usage and system stability, the following rate limits apply:
  • 1,000 requests per minute per API key
  • 10,000 requests per hour per workspace
Rate limit information is included in all API responses: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1642521600

​
Core Platform Areas

The Avoca API is organized around key functional areas:

Inbound Communication

Handle incoming calls, chats, SMS, and emails with AI automation

Outbound Campaigns

Speed-to-lead, happy calls, maintenance reminders, and reschedule calls

Analytics & Coach

Call scoring, performance metrics, and quality assurance

Bot Building

Configure AI assistants with custom voices, prompts, and knowledge

Scheduling

Simple scheduler widget, availability checking, and appointment booking

Omnichannel

Unified messaging across voice, SMS, email, and live chat

​
Request Format

All requests must include the following headers: 
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
X-Workspace-ID: YOUR_WORKSPACE_ID

​
Response Format

All API responses return JSON data with consistent formatting:

​
Success Response

{
  "data": {
    // Response data
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-20T15:30:00Z"
  }
}

​
Error Response

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The appointment slot is no longer available",
    "details": {
      "field": "appointment_slot",
      "reason": "slot_taken"
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-20T15:30:00Z"
  }
}

​
Error Codes

CodeHTTP StatusDescription
AUTHENTICATION_FAILED401Invalid or missing API key
PERMISSION_DENIED403Insufficient permissions for resource
NOT_FOUND404Resource not found
INVALID_REQUEST400Invalid request parameters
RATE_LIMIT_EXCEEDED429Too many requests
INTERNAL_ERROR500Server error

​
Webhook Events

Configure webhooks to receive real-time notifications for:
  • call.completed - Inbound or outbound call ended
  • appointment.scheduled - New appointment booked
  • sms.received - Inbound SMS received
  • chat.started - Live chat session initiated
  • speed_to_lead.completed - STL call attempt finished
  • coach.score_available - New call score calculated

​
SDKs & Libraries

Official SDKs are available for:

Node.js/TypeScript

Full TypeScript support with async/await

Python

Pythonic interface with type hints

​
Quick Start Example

Here’s a simple example using Speed-to-Lead: 
import { AvocaClient } from '@avoca/node-sdk';

const client = new AvocaClient({
  apiKey: process.env.AVOCA_API_KEY,
  workspaceId: process.env.WORKSPACE_ID
});

// Trigger speed-to-lead call
const response = await client.speedToLead.trigger({
  teamId: 123,
  customerName: 'John Doe',
  phoneNumber: '(555) 123-4567',
  leadSource: 'Website Form',
  serviceType: 'HVAC Repair'
});

console.log('Speed-to-lead call scheduled:', response.data.id);

​
Support

Need help? We’re here to assist: