Campaign Management

Campaign Quickstart

Get up and running with the Vozzo Campaign API in minutes. This guide will walk you through creating your first automated voice call campaign.

Prerequisites

Before you begin, ensure you have:

A Vozzo account with API access
Your API key (format: Token YOUR_SECRET_API_KEY)
An AI agent created and configured in your Vozzo account
The agent's UUID from the Vozzo platform
Test phone numbers in E.164 format (e.g., +91-xxxxxxxx)

Step 1: Verify Authentication

First, verify your API key is working correctly by checking your user information.

Code
 
curl --request GET \
  --url https://backend.vozzo.ai/v1alpha/auth/me \
  --header 'Authorization: Token YOUR_SECRET_API_KEY'

Expected Response:


Code
 
{
  "user_id": "880e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "name": "John Doe",
  "organization_id": 12345,
  "organization_name": "Example Corp",
  "permissions": ["campaign:read", "campaign:write"]
}

Step 2: Create Your First Campaign

Now let's create a simple campaign with two recipients. Replace the placeholders with your actual values.

Code
 
curl --request POST \
  --url https://backend.vozzo.ai/v1alpha/campaign \
  --header 'Authorization: Token YOUR_SECRET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "agent_uuid": "YOUR_AGENT_UUID",
    "campaign_name": "My First Campaign",
    "campaign_start_date": "2026-01-04",
    "campaign_end_date": "2026-01-10",
    "campaign_start_time": "09",
    "campaign_end_time": "18",
    "campaign_allow_weekends": false,
    "campaign_max_retry": 3,
    "campaign_max_retry_per_day": 1,
    "campaign_data": [
      {
        "to_phone_number": "+911234567890",
        "agent_language": "EN",
        "metadata": "{\"customer_name\":\"John Doe\",\"product\":\"premium_plan\"}"
      },
      {
        "to_phone_number": "+911234567891",
        "agent_language": "HI",
        "metadata": "{\"customer_name\":\"Priya Sharma\",\"product\":\"basic_plan\"}"
      }
    ]
  }'

Understanding the Request Parameters

Parameter	Description	Example
agent_uuid	Your AI agent's unique identifier	619ec26c-...
campaign_name	Human-readable campaign name	"My First Campaign"
campaign_start_date	Campaign start date (YYYY-MM-DD)	"2026-01-04"
campaign_end_date	Campaign end date (optional)	"2026-01-10"
campaign_start_time	Daily start hour (00-23)	"09" (9 AM)
campaign_end_time	Daily end hour (00-23)	"18" (6 PM)
campaign_allow_weekends	Allow calls on Sat/Sun	false
campaign_max_retry	Max total retry attempts (1-5)	3
campaign_max_retry_per_day	Max daily retries (1-5, optional)	1

Campaign Data Structure

Each recipient in campaign_data requires:


Code
 
{
  "to_phone_number": "+911234567890",
  "agent_language": "EN",
  "metadata": "{\"customer_name\":\"John Doe\",\"account_id\":\"ACC12345\"}"
}

to_phone_number: Phone number in E.164 format with country code
agent_language: Language code (EN, HI, BN, TA, TE, MR, etc.)
metadata: JSON string containing personalization data for the AI agent

Expected Response


Code
 
{
  "success": true,
  "message": "Campaign created successfully",
  "data": {
    "campaign_id": "550e8400-e29b-41d4-a716-446655440000",
    "campaign_name": "My First Campaign",
    "campaign_state": "TO_START",
    "campaign_start_date": "2026-01-04",
    "campaign_end_date": "2026-01-10",
    "org_id": 1,
    "created_at": "2026-01-03T14:30:00Z"
  }
}

Success! Save the campaign_id for monitoring and management.

Step 3: Monitor Your Campaign

Check Campaign Status

Code
 
curl --request GET \
  --url https://backend.vozzo.ai/v1alpha/campaign/550e8400-e29b-41d4-a716-446655440000 \
  --header 'Authorization: Token YOUR_SECRET_API_KEY'

View Scheduled Calls

Code
 
curl --request GET \
  --url 'https://backend.vozzo.ai/v1alpha/campaign/550e8400-e29b-41d4-a716-446655440000/items?page=1&page_size=10' \
  --header 'Authorization: Token YOUR_SECRET_API_KEY'

Get Campaign Analytics

Code
 
curl --request GET \
  --url https://backend.vozzo.ai/v1alpha/campaigns/analytics/550e8400-e29b-41d4-a716-446655440000 \
  --header 'Authorization: Token YOUR_SECRET_API_KEY'

Step 4: Start Your Campaign

When you're ready to begin calling, update the campaign status to RUNNING.

Code
 
curl --request POST \
  --url 'https://backend.vozzo.ai/v1alpha/campaign/update-campaign/550e8400-e29b-41d4-a716-446655440000/?campaign_status=RUNNING&campaign_allow_weekends=false' \
  --header 'Authorization: Token YOUR_SECRET_API_KEY'

Campaign States

TO_START

Campaign created but not yet active

RUNNING

Campaign actively processing calls

SUSPENDED

Campaign temporarily paused

ENDED

Campaign completed or terminated

How To Integrate API's

Create Campaign

Endpoint

POST {{baseUrl}}/v1alpha/campaign

Create a new outbound calling campaign with scheduling rules, retry logic, and campaign-specific call data.

Headers

Authorization

string · pattern:

^Token
YOUR_SECRET_API_KEY

· required

Your secret API key from Vozzo platform formatted as Token YOUR_SECRET_API_KEY

Field	Type	Required	Description
agent_uuid	string (uuid)	Yes	Unique identifier of the AI agent that will handle the calls. The agent must be created and configured in Vozzo before campaign creation.
campaign_name	string	Yes	Human-readable name for the campaign used for identification and reporting.
campaign_start_date	string (YYYY-MM-DD)	Yes	Start date for the campaign. Must be today or a future date.
campaign_end_date	string (YYYY-MM-DD)	No	Optional end date for the campaign. If not provided, the campaign runs indefinitely.
campaign_start_time	string (00–23)	Yes	Campaign start hour in 24-hour format. Defines the earliest hour calls can be made.
campaign_end_time	string (00–23)	Yes	Campaign end hour in 24-hour format. Must be after `campaign_start_time`.
campaign_allow_weekends	boolean	Yes	Whether calls are allowed on Saturdays and Sundays.
campaign_max_retry	integer (1–5)	Yes	Maximum total retry attempts per recipient, including the initial call.
campaign_max_retry_per_day	integer (1–5)	No	Optional maximum retry attempts per recipient per day. If not set, total retry limit is used.
campaign_data	object[]	Yes	List of recipients and call-specific parameters. Supports bulk operations with thousands of recipients.

