Campaign Management

Campaign APIs & Data Export

The Vozzo Campaign API exposes REST endpoints for campaign management, analytics, scheduling, queue operations, and bulk exports.

This page covers authentication, request patterns, validation handling, and large-scale export workflows.

Authentication

All requests require a valid API token.

Authorization Header

Code
 
Authorization: Token vzt_YOUR_SECRET_API_KEY
Content-Type: application/json

API keys are available from your Vozzo dashboard settings.

API Categories

The Campaign API is organized into several operational groups.

Campaign Management

Create, update, pause, resume, and monitor campaigns.

Scheduling & Retries

Configure retry behavior, timeslots, and scheduling windows.

Analytics APIs

Access campaign metrics, dispositions, and AI-generated insights.

Export APIs

Download CSV exports and large-scale operational datasets.

Common Response Patterns

Paginated Responses

List endpoints return standardized pagination wrappers.


Code
 
{
  "items": [],
  "total": 120,
  "limit": 20,
  "offset": 0
}

Common Query Parameters

Parameter	Description
`limit`	Number of records to return
`offset`	Pagination offset
`state`	Filter campaigns by state
`disposition`	Filter call items by outcome

Validation Errors

The API validates payloads before processing requests.

Validation failures return:

Code
 
422 Unprocessable Entity

Example Response


Code
 
{
  "detail": [
    {
      "loc": ["body", "campaign_config", "retry_options", "max_calls_total"],

      "msg": "Input should be less than or equal to 5",

      "type": "less_than_equal_to_5"
    }
  ]
}

Common Validation Rules

Retry Limits

max_calls_total must be between 1 and 5.

UUID Validation

UUID parameters must use valid 36-character UUID formats.

metadata Format

metadata fields must contain valid stringified JSON.

Error Handling

The API returns structured error responses for failed requests.

Example Error


Code
 
{
  "detail": "Campaign not found",
  "code": "CAMPAIGN_NOT_FOUND",
  "request_id": "req_5f2c710d"
}

Common HTTP Errors

Status	Code	Description
`400`	`INVALID_PAYLOAD`	Invalid request body or parameters
`401`	`UNAUTHORIZED`	Missing or invalid API token
`403`	`INSUFFICIENT_SCOPE`	Missing permissions
`404`	`CAMPAIGN_NOT_FOUND`	Campaign UUID not found
`422`	`VALIDATION_ERROR`	Request validation failed
`500`	`INTERNAL_ERROR`	Internal platform error

Export APIs

For large datasets, Vozzo provides streaming export endpoints.

Single Campaign Export

Code
 
GET /v1alpha/campaign/{campaign_id}/items/download

Multi-Campaign Export

Code
 
POST /v1alpha/campaign/items/download_csv_by_ids

Streaming Export Notes

Large Dataset Recommendation

Export APIs stream binary data directly from the backend. Write responses directly to disk instead of loading entire files into memory.

Example Streaming Download

Python


Code
 
import requests

API_KEY = "vzt_YOUR_SECRET_KEY"

headers = {
    "Authorization": f"Token {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "campaign_ids": [
        "campaign_uuid_1",
        "campaign_uuid_2"
    ]
}

url = "https://backend.vozzo.ai/v1alpha/campaign/items/download_csv_by_ids"

with requests.post(url, headers=headers, json=payload, stream=True) as response:
    with open("campaign_export.csv", "wb") as file:
        for chunk in response.iter_content(chunk_size=8192):
            if chunk:
                file.write(chunk)

print("Download completed")

Operational Recommendations

Best Practices

• Reuse shared HTTP clients for high-volume integrations.
• Stream exports directly to storage for large campaigns.
• Implement retry/backoff handling for 5xx responses.
• Validate metadata JSON before sending requests.

Next Steps

Campaign Introduction

Review campaign architecture, lifecycle states, and workflows.

Multi-Campaign Operations

Aggregate analytics, combined queues, and bulk exports.

Campaign API • v1alpha

Last modified on July 24, 2026

Quickstart Creating & Scheduling

API Categories

The Campaign API is organized into several operational groups.

Campaign Management

Create, update, pause, resume, and monitor campaigns.

Scheduling & Retries

Configure retry behavior, timeslots, and scheduling windows.

Analytics APIs

Access campaign metrics, dispositions, and AI-generated insights.

Export APIs

Download CSV exports and large-scale operational datasets.

Parameter

Description

limit

Number of records to return

offset

Pagination offset

state

Filter campaigns by state

disposition

Filter call items by outcome

Validation Errors

The API validates payloads before processing requests.

Validation failures return:

Code

422 Unprocessable Entity

Example Response

Code

{
  "detail": [
    {
      "loc": ["body", "campaign_config", "retry_options", "max_calls_total"],

      "msg": "Input should be less than or equal to 5",

      "type": "less_than_equal_to_5"
    }
  ]
}

Status

Code

Description

400

INVALID_PAYLOAD

Invalid request body or parameters

401

UNAUTHORIZED

Missing or invalid API token

403

INSUFFICIENT_SCOPE

Missing permissions

404

CAMPAIGN_NOT_FOUND

Campaign UUID not found

422

VALIDATION_ERROR

Request validation failed

500

INTERNAL_ERROR

Internal platform error

Python

Code

import requests

API_KEY = "vzt_YOUR_SECRET_KEY"

headers = {
    "Authorization": f"Token {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "campaign_ids": [
        "campaign_uuid_1",
        "campaign_uuid_2"
    ]
}

url = "https://backend.vozzo.ai/v1alpha/campaign/items/download_csv_by_ids"

with requests.post(url, headers=headers, json=payload, stream=True) as response:
    with open("campaign_export.csv", "wb") as file:
        for chunk in response.iter_content(chunk_size=8192):
            if chunk:
                file.write(chunk)

print("Download completed")