Quick Start

Get up and running with the Vocobase Partner API. By the end of this guide, you will have created a voice agent and initiated your first outbound call.

Prerequisites

A Vocobase account with approved partner status (apply here)
Your API key (format: rg_live_xxxx)
At least one telephony provider configured and allowed for your partner account

Get your API key

Log in to the Vocobase Dashboard and navigate to API Keys. Create a new key and copy it immediately — it is only shown once.Your key looks like this:

rg_live_abc123def456ghi789jkl012

Store your API key securely. It cannot be retrieved after creation.

Test your connection

Verify your API key works by fetching your partner configuration:

curl -X GET https://api.vocobase.com/api/v2/config \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

const response = await fetch("https://api.vocobase.com/api/v2/config", {
  headers: {
    "Authorization": "Bearer rg_live_abc123def456ghi789jkl012"
  }
});
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    "https://api.vocobase.com/api/v2/config",
    headers={"Authorization": "Bearer rg_live_abc123def456ghi789jkl012"}
)
print(response.json())

You should receive a response with your partner configuration:

{
  "success": true,
  "data": {
    "name": "acme-corp",
    "display_name": "Acme Corporation",
    "agent_limit": 10,
    "current_agent_count": 0,
    "status": "active",
    ...
  }
}

Create an agent

Create your first voice agent. The voice_id is the catalog id returned by GET /agent/voices — fetch it first and pick a row that matches the tier, language, and gender you want. Use GET /agent/voice-tiers to list supported tiers, then filter the catalog with GET /agent/voices?tier=va-1.

curl -X POST https://api.vocobase.com/api/v2/agent \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Sales Assistant",
    "prompt": "You are a friendly sales assistant for Acme Corp. Help callers understand our products and answer their questions.",
    "voice_id": "b49e0d0f-2219-4425-a765-1efd32beb509",
    "agent_type": "outbound",
    "intro_message": "Hello! Thanks for taking my call. How can I help you today?"
  }'

const response = await fetch("https://api.vocobase.com/api/v2/agent", {
  method: "POST",
  headers: {
    "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    agent_name: "Sales Assistant",
    prompt: "You are a friendly sales assistant for Acme Corp. Help callers understand our products and answer their questions.",
    voice_id: "b49e0d0f-2219-4425-a765-1efd32beb509",
    agent_type: "outbound",
    intro_message: "Hello! Thanks for taking my call. How can I help you today?"
  })
});
const data = await response.json();
console.log(data.data.id); // Save this agent ID

import requests

response = requests.post(
    "https://api.vocobase.com/api/v2/agent",
    headers={
        "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
        "Content-Type": "application/json"
    },
    json={
        "agent_name": "Sales Assistant",
        "prompt": "You are a friendly sales assistant for Acme Corp. Help callers understand our products and answer their questions.",
        "voice_id": "b49e0d0f-2219-4425-a765-1efd32beb509",
        "agent_type": "outbound",
        "intro_message": "Hello! Thanks for taking my call. How can I help you today?"
    }
)
data = response.json()
print(data["data"]["id"])  # Save this agent ID

The response includes your new agent’s ID:

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "agent_name": "Sales Assistant",
    "status": "active",
    ...
  }
}

Save the id from the response - you will need it to start calls. On supported Plivo and Vobiz accounts, agents also accept optional voicemail_detection_enabled and voicemail_message fields for carrier-side voicemail handling.

Make your first call

Initiate an outbound call using the agent you just created. Replace the agent_id with the ID from the previous step. If your account has multiple active connections for the selected provider, include connection_id from GET /api/v2/telephony/connections.

curl -X POST https://api.vocobase.com/api/v2/calls/start \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "to_number": "+919876543210",
    "provider": "twilio",
    "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20"
  }'

const response = await fetch("https://api.vocobase.com/api/v2/calls/start", {
  method: "POST",
  headers: {
    "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    agent_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    to_number: "+919876543210",
    provider: "twilio",
    connection_id: "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20"
  })
});
const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://api.vocobase.com/api/v2/calls/start",
    headers={
        "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
        "Content-Type": "application/json"
    },
    json={
        "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "to_number": "+919876543210",
        "provider": "twilio",
        "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20"
    }
)
print(response.json())

{
  "success": true,
  "data": {
    "call_id": "c1234567-abcd-1234-abcd-123456789012",
    "session_id": "s1234567-abcd-1234-abcd-123456789012",
    "status": "pending",
    "provider": "twilio",
    "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
    "from_number": "+14155551234",
    "to_number": "+919876543210",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

The from_number is resolved from the selected provider connection and returned in the response. The call is placed asynchronously. Set up webhooks to receive live call status updates plus the final transcript and recording URL.

Next steps

Authentication

Learn about API key formats, rate limits, and error handling.

Configure Webhooks

Receive live call status updates and final session results.

Twilio Setup

Configure Twilio for outbound calling.

API Reference

Explore the full API reference.

Getting Started

Guides

Partner Onboarding

API Reference

Webhooks

Telephony

Quick Start

Quick Start

Prerequisites

Next steps

Authentication

Configure Webhooks

Twilio Setup

API Reference

​Quick Start

​Prerequisites

​Next steps

Authentication

Configure Webhooks

Twilio Setup

API Reference

Quick Start

Prerequisites

Next steps