curl --request POST \
  --url https://backend.vozzo.ai/v1alpha/campaign \
  --header 'Authorization: <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{ "agent_uuid": "619ec26c-4957-4926-70f8-fe7391b3527e", "campaign_name": "Winter Promotion 2024", "campaign_start_date": "2024-12-01", "campaign_end_date": "2024-12-31", "campaign_start_time": "09", "campaign_end_time": "18", "campaign_allow_weekends": false, "campaign_max_retry": 3, "campaign_max_retry_per_day": 1, "campaign_data": [{ "to_phone_number": "+911234567890", "agent_language": "EN", "metadata": "{\"customer_name\":\"John Doe\"}" }] }'

Example Request Body


Code
 
  {
      "agent_uuid": "619ec26c-4957-4926-70f8-fe7391b3527e",
      "campaign_name": "Winter Promotion 2024",
      "campaign_start_date": "2024-12-01",
      "campaign_end_date": "2024-12-31",
      "campaign_start_time": "09",
      "campaign_end_time": "18",
      "campaign_allow_weekends": false,
      "campaign_max_retry": 3,
      "campaign_max_retry_per_day": 1,
      "campaign_data": [
          {
          "to_phone_number": "+911234567890",
          "agent_language": "EN",
          "metadata": "{\\"customer_name\\":\\"John Doe\\",\\"account_id\\":\\"ACC12345\\",\\"product\\":\\"premium_plan\\"}"
          },
          {
          "to_phone_number": "+911234567891",
          "agent_language": "HI",
          "metadata": "{\\"customer_name\\":\\"Jane Smith\\",\\"account_id\\":\\"ACC12346\\",\\"product\\":\\"basic_plan\\"}"
          }
      ]
  }

Update Campaign

Endpoint

POST {{baseUrl}}/v1alpha/campaign/update-campaign/{campaign_id}/

Update an existing campaign's configuration, schedule, and settings. Allows modifying campaign status, dates, time slots, retry options, and other operational parameters while preserving campaign data.

Headers

Authorization

string · pattern:

^Token
YOUR_SECRET_API_KEY

· required

Your secret API key from Vozzo platform formatted as Token YOUR_SECRET_API_KEY

Path Parameters

campaign_id

stringuuidrequired

Unique identifier of the campaign to update

Query Parameters

campaign_allow_weekends

booleanrequired

Whether to allow calls on weekends

campaign_status

string · enum

Campaign status to update

Enum values: TO_START, RUNNING, SUSPENDED, ENDED

campaign_start_date

string · date

Updated start date in YYYY-MM-DD format

campaign_end_date

string · date

Updated end date for the campaign (optional)

campaign_max_retry

integer · min: 1 · max: 5

Maximum total retry attempts (1–5)

campaign_max_retry_per_day

integer · min: 1 · max: 5

Maximum retry attempts per day (1–5)

campaign_start_time

string · time

Start time in 24-hour format (00–23)

campaign_end_time

string · time

End time in 24-hour format (00–23)

curl --request POST \
  --url "https://backend.vozzo.ai/v1alpha/campaign/update-campaign/5804a5e5-97fd-4dc4-8d0d-87895734af7d?campaign_status=SUSPENDED&campaign_start_date=2026-01-01&campaign_end_date=2026-01-14&campaign_start_time=09&campaign_end_time=18&campaign_max_retry=4&campaign_max_retry_per_day=2&campaign_allow_weekends=false" \
  --header "Authorization: Token YOUR_SECRET_API_KEY"

Example Request

{
  "success": true,
  "message": "Campaign updated successfully",
  "data": {
    "campaign_id": "c5785fa5-8bdd-4629-b7ef-1addfc4b44a5",
    "org_id": 1,
    "campaign_state": "SUSPENDED",
    "campaign_start_date": "2026-01-01",
    "campaign_end_date": "2026-01-14",
    "campaign_config": {
      "campaign_name": "TEST",
      "retry_options": {
        "max_calls_total": 4,
        "max_calls_in_a_day": 4,
        "retry_delay": 60
      },
      "metadata": {},
      "timeslot_settings": {
        "timezone": "IST",
        "allow_on_weekends": false,
        "start_time": "09",
        "end_time": "18"
      },
      "preferred_timeslot": "ANYDAY",
      "encrypted_data": false,
      "internal_auth": false,
      "org_id": null,
      "post_call_action": null
    },
    "updated_at": "2025-12-26T12:51:40.253482+00:00"
  }
}

Get Campaigns List

Endpoint

GET {{baseUrl}}/v1alpha/campaigns

Retrieve a paginated list of all campaigns for the authenticated user. This endpoint provides a high-level overview of campaigns including their current state and basic information.

Headers

Authorization

string · pattern:

^Token
YOUR_SECRET_API_KEY

· required

Your secret API key from Vozzo platform formatted as Token YOUR_SECRET_API_KEY

Query Parameters

limit

integer · min: 1 · max: 100 · default: 20

Number of campaigns to return per page.

offset

integer · min: 0 · default: 0

Number of campaigns to skip for pagination.

state

string · enum

Filter campaigns by their current lifecycle state.

Example values: TO_START, RUNNING, SUSPENDED, COMPLETED, ENDED

curl --request GET \
  --url "https://backend.vozzo.ai/v1alpha/campaigns?limit=20&offset=0&state=RUNNING" \
  --header "Authorization: Token YOUR_SECRET_API_KEY"

Example Response

{
  "campaigns": [
    {
      "campaign_id": "550e8400-e29b-41d4-a716-446655440000",
      "campaign_name": "Summer Promotion",
      "campaign_state": "RUNNING",
      "agent_id": "660e8400-e29b-41d4-a716-446655440000",
      "created_at": "2024-01-15T10:30:00Z",
      "total_records": 150,
      "processed_records": 75
    }
  ],
  "total": 5,
  "limit": 20,
  "offset": 0
}

