Create a campaign

POST

api

account

{account_id}

campaigns

Create a campaign

curl --request POST \
  --url https://api.vobiz.ai/api/v1/account/{account_id}/campaigns \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <x-auth-id>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "name": "<string>",
  "agent_id": "<string>",
  "max_concurrent": 123,
  "timezone": "<string>",
  "caller_id_strategy": "<string>"
}
'

import requests

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

payload = {
    "name": "<string>",
    "agent_id": "<string>",
    "max_concurrent": 123,
    "timezone": "<string>",
    "caller_id_strategy": "<string>"
}
headers = {
    "X-Auth-ID": "<x-auth-id>",
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-ID': '<x-auth-id>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '<string>',
    agent_id: '<string>',
    max_concurrent: 123,
    timezone: '<string>',
    caller_id_strategy: '<string>'
  })
};

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

POST https://api.vobiz.ai/api/v1/account/{account_id}/campaigns

A campaign links an agent to a contact list and defines concurrency, caller-ID selection, scheduling, daily windows, and retry behaviour. New campaigns start in draft.

Authentication required

X-Auth-ID — your Vobiz account ID
X-Auth-Token — your Vobiz auth token

string

required

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

string

required

Your Vobiz account ID, for example MA_XXXXXXXX.

string

required

Campaign name. Maximum 100 characters.

string

required

ID of an existing agent.

integer

required

Maximum simultaneous calls. At least 1, and no higher than the account concurrency limit.

string

required

IANA timezone such as Asia/Kolkata. Governs the daily window and daily pool limits.

string

required

fixed, per_contact, or pool.

string

Required when the strategy is fixed. E.164 format.

integer

Retained for backward compatibility. Values below 1 normalise to 1. CPS does not gate campaign capacity — use max_concurrent.

string

ISO 8601 timestamp for a scheduler-based launch instead of an immediate start.

boolean

default:"false"

Enables the daily calling window.

string

Required when the window is enabled. HH:mm in the campaign timezone.

string

Required when the window is enabled. Must differ from the start time.

integer

default:"0"

Retries after the initial attempt. Range 0–5.

array

Delay in minutes before each retry, for example [60, 240].

integer

default:"7"

Maximum number of days retries may span.

string

Target for signed campaign and contact webhooks.

Example

cURL

curl -X POST \
  "https://api.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}",
    "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 — the upload fails if the column is missing.

Set the strategy to pool, then add numbers before launch.Pool campaigns also accept pool_rotation_strategy (round_robin, least_used, or random), pool_max_calls_per_number, pool_max_calls_per_day, and pool_cooldown_seconds.

Create a campaign

curl --request POST \
  --url https://api.vobiz.ai/api/v1/account/{account_id}/campaigns \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <x-auth-id>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "name": "<string>",
  "agent_id": "<string>",
  "max_concurrent": 123,
  "timezone": "<string>",
  "caller_id_strategy": "<string>"
}
'

import requests

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

payload = {
    "name": "<string>",
    "agent_id": "<string>",
    "max_concurrent": 123,
    "timezone": "<string>",
    "caller_id_strategy": "<string>"
}
headers = {
    "X-Auth-ID": "<x-auth-id>",
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-ID': '<x-auth-id>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '<string>',
    agent_id: '<string>',
    max_concurrent: 123,
    timezone: '<string>',
    caller_id_strategy: '<string>'
  })
};

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

​Example

​Caller-ID strategies

Example

Caller-ID strategies