Create a campaign agent

POST

api

account

{account_id}

campaign

agents

Create a campaign agent

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

import requests

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

payload = {
    "name": "<string>",
    "answer_url": "<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>', answer_url: '<string>'})
};

fetch('https://api.vobiz.ai/api/v1/account/{account_id}/campaign/agents', 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}/campaign/agents

An agent is a reusable webhook configuration shared by multiple campaigns. It defines what Vobiz calls when a contact answers and, optionally, when the call ends.

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

Agent name. Unique per account, maximum 100 characters.

string

required

HTTPS URL called when the contact answers. Must return Vobiz XML.

string

default:"POST"

HTTP method for answer_url. GET or POST.

string

URL called when the call ends.

string

default:"POST"

HTTP method for hangup_url. GET or POST.

array

Array of { key, value } objects sent as SIP headers on every call placed by this agent.

Example

cURL

curl -X POST \
  "https://api.vobiz.ai/api/v1/account/{account_id}/campaign/agents" \
  -H "X-Auth-ID: {account_id}" \
  -H "X-Auth-Token: {auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment Reminder Agent",
    "answer_url": "https://example.com/answer",
    "answer_method": "POST",
    "hangup_url": "https://example.com/hangup",
    "hangup_method": "POST",
    "static_headers": [
      { "key": "X-Campaign-Type", "value": "reminder" },
      { "key": "X-Version", "value": "1" }
    ]
  }'

Response

201 Created

{
  "id": "9f1c4b6a-2f0e-4a3d-8b21-6c5f0d9a7e42",
  "name": "Appointment Reminder Agent",
  "answer_url": "https://example.com/answer",
  "answer_method": "POST",
  "hangup_url": "https://example.com/hangup",
  "hangup_method": "POST",
  "static_headers": [
    { "key": "X-Campaign-Type", "value": "reminder" }
  ],
  "created_at": "2026-08-28T09:14:22Z"
}

Save the returned id and pass it as agent_id when you create a campaign.

A launch takes a frozen agent snapshot. Editing an agent does not change campaigns that are already running or queued — the next launch uses the updated values.

Create a campaign agent

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

import requests

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

payload = {
    "name": "<string>",
    "answer_url": "<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>', answer_url: '<string>'})
};

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

​Example

​Response

Example

Response