Get Campaign Details

Endpoint

GET {{baseUrl}}/v1alpha/campaign/{campaign_id}

Retrieve comprehensive information about a specific campaign including configuration, statistics, and current status. Use this endpoint for detailed campaign analysis and monitoring.

Headers

Authorization

string · pattern:

^Token
YOUR_SECRET_API_KEY

· required

Your secret API key from Vozzo platform formatted as Token YOUR_SECRET_API_KEY

Path Parameters

campaign_id

string · uuidrequired

Unique identifier of the campaign. Obtain this from the campaign creation response or campaigns list endpoint.

curl --request GET \
  --url "https://backend.vozzo.ai/v1alpha/campaign/550e8400-e29b-41d4-a716-446655440000" \
  --header "Authorization: Token YOUR_SECRET_API_KEY"

Example Response


Code
 
  {
    campaign_id: "550e8400-e29b-41d4-a716-446655440000",
    campaign_name: "Summer Promotion 2024",
    campaign_state: "RUNNING",
    agent_id: "660e8400-e29b-41d4-a716-446655440000",
    org_id: 12345,
    campaign_start_date: "2024-06-01T09:00:00Z",
    campaign_end_date: "2024-08-31T18:00:00Z",
    created_at: "2024-05-25T14:30:00Z",
    updated_at: "2024-06-15T16:45:00Z",
    campaign_data: {
      total_records: 150,
      processed_records: 75,
      successful_calls: 45,
      failed_calls: 5,
      pending_calls: 25,
    },
    campaign_config: {
      preferred_timeslot: "WEEKDAY_AFTERNOON",
      retry_options: {
        max_attempts: 3,
        delay_minutes: 60,
      },
      campaign_name: "Summer Promotion 2024",
    },
    campaign_report_summary: {
      successful_calls: 45,
      failed_calls: 5,
      pending_calls: 25,
      total_attempts: 75,
      average_call_duration: 125,
      completion_rate: 60.0,
    },
    campaign_schema_version: "1.0.0",
    active: true,
  },
  null,
  2
)}

Get Campaign Analytics

Endpoint

GET {{baseUrl}}/v1alpha/campaigns/analytics/{campaign_id}

Retrieve detailed analytics and metrics for a specific campaign including category breakdowns, goal achievements, success criteria, and tagging information.

Headers

Authorization

string · pattern:

^Token
YOUR_SECRET_API_KEY

· required

Your secret API key from Vozzo platform formatted as Token YOUR_SECRET_API_KEY

Path Parameters

campaign_id

string · uuidrequired

Unique identifier of the campaign to get analytics for.

curl --request GET \
  --url "https://backend.vozzo.ai/v1alpha/campaigns/analytics/5804a5e5-97fd-4dc-8d0d-87895734af7d" \
  --header "Authorization: Token YOUR_SECRET_API_KEY"

Responses

200 OK

Returns campaign analytics data.

401 Unauthorized

Invalid or missing authentication token.

404 Not Found

Campaign not found.

Example Response


Code
 
  {
    category: {
      "Account Identification Failed": 0,
      "Transferred to Agent": 0,
      "Others": 1,
    },
    goals: {
      "Account Identification": 1,
      "Resolved": 1,
    },
    success_criteria: {
      "Account Identification successe": 1,
      "No Callback Requested": 1,
    },
    tags: {
      "Account Identification Failed tags": 0,
      "Transferred to Agent tags": 0,
    },
  },
  null,
  2

Get Campaigns By Agent

Endpoint

GET {{baseUrl}}/v1alpha/campaigns/agent/{agent_uuid}

Retrieve a paginated list of campaigns managed by a specific agent, including campaign configuration, statistics, and performance metrics.

Headers

Authorization

string · pattern:

^Token
YOUR_SECRET_API_KEY

· required

Your secret API key from Vozzo platform formatted as Token YOUR_SECRET_API_KEY

Path Parameters

agent_uuid

string · uuidrequired

Unique identifier of the agent to retrieve campaigns for.

Query Parameters

page

integer · min: 1 · default: 1

Page number for pagination (1-based).

page_size

integer · min: 1 · max: 100 · default: 10

Number of campaigns per page.

curl --request GET \
  --url "https://backend.vozzo.ai/v1alpha/campaigns/agent/32f9e6e3-b535-4d2e-959d-c94cfd456a23" \
  --header "Authorization: Token YOUR_SECRET_API_KEY"

Responses

200 OK

Returns a list of campaigns managed by the agent.

401 Unauthorized

Invalid or missing authentication token.

404 Not Found

Agent not found or no campaigns available.

Example Response


Code
 
  [
    {
      campaign_id: "22af4c4a-6499-4936-b38d-9501473f7e37",
      campaign_name: "winter sale now",
      campaign_state: "RUNNING",
      agent_id: "32f9e6e3-b535-4d2e-959d-c94cfd456a23",
      campaign_start_date: "2025-11-18",
      campaign_end_date: null,
      campaign_report_summary: {
        total_calls: 1,
        total_calls_failed: 0,
        total_calls_completed: 1,
        total_calls_pending: 0,
        total_calls_in_progress: 0,
        total_calls_post_call_action_pending: 0,
        total_calls_user_defined_action_pending: 0
      },
      average_call_duration_seconds: 4.0
    }
  ],
  null,
  2

Get Campaigns Count By Agent

Endpoint

GET {{baseUrl}}/v1alpha/campaigns/agent/{agent_uuid}/count

Retrieve counts of campaigns for a specific agent, including total campaigns, active campaigns, and completed campaigns.

Headers

Authorization

string · pattern:

^Token
YOUR_SECRET_API_KEY

· required

Your secret API key from Vozzo platform formatted as Token YOUR_SECRET_API_KEY

Path Parameters

agent_uuid

string · uuidrequired

Unique identifier of the agent to get campaign counts for.

curl --request GET \
  --url "https://backend.vozzo.ai/v1alpha/campaigns/agent/32f9e6e3-b535-4d2e-959d-c94cfd456a23/count" \
  --header "Authorization: Token YOUR_SECRET_API_KEY"

