Campaigns API

POST

api

account

{account_id}

campaigns

Campaigns API

curl --request POST \
  --url https://campaign.vobiz.ai/api/v1/account/{account_id}/campaigns \
  --header 'X-Auth-ID: <x-auth-id>' \
  --header 'X-Auth-Token: <api-key>'

import requests

url = "https://campaign.vobiz.ai/api/v1/account/{account_id}/campaigns"

headers = {
    "X-Auth-ID": "<x-auth-id>",
    "X-Auth-Token": "<api-key>"
}

response = requests.post(url, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Auth-ID': '<x-auth-id>', 'X-Auth-Token': '<api-key>'}
};

fetch('https://campaign.vobiz.ai/api/v1/account/{account_id}/campaigns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

A campaign links an agent to contacts and defines concurrency, caller-ID selection, scheduling, daily windows, and retry behavior.

account_id

string

required

Your Vobiz account ID. Use the same value in X-Auth-ID.

X-Auth-ID

string

required

Your Vobiz account ID, for example MA_XXXXXXXX.

Endpoints

Method	Path	Description
`POST`	`/api/v1/account/{account_id}/campaigns`	Create a draft campaign.
`GET`	`/api/v1/account/{account_id}/campaigns`	List active or archived campaigns.
`GET`	`/api/v1/account/{account_id}/campaigns/{campaign_id}`	Retrieve a campaign and its health.
`PUT`	`/api/v1/account/{account_id}/campaigns/{campaign_id}`	Update a `draft` or `ready` campaign.
`GET`	`/api/v1/account/{account_id}/campaigns/{campaign_id}/call-lookup/{call_uuid}`	Validate campaign ownership of a call.

Create a campaign

Field	Required	Description
`name`	Yes	Campaign name. Maximum 100 characters.
`agent_id`	Yes	ID of an existing agent.
`cps`	No	Retained for compatibility. Values below `1` normalize to `1`; CPS does not gate campaign capacity.
`max_concurrent`	Yes	At least `1` and no higher than the account concurrency limit.
`timezone`	Yes	IANA timezone such as `Asia/Kolkata`.
`caller_id_strategy`	Yes	`fixed`, `per_contact`, or `pool`.
`fixed_caller_id`	Conditional	Required for `fixed`. Use E.164 format.
`scheduled_at`	No	ISO 8601 timestamp for scheduler-based launch.
`window_enabled`	No	Enables the daily calling window.
`window_start_time`	Conditional	Required when the window is enabled. `HH:mm` format.
`window_end_time`	Conditional	Required when enabled and must differ from the start time.
`retry_attempts`	No	Retries after the initial attempt. Range `0`–`5`.
`retry_delays`	No	Delay in minutes for each retry.
`retry_window_days`	No	Maximum retry window. Defaults to `7`.
`notify_url`	No	Target for signed campaign and contact webhooks.

Fixed caller ID

cURL

curl -X POST \
  "https://campaign.vobiz.ai/api/v1/account/{account_id}/campaigns" \
  -H "X-Auth-ID: {account_id}" \
  -H "X-Auth-Token: {auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Appointment Reminders",
    "agent_id": "{agent_id}",
    "cps": 3,
    "max_concurrent": 10,
    "timezone": "Asia/Kolkata",
    "caller_id_strategy": "fixed",
    "fixed_caller_id": "+919876543210",
    "window_enabled": true,
    "window_start_time": "09:00",
    "window_end_time": "18:00",
    "retry_attempts": 2,
    "retry_delays": [60, 240],
    "retry_window_days": 7,
    "notify_url": "https://example.com/campaign-webhooks"
  }'

The response is 201 with a draft campaign. Upload contacts to move it to ready.

Caller-ID strategies

Fixed
Per contact
Pool

Set caller_id_strategy to fixed and supply fixed_caller_id. Every attempt uses the same number.

Set the strategy to per_contact. Every CSV row must contain a from value. Upload fails if the column is missing.

Set the strategy to pool, configure rotation and limits, then add numbers through the caller pool endpoints before launch.pool_rotation_strategy accepts round_robin, least_used, or random. You can also set pool_max_calls_per_number, pool_max_calls_per_day, and pool_cooldown_seconds.

List campaigns

Use limit and offset for pagination. Active campaigns are returned by default.

GET /api/v1/account/{account_id}/campaigns?limit=20&offset=0
GET /api/v1/account/{account_id}/campaigns?archived=true&limit=20&offset=0

Archived campaigns are read-only. Their contacts, CDRs, and statistics remain available.

Retrieve health

The campaign response includes status, outcome counters, capacity settings, caller-ID strategy, schedule, daily window, pause reason, webhook URL, and timestamps. For a running campaign, health is computed from recent dial activity:

active — calls are being placed.
idle — running but currently not dialing, for example while account capacity is saturated.
stalled — no recent dial beyond the watchdog threshold.
not_started — no dial has occurred.

Update a campaign

You can update a campaign only while it is draft or ready. Every request field is optional. Use clear_schedule: true to remove an existing schedule. max_concurrent must remain within the account limit.

Campaign agents API

Campaign controls API

Campaigns API

curl --request POST \
  --url https://campaign.vobiz.ai/api/v1/account/{account_id}/campaigns \
  --header 'X-Auth-ID: <x-auth-id>' \
  --header 'X-Auth-Token: <api-key>'

import requests

url = "https://campaign.vobiz.ai/api/v1/account/{account_id}/campaigns"

headers = {
    "X-Auth-ID": "<x-auth-id>",
    "X-Auth-Token": "<api-key>"
}

response = requests.post(url, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Auth-ID': '<x-auth-id>', 'X-Auth-Token': '<api-key>'}
};

fetch('https://campaign.vobiz.ai/api/v1/account/{account_id}/campaigns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

​Endpoints

​Create a campaign

​Fixed caller ID

​Caller-ID strategies

​List campaigns

​Retrieve health

​Update a campaign

Endpoints

Create a campaign

Fixed caller ID

Caller-ID strategies

List campaigns

Retrieve health

Update a campaign