Responses

200 OK

Returns campaign counts for the agent.

401 Unauthorized

Invalid or missing authentication token.

404 Not Found

Agent not found.

Example Response


Code
 
  {
    total_campaigns: 13,
    active_campaigns: 13,
    completed_campaigns: 0
  },
  null,
  2

Get Scheduled Calls

Endpoint

GET {{baseUrl}}/v1alpha/campaign/{campaign_id}/items

Retrieve all scheduled calls for a specific campaign with pagination. This endpoint provides visibility into individual call attempts, their status, and detailed call information.

Headers

Authorization

string · pattern:

^Token
YOUR_SECRET_API_KEY

· required

Your secret API key from Vozzo platform formatted as Token YOUR_SECRET_API_KEY

Path Parameters

campaign_idstring · uuidrequired

Unique identifier of the campaign. Must be an active campaign that you have access to.

Query Parameters

pageinteger · min: 1 · default: 1

Page number for pagination (1-based).

page_sizeinteger · min: 1 · max: 100 · default: 10

Number of call records to return per page.

curl --request GET \
  --url "https://backend.vozzo.ai/v1alpha/campaign/5804a5e5-97fd-4dc-8d0d-87895734af7d/items" \
  --header "Authorization: Token YOUR_SECRET_API_KEY"

Responses

200 OK

Returns a list of scheduled calls for the campaign.

401 Unauthorized

Invalid or missing authentication token.

404 Not Found

Campaign not found or you don’t have access to this campaign.

422 Validation Error

Invalid parameters (e.g., UUID format).

Example Response


Code
 
  [
    {
      scheduled_item_id: "27108280-91a6-4edf-ba9c-c9e593ef0f3e",
      campaign_id: "5804a5e5-97fd-4dc4-8d0d-87895734af7d",
      agent_id: "32f9e6e3-b535-4d2e-959d-c94cfd456a23",
      call_state: "COMPLETED",
      call_info: {
        agent_language: "Hindi",
        to_phone_number: "+916376526334",
        post_call_action: null
      },
      call_history: {
        actor: "vozzo-workflows:check_attempted_calls",
        status: "COMPLETED",
        conv_id: 14718,
        message: "Call completed after 2 attempt(s)",
        call_uuid: "07f95ec0-ef2c-4691-b3a9-3efcc844abd5",
        timestamp: "2025-12-16T10:48:06.603989"
      }
    }
  ],
  null,
  2
}

Get Scheduled Call Details

Endpoint

GET {{baseUrl}}/v1alpha/campaign/{campaign_id}/item/{scheduled_item_id}

Retrieve comprehensive information about a specific scheduled call including call logs, attempt history, and detailed results. Use this for detailed call analysis and troubleshooting.

Headers

Authorization

string · pattern:

^Token
YOUR_SECRET_API_KEY

· required

Your secret API key from Vozzo platform formatted as Token YOUR_SECRET_API_KEY

Path Parameters

campaign_idstring · uuidrequired

Unique identifier of the campaign containing the scheduled call.

scheduled_item_idstring · uuidrequired

Unique identifier of the specific scheduled call item.

curl --request GET \
  --url "https://backend.vozzo.ai/v1alpha/campaign/550e8400-e29b-41d4-a716-446655440000/item/770e8400-e29b-41d4-a716-446655440000" \
  --header "Authorization: Token YOUR_SECRET_API_KEY"

Responses

200 OK

Returns detailed information for the requested scheduled call.

401 Unauthorized

Invalid or missing authentication token.

404 Not Found

Scheduled call not found or item does not exist in the campaign.

422 Validation Error

Invalid UUID format for path parameters.

Example Response


Code
 
  {
    scheduled_item_id: "770e8400-e29b-41d4-a716-446655440000",
    campaign_id: "550e8400-e29b-41d4-a716-446655440000",
    call_state: "COMPLETED",
    to_phone_number: "+1234567890",
    agent_language: "en",
    metadata: {
      customer_name: "John Doe",
      segment: "premium",
      product: "personal_loan"
    },
    scheduled_time: "2024-06-01T10:30:00Z",
    actual_call_time: "2024-06-01T10:31:15Z",
    completion_time: "2024-06-01T10:35:00Z",
    call_duration: 225,
    attempt_count: 1,
    call_recording_url: "https://storage.vozzo.ai/recordings/recording_12345.wav",
    call_summary: "Customer confirmed receipt of information, asked about payment options",
    agent_notes: "Customer was responsive and provided positive feedback",
    call_metrics: {
      speech_duration: 185,
      silence_duration: 40,
      interaction_count: 12
    },
    created_at: "2024-05-30T14:20:00Z",
    updated_at: "2024-06-01T10:35:00Z"
  },
  null,
  2
)}

Common Pitfalls & Solutions

Invalid or expired authentication token

Solution: Ensure your API key is formatted correctly
as Token YOUR_SECRET_API_KEY (with the "Token" prefix).

Agent not found

Solution: Verify your agent UUID exists in the Vozzo platform and you have access to it.

Invalid phone number format

Solution: Use E.164 format with country code:

+[country_code][number] (e.g +911234567890)

Invalid date format

Solution:

YYYY-MM-DD format (e.g. 2026-01-04)

Metadata must be a valid JSON string

Solution: Ensure metadata is a JSON string, not an object.

Correct:"{"key":"value"}"

Incorrect:{"key":"value"}

Best Practices

Start Small

Begin with 2-5 test recipients before scaling to hundreds or thousands

Use Descriptive Names

Name campaigns clearly: "Q1_2026_Product_Launch" instead of "Campaign_1"

Set Realistic Time Windows

Consider recipient timezones and avoid early morning or late evening calls

Implement Error Handling

Always check response status codes and handle errors gracefully

Monitor Performance

Regularly check analytics to optimize retry settings and calling windows

Respect Privacy

Only call numbers with proper consent and follow local regulations

Next Steps

Explore API Reference

Dive deep into all available endpoints and parameters

View API Reference →

Support

Need help? We're here for you:

Email:support@vozzo.ai
Community Forum:Join discussions with other developers
Documentation:Comprehensive guides and examples
Issue Tracker:Report bugs and request features

Last modified on February 23, 2026

Introduction Introduction

Campaign Management

Campaign Quickstart

Get up and running with the Vozzo Campaign API in minutes. This guide will walk you through creating your first automated voice call campaign.

Prerequisites

Before you begin, ensure you have:

A Vozzo account with API access
Your API key (format: Token YOUR_SECRET_API_KEY)
An AI agent created and configured in your Vozzo account
The agent's UUID from the Vozzo platform
Test phone numbers in E.164 format (e.g., +91-xxxxxxxx)

Step 1: Verify Authentication

First, verify your API key is working correctly by checking your user information.

Code
 
curl --request GET \
  --url https://backend.vozzo.ai/v1alpha/auth/me \
  --header 'Authorization: Token YOUR_SECRET_API_KEY'

Expected Response:


Code
 
{
  "user_id": "880e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "name": "John Doe",
  "organization_id": 12345,
  "organization_name": "Example Corp",
  "permissions": ["campaign:read", "campaign:write"]
}

Step 2: Create Your First Campaign

Now let's create a simple campaign with two recipients. Replace the placeholders with your actual values.

Code
 
curl --request POST \
  --url https://backend.vozzo.ai/v1alpha/campaign \
  --header 'Authorization: Token YOUR_SECRET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "agent_uuid": "YOUR_AGENT_UUID",
    "campaign_name": "My First Campaign",
    "campaign_start_date": "2026-01-04",
    "campaign_end_date": "2026-01-10",
    "campaign_start_time": "09",
    "campaign_end_time": "18",
    "campaign_allow_weekends": false,
    "campaign_max_retry": 3,
    "campaign_max_retry_per_day": 1,
    "campaign_data": [
      {
        "to_phone_number": "+911234567890",
        "agent_language": "EN",
        "metadata": "{\"customer_name\":\"John Doe\",\"product\":\"premium_plan\"}"
      },
      {
        "to_phone_number": "+911234567891",
        "agent_language": "HI",
        "metadata": "{\"customer_name\":\"Priya Sharma\",\"product\":\"basic_plan\"}"
      }
    ]
  }'

Understanding the Request Parameters

Parameter	Description	Example
agent_uuid	Your AI agent's unique identifier	619ec26c-...
campaign_name	Human-readable campaign name	"My First Campaign"
campaign_start_date	Campaign start date (YYYY-MM-DD)	"2026-01-04"
campaign_end_date	Campaign end date (optional)	"2026-01-10"
campaign_start_time	Daily start hour (00-23)	"09" (9 AM)
campaign_end_time	Daily end hour (00-23)	"18" (6 PM)
campaign_allow_weekends	Allow calls on Sat/Sun	false
campaign_max_retry	Max total retry attempts (1-5)	3
campaign_max_retry_per_day	Max daily retries (1-5, optional)	1

Campaign Data Structure

Each recipient in campaign_data requires:


Code
 
{
  "to_phone_number": "+911234567890",
  "agent_language": "EN",
  "metadata": "{\"customer_name\":\"John Doe\",\"account_id\":\"ACC12345\"}"
}

to_phone_number: Phone number in E.164 format with country code
agent_language: Language code (EN, HI, BN, TA, TE, MR, etc.)
metadata: JSON string containing personalization data for the AI agent

Expected Response


Code
 
{
  "success": true,
  "message": "Campaign created successfully",
  "data": {
    "campaign_id": "550e8400-e29b-41d4-a716-446655440000",
    "campaign_name": "My First Campaign",
    "campaign_state": "TO_START",
    "campaign_start_date": "2026-01-04",
    "campaign_end_date": "2026-01-10",
    "org_id": 1,
    "created_at": "2026-01-03T14:30:00Z"
  }
}

Success! Save the campaign_id for monitoring and management.

Step 3: Monitor Your Campaign

Check Campaign Status

Code
 
curl --request GET \
  --url https://backend.vozzo.ai/v1alpha/campaign/550e8400-e29b-41d4-a716-446655440000 \
  --header 'Authorization: Token YOUR_SECRET_API_KEY'

View Scheduled Calls

Code
 
curl --request GET \
  --url 'https://backend.vozzo.ai/v1alpha/campaign/550e8400-e29b-41d4-a716-446655440000/items?page=1&page_size=10' \
  --header 'Authorization: Token YOUR_SECRET_API_KEY'

Get Campaign Analytics

Code
 
curl --request GET \
  --url https://backend.vozzo.ai/v1alpha/campaigns/analytics/550e8400-e29b-41d4-a716-446655440000 \
  --header 'Authorization: Token YOUR_SECRET_API_KEY'

Step 4: Start Your Campaign

When you're ready to begin calling, update the campaign status to RUNNING.

Code
 
curl --request POST \
  --url 'https://backend.vozzo.ai/v1alpha/campaign/update-campaign/550e8400-e29b-41d4-a716-446655440000/?campaign_status=RUNNING&campaign_allow_weekends=false' \
  --header 'Authorization: Token YOUR_SECRET_API_KEY'

Campaign States

TO_START

Campaign created but not yet active

RUNNING

Campaign actively processing calls

SUSPENDED

Campaign temporarily paused

ENDED

Campaign completed or terminated

How To Integrate API's

Create Campaign

Endpoint

POST {{baseUrl}}/v1alpha/campaign

Create a new outbound calling campaign with scheduling rules, retry logic, and campaign-specific call data.

Headers

Authorization

string · pattern:

^Token
YOUR_SECRET_API_KEY

· required

Your secret API key from Vozzo platform formatted as Token YOUR_SECRET_API_KEY

Field	Type	Required	Description
agent_uuid	string (uuid)	Yes	Unique identifier of the AI agent that will handle the calls. The agent must be created and configured in Vozzo before campaign creation.
campaign_name	string	Yes	Human-readable name for the campaign used for identification and reporting.
campaign_start_date	string (YYYY-MM-DD)	Yes	Start date for the campaign. Must be today or a future date.
campaign_end_date	string (YYYY-MM-DD)	No	Optional end date for the campaign. If not provided, the campaign runs indefinitely.
campaign_start_time	string (00–23)	Yes	Campaign start hour in 24-hour format. Defines the earliest hour calls can be made.
campaign_end_time	string (00–23)	Yes	Campaign end hour in 24-hour format. Must be after `campaign_start_time`.
campaign_allow_weekends	boolean	Yes	Whether calls are allowed on Saturdays and Sundays.
campaign_max_retry	integer (1–5)	Yes	Maximum total retry attempts per recipient, including the initial call.
campaign_max_retry_per_day	integer (1–5)	No	Optional maximum retry attempts per recipient per day. If not set, total retry limit is used.
campaign_data	object[]	Yes	List of recipients and call-specific parameters. Supports bulk operations with thousands of recipients.

curl --request POST \
  --url https://backend.vozzo.ai/v1alpha/campaign \
  --header 'Authorization: <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{ "agent_uuid": "619ec26c-4957-4926-70f8-fe7391b3527e", "campaign_name": "Winter Promotion 2024", "campaign_start_date": "2024-12-01", "campaign_end_date": "2024-12-31", "campaign_start_time": "09", "campaign_end_time": "18", "campaign_allow_weekends": false, "campaign_max_retry": 3, "campaign_max_retry_per_day": 1, "campaign_data": [{ "to_phone_number": "+911234567890", "agent_language": "EN", "metadata": "{\"customer_name\":\"John Doe\"}" }] }'

Example Request Body


Code
 
  {
      "agent_uuid": "619ec26c-4957-4926-70f8-fe7391b3527e",
      "campaign_name": "Winter Promotion 2024",
      "campaign_start_date": "2024-12-01",
      "campaign_end_date": "2024-12-31",
      "campaign_start_time": "09",
      "campaign_end_time": "18",
      "campaign_allow_weekends": false,
      "campaign_max_retry": 3,
      "campaign_max_retry_per_day": 1,
      "campaign_data": [
          {
          "to_phone_number": "+911234567890",
          "agent_language": "EN",
          "metadata": "{\\"customer_name\\":\\"John Doe\\",\\"account_id\\":\\"ACC12345\\",\\"product\\":\\"premium_plan\\"}"
          },
          {
          "to_phone_number": "+911234567891",
          "agent_language": "HI",
          "metadata": "{\\"customer_name\\":\\"Jane Smith\\",\\"account_id\\":\\"ACC12346\\",\\"product\\":\\"basic_plan\\"}"
          }
      ]
  }

Update Campaign

Endpoint

POST {{baseUrl}}/v1alpha/campaign/update-campaign/{campaign_id}/

Headers

Authorization

string · pattern:

^Token
YOUR_SECRET_API_KEY

· required

Your secret API key from Vozzo platform formatted as Token YOUR_SECRET_API_KEY

Path Parameters

campaign_id

stringuuidrequired

Unique identifier of the campaign to update

Query Parameters

campaign_allow_weekends

booleanrequired

Whether to allow calls on weekends

campaign_status

string · enum

Campaign status to update

Enum values: TO_START, RUNNING, SUSPENDED, ENDED

campaign_start_date

string · date

Updated start date in YYYY-MM-DD format

campaign_end_date

string · date

Updated end date for the campaign (optional)

campaign_max_retry

integer · min: 1 · max: 5

Maximum total retry attempts (1–5)

campaign_max_retry_per_day

integer · min: 1 · max: 5

Maximum retry attempts per day (1–5)

campaign_start_time

string · time

Start time in 24-hour format (00–23)

campaign_end_time

string · time

End time in 24-hour format (00–23)

curl --request POST \
  --url "https://backend.vozzo.ai/v1alpha/campaign/update-campaign/5804a5e5-97fd-4dc4-8d0d-87895734af7d?campaign_status=SUSPENDED&campaign_start_date=2026-01-01&campaign_end_date=2026-01-14&campaign_start_time=09&campaign_end_time=18&campaign_max_retry=4&campaign_max_retry_per_day=2&campaign_allow_weekends=false" \
  --header "Authorization: Token YOUR_SECRET_API_KEY"

Example Request

{
  "success": true,
  "message": "Campaign updated successfully",
  "data": {
    "campaign_id": "c5785fa5-8bdd-4629-b7ef-1addfc4b44a5",
    "org_id": 1,
    "campaign_state": "SUSPENDED",
    "campaign_start_date": "2026-01-01",
    "campaign_end_date": "2026-01-14",
    "campaign_config": {
      "campaign_name": "TEST",
      "retry_options": {
        "max_calls_total": 4,
        "max_calls_in_a_day": 4,
        "retry_delay": 60
      },
      "metadata": {},
      "timeslot_settings": {
        "timezone": "IST",
        "allow_on_weekends": false,
        "start_time": "09",
        "end_time": "18"
      },
      "preferred_timeslot": "ANYDAY",
      "encrypted_data": false,
      "internal_auth": false,
      "org_id": null,
      "post_call_action": null
    },
    "updated_at": "2025-12-26T12:51:40.253482+00:00"
  }
}

Get Campaigns List

Endpoint

GET {{baseUrl}}/v1alpha/campaigns

Retrieve a paginated list of all campaigns for the authenticated user. This endpoint provides a high-level overview of campaigns including their current state and basic information.

Headers

Authorization

string · pattern:

^Token
YOUR_SECRET_API_KEY

· required

Your secret API key from Vozzo platform formatted as Token YOUR_SECRET_API_KEY

Query Parameters

limit

integer · min: 1 · max: 100 · default: 20

Number of campaigns to return per page.

offset

integer · min: 0 · default: 0

Number of campaigns to skip for pagination.

state

string · enum

Filter campaigns by their current lifecycle state.

Example values: TO_START, RUNNING, SUSPENDED, COMPLETED, ENDED

curl --request GET \
  --url "https://backend.vozzo.ai/v1alpha/campaigns?limit=20&offset=0&state=RUNNING" \
  --header "Authorization: Token YOUR_SECRET_API_KEY"

Example Response

{
  "campaigns": [
    {
      "campaign_id": "550e8400-e29b-41d4-a716-446655440000",
      "campaign_name": "Summer Promotion",
      "campaign_state": "RUNNING",
      "agent_id": "660e8400-e29b-41d4-a716-446655440000",
      "created_at": "2024-01-15T10:30:00Z",
      "total_records": 150,
      "processed_records": 75
    }
  ],
  "total": 5,
  "limit": 20,
  "offset": 0
}

Get Campaign Details

Endpoint

GET {{baseUrl}}/v1alpha/campaign/{campaign_id}

Retrieve comprehensive information about a specific campaign including configuration, statistics, and current status. Use this endpoint for detailed campaign analysis and monitoring.

Headers

Authorization

string · pattern:

^Token
YOUR_SECRET_API_KEY

· required

Your secret API key from Vozzo platform formatted as Token YOUR_SECRET_API_KEY

Path Parameters

campaign_id

string · uuidrequired

Unique identifier of the campaign. Obtain this from the campaign creation response or campaigns list endpoint.

curl --request GET \
  --url "https://backend.vozzo.ai/v1alpha/campaign/550e8400-e29b-41d4-a716-446655440000" \
  --header "Authorization: Token YOUR_SECRET_API_KEY"

Example Response


Code
 
  {
    campaign_id: "550e8400-e29b-41d4-a716-446655440000",
    campaign_name: "Summer Promotion 2024",
    campaign_state: "RUNNING",
    agent_id: "660e8400-e29b-41d4-a716-446655440000",
    org_id: 12345,
    campaign_start_date: "2024-06-01T09:00:00Z",
    campaign_end_date: "2024-08-31T18:00:00Z",
    created_at: "2024-05-25T14:30:00Z",
    updated_at: "2024-06-15T16:45:00Z",
    campaign_data: {
      total_records: 150,
      processed_records: 75,
      successful_calls: 45,
      failed_calls: 5,
      pending_calls: 25,
    },
    campaign_config: {
      preferred_timeslot: "WEEKDAY_AFTERNOON",
      retry_options: {
        max_attempts: 3,
        delay_minutes: 60,
      },
      campaign_name: "Summer Promotion 2024",
    },
    campaign_report_summary: {
      successful_calls: 45,
      failed_calls: 5,
      pending_calls: 25,
      total_attempts: 75,
      average_call_duration: 125,
      completion_rate: 60.0,
    },
    campaign_schema_version: "1.0.0",
    active: true,
  },
  null,
  2
)}

Get Campaign Analytics

Endpoint

GET {{baseUrl}}/v1alpha/campaigns/analytics/{campaign_id}

Retrieve detailed analytics and metrics for a specific campaign including category breakdowns, goal achievements, success criteria, and tagging information.

Headers

Authorization

string · pattern:

^Token
YOUR_SECRET_API_KEY

· required

Your secret API key from Vozzo platform formatted as Token YOUR_SECRET_API_KEY

Path Parameters

campaign_id

string · uuidrequired

Unique identifier of the campaign to get analytics for.

curl --request GET \
  --url "https://backend.vozzo.ai/v1alpha/campaigns/analytics/5804a5e5-97fd-4dc-8d0d-87895734af7d" \
  --header "Authorization: Token YOUR_SECRET_API_KEY"

Responses

200 OK

Returns campaign analytics data.

401 Unauthorized

Invalid or missing authentication token.

404 Not Found

Campaign not found.

Example Response


Code
 
  {
    category: {
      "Account Identification Failed": 0,
      "Transferred to Agent": 0,
      "Others": 1,
    },
    goals: {
      "Account Identification": 1,
      "Resolved": 1,
    },
    success_criteria: {
      "Account Identification successe": 1,
      "No Callback Requested": 1,
    },
    tags: {
      "Account Identification Failed tags": 0,
      "Transferred to Agent tags": 0,
    },
  },
  null,
  2

Get Campaigns By Agent

Endpoint

GET {{baseUrl}}/v1alpha/campaigns/agent/{agent_uuid}

Retrieve a paginated list of campaigns managed by a specific agent, including campaign configuration, statistics, and performance metrics.

Headers

Authorization

string · pattern:

^Token
YOUR_SECRET_API_KEY

· required

Your secret API key from Vozzo platform formatted as Token YOUR_SECRET_API_KEY

Path Parameters

agent_uuid

string · uuidrequired

Unique identifier of the agent to retrieve campaigns for.

Query Parameters

page

integer · min: 1 · default: 1

Page number for pagination (1-based).

page_size

integer · min: 1 · max: 100 · default: 10

Number of campaigns per page.

curl --request GET \
  --url "https://backend.vozzo.ai/v1alpha/campaigns/agent/32f9e6e3-b535-4d2e-959d-c94cfd456a23" \
  --header "Authorization: Token YOUR_SECRET_API_KEY"

Responses

200 OK

Returns a list of campaigns managed by the agent.

401 Unauthorized

Invalid or missing authentication token.

404 Not Found

Agent not found or no campaigns available.

Example Response


Code
 
  [
    {
      campaign_id: "22af4c4a-6499-4936-b38d-9501473f7e37",
      campaign_name: "winter sale now",
      campaign_state: "RUNNING",
      agent_id: "32f9e6e3-b535-4d2e-959d-c94cfd456a23",
      campaign_start_date: "2025-11-18",
      campaign_end_date: null,
      campaign_report_summary: {
        total_calls: 1,
        total_calls_failed: 0,
        total_calls_completed: 1,
        total_calls_pending: 0,
        total_calls_in_progress: 0,
        total_calls_post_call_action_pending: 0,
        total_calls_user_defined_action_pending: 0
      },
      average_call_duration_seconds: 4.0
    }
  ],
  null,
  2

Get Campaigns Count By Agent

Endpoint

GET {{baseUrl}}/v1alpha/campaigns/agent/{agent_uuid}/count

Retrieve counts of campaigns for a specific agent, including total campaigns, active campaigns, and completed campaigns.

Headers

Authorization

string · pattern:

^Token
YOUR_SECRET_API_KEY

· required

Your secret API key from Vozzo platform formatted as Token YOUR_SECRET_API_KEY

Path Parameters

agent_uuid

string · uuidrequired

Unique identifier of the agent to get campaign counts for.

curl --request GET \
  --url "https://backend.vozzo.ai/v1alpha/campaigns/agent/32f9e6e3-b535-4d2e-959d-c94cfd456a23/count" \
  --header "Authorization: Token YOUR_SECRET_API_KEY"

Responses

200 OK

Returns campaign counts for the agent.

401 Unauthorized

Invalid or missing authentication token.

404 Not Found

Agent not found.

Example Response


Code
 
  {
    total_campaigns: 13,
    active_campaigns: 13,
    completed_campaigns: 0
  },
  null,
  2

Get Scheduled Calls

Endpoint

GET {{baseUrl}}/v1alpha/campaign/{campaign_id}/items

Retrieve all scheduled calls for a specific campaign with pagination. This endpoint provides visibility into individual call attempts, their status, and detailed call information.

Headers

Authorization

string · pattern:

^Token
YOUR_SECRET_API_KEY

· required

Your secret API key from Vozzo platform formatted as Token YOUR_SECRET_API_KEY

Path Parameters

campaign_idstring · uuidrequired

Unique identifier of the campaign. Must be an active campaign that you have access to.

Query Parameters

pageinteger · min: 1 · default: 1

Page number for pagination (1-based).

page_sizeinteger · min: 1 · max: 100 · default: 10

Number of call records to return per page.

curl --request GET \
  --url "https://backend.vozzo.ai/v1alpha/campaign/5804a5e5-97fd-4dc-8d0d-87895734af7d/items" \
  --header "Authorization: Token YOUR_SECRET_API_KEY"

Responses

200 OK

Returns a list of scheduled calls for the campaign.

401 Unauthorized

Invalid or missing authentication token.

404 Not Found

Campaign not found or you don’t have access to this campaign.

422 Validation Error

Invalid parameters (e.g., UUID format).

Example Response


Code
 
  [
    {
      scheduled_item_id: "27108280-91a6-4edf-ba9c-c9e593ef0f3e",
      campaign_id: "5804a5e5-97fd-4dc4-8d0d-87895734af7d",
      agent_id: "32f9e6e3-b535-4d2e-959d-c94cfd456a23",
      call_state: "COMPLETED",
      call_info: {
        agent_language: "Hindi",
        to_phone_number: "+916376526334",
        post_call_action: null
      },
      call_history: {
        actor: "vozzo-workflows:check_attempted_calls",
        status: "COMPLETED",
        conv_id: 14718,
        message: "Call completed after 2 attempt(s)",
        call_uuid: "07f95ec0-ef2c-4691-b3a9-3efcc844abd5",
        timestamp: "2025-12-16T10:48:06.603989"
      }
    }
  ],
  null,
  2
}

Get Scheduled Call Details

Endpoint

GET {{baseUrl}}/v1alpha/campaign/{campaign_id}/item/{scheduled_item_id}

Retrieve comprehensive information about a specific scheduled call including call logs, attempt history, and detailed results. Use this for detailed call analysis and troubleshooting.

Headers

Authorization

string · pattern:

^Token
YOUR_SECRET_API_KEY

· required

Your secret API key from Vozzo platform formatted as Token YOUR_SECRET_API_KEY

Path Parameters

campaign_idstring · uuidrequired

Unique identifier of the campaign containing the scheduled call.

scheduled_item_idstring · uuidrequired

Unique identifier of the specific scheduled call item.

curl --request GET \
  --url "https://backend.vozzo.ai/v1alpha/campaign/550e8400-e29b-41d4-a716-446655440000/item/770e8400-e29b-41d4-a716-446655440000" \
  --header "Authorization: Token YOUR_SECRET_API_KEY"

Responses

200 OK

Returns detailed information for the requested scheduled call.

401 Unauthorized

Invalid or missing authentication token.

404 Not Found

Scheduled call not found or item does not exist in the campaign.

422 Validation Error

Invalid UUID format for path parameters.

Example Response


Code
 
  {
    scheduled_item_id: "770e8400-e29b-41d4-a716-446655440000",
    campaign_id: "550e8400-e29b-41d4-a716-446655440000",
    call_state: "COMPLETED",
    to_phone_number: "+1234567890",
    agent_language: "en",
    metadata: {
      customer_name: "John Doe",
      segment: "premium",
      product: "personal_loan"
    },
    scheduled_time: "2024-06-01T10:30:00Z",
    actual_call_time: "2024-06-01T10:31:15Z",
    completion_time: "2024-06-01T10:35:00Z",
    call_duration: 225,
    attempt_count: 1,
    call_recording_url: "https://storage.vozzo.ai/recordings/recording_12345.wav",
    call_summary: "Customer confirmed receipt of information, asked about payment options",
    agent_notes: "Customer was responsive and provided positive feedback",
    call_metrics: {
      speech_duration: 185,
      silence_duration: 40,
      interaction_count: 12
    },
    created_at: "2024-05-30T14:20:00Z",
    updated_at: "2024-06-01T10:35:00Z"
  },
  null,
  2
)}

Common Pitfalls & Solutions

Invalid or expired authentication token

Solution: Ensure your API key is formatted correctly
as Token YOUR_SECRET_API_KEY (with the "Token" prefix).

Agent not found

Solution: Verify your agent UUID exists in the Vozzo platform and you have access to it.

Invalid phone number format

Solution: Use E.164 format with country code:

+[country_code][number] (e.g +911234567890)

Invalid date format

Solution:

YYYY-MM-DD format (e.g. 2026-01-04)

Metadata must be a valid JSON string

Solution: Ensure metadata is a JSON string, not an object.

Correct:"{"key":"value"}"

Incorrect:{"key":"value"}

Best Practices

Start Small

Begin with 2-5 test recipients before scaling to hundreds or thousands

Use Descriptive Names

Name campaigns clearly: "Q1_2026_Product_Launch" instead of "Campaign_1"

Set Realistic Time Windows

Consider recipient timezones and avoid early morning or late evening calls

Implement Error Handling

Always check response status codes and handle errors gracefully

Monitor Performance

Regularly check analytics to optimize retry settings and calling windows

Respect Privacy

Only call numbers with proper consent and follow local regulations

Next Steps

Explore API Reference

Dive deep into all available endpoints and parameters

View API Reference →

Support

Need help? We're here for you:

Email:support@vozzo.ai
Community Forum:Join discussions with other developers
Documentation:Comprehensive guides and examples
Issue Tracker:Report bugs and request features

Last modified on February 23, 2026

Introduction Introduction