Create a campaign

curl --request POST \
  --url https://voice-api.onclarity.com/v1/projects/{projectId}/campaigns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "March renewals",
  "agent_id": "5b7e9c1d-2a4f-4c6e-8d0b-1f3a5c7e9b24",
  "from_number": "+14155550100",
  "start_time": "2026-03-02T09:00:00-05:00",
  "retries": 2,
  "retry_delay_seconds": 3600,
  "max_concurrency": 5,
  "calling_window": {
    "start": "09:00",
    "end": "18:00",
    "days": [
      1,
      2,
      3,
      4,
      5
    ],
    "timezone": "America/New_York"
  },
  "items": [
    {
      "name": "Jane Doe",
      "phone_number": "+14155550123",
      "custom_vars": {
        "plan": "Premium",
        "renewal_date": "2026-03-31"
      }
    }
  ]
}
'

import requests

url = "https://voice-api.onclarity.com/v1/projects/{projectId}/campaigns"

payload = {
    "name": "March renewals",
    "agent_id": "5b7e9c1d-2a4f-4c6e-8d0b-1f3a5c7e9b24",
    "from_number": "+14155550100",
    "start_time": "2026-03-02T09:00:00-05:00",
    "retries": 2,
    "retry_delay_seconds": 3600,
    "max_concurrency": 5,
    "calling_window": {
        "start": "09:00",
        "end": "18:00",
        "days": [1, 2, 3, 4, 5],
        "timezone": "America/New_York"
    },
    "items": [
        {
            "name": "Jane Doe",
            "phone_number": "+14155550123",
            "custom_vars": {
                "plan": "Premium",
                "renewal_date": "2026-03-31"
            }
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'March renewals',
    agent_id: '5b7e9c1d-2a4f-4c6e-8d0b-1f3a5c7e9b24',
    from_number: '+14155550100',
    start_time: '2026-03-02T09:00:00-05:00',
    retries: 2,
    retry_delay_seconds: 3600,
    max_concurrency: 5,
    calling_window: {
      start: '09:00',
      end: '18:00',
      days: [1, 2, 3, 4, 5],
      timezone: 'America/New_York'
    },
    items: [
      {
        name: 'Jane Doe',
        phone_number: '+14155550123',
        custom_vars: {plan: 'Premium', renewal_date: '2026-03-31'}
      }
    ]
  })
};

fetch('https://voice-api.onclarity.com/v1/projects/{projectId}/campaigns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "campaign": {
    "id": "3f1c2a8e-6b0d-4f6e-9a51-0d2b7c9e4a10",
    "project_id": "8d2e4b1a-1c3f-4e5a-9b7d-6f0a2c4e8b13",
    "name": "March renewals",
    "agent_id": "5b7e9c1d-2a4f-4c6e-8d0b-1f3a5c7e9b24",
    "from_number": "+14155550100",
    "start_time": "2026-03-02T14:00:00.000Z",
    "callback": false,
    "retries": 2,
    "retry_delay_seconds": 3600,
    "max_concurrency": 5,
    "calling_window": {
      "start": "09:00",
      "end": "18:00",
      "days": [
        1,
        2,
        3,
        4,
        5
      ],
      "timezone": "America/New_York"
    },
    "status": "scheduled",
    "started_at": null,
    "canceled_at": null,
    "ended_at": null,
    "created_at": "2026-02-27T15:12:40.000Z",
    "updated_at": "2026-02-27T15:12:40.000Z"
  },
  "items": [
    {
      "id": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d",
      "campaign_id": "3f1c2a8e-6b0d-4f6e-9a51-0d2b7c9e4a10",
      "name": "Jane Doe",
      "phone_number": "+14155550123",
      "channel": "voice",
      "country": "US",
      "agent_id": null,
      "callback": false,
      "custom_vars": {
        "plan": "Premium",
        "renewal_date": "2026-03-31"
      },
      "status": "scheduled",
      "failed_reason": null,
      "attempt_count": 0,
      "conversation_id": null,
      "start_time": null,
      "next_attempt_at": null,
      "callback_requested": false,
      "callback_origin_item_id": null,
      "callback_target_item_id": null,
      "created_at": "2026-02-27T15:12:40.000Z",
      "updated_at": "2026-02-27T15:12:40.000Z"
    }
  ]
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "Invalid or revoked token"
}

{
  "error": "publish_capability_required",
  "code": "PUBLISH_CAPABILITY_REQUIRED"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "Agent \"Billing bot\" is not published yet — publish it before it can take calls",
  "code": "AGENT_NOT_PUBLISHED",
  "agent_id": "<string>"
}

{
  "error": "max_concurrency: Number must be greater than or equal to 5",
  "issues": [
    {
      "path": "max_concurrency",
      "code": "too_small",
      "message": "Number must be greater than or equal to 5",
      "minimum": 5
    }
  ]
}

Campaigns

Create a campaign

Creates an outbound calling campaign, optionally with its first contacts in items. Without a start_time the campaign is created as a draft and dials nobody until you start it. With a start_time it is scheduled and starts dialing on its own at that time (and within its calling_window, when set). The campaign’s agent, and any agent set on a contact, must belong to the project, be a voice agent that can place calls, and have a published version. Phone numbers that cannot be parsed are kept with status invalid and are never dialed.

POST

projects

{projectId}

campaigns

Create a campaign

curl --request POST \
  --url https://voice-api.onclarity.com/v1/projects/{projectId}/campaigns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "March renewals",
  "agent_id": "5b7e9c1d-2a4f-4c6e-8d0b-1f3a5c7e9b24",
  "from_number": "+14155550100",
  "start_time": "2026-03-02T09:00:00-05:00",
  "retries": 2,
  "retry_delay_seconds": 3600,
  "max_concurrency": 5,
  "calling_window": {
    "start": "09:00",
    "end": "18:00",
    "days": [
      1,
      2,
      3,
      4,
      5
    ],
    "timezone": "America/New_York"
  },
  "items": [
    {
      "name": "Jane Doe",
      "phone_number": "+14155550123",
      "custom_vars": {
        "plan": "Premium",
        "renewal_date": "2026-03-31"
      }
    }
  ]
}
'

import requests

url = "https://voice-api.onclarity.com/v1/projects/{projectId}/campaigns"

payload = {
    "name": "March renewals",
    "agent_id": "5b7e9c1d-2a4f-4c6e-8d0b-1f3a5c7e9b24",
    "from_number": "+14155550100",
    "start_time": "2026-03-02T09:00:00-05:00",
    "retries": 2,
    "retry_delay_seconds": 3600,
    "max_concurrency": 5,
    "calling_window": {
        "start": "09:00",
        "end": "18:00",
        "days": [1, 2, 3, 4, 5],
        "timezone": "America/New_York"
    },
    "items": [
        {
            "name": "Jane Doe",
            "phone_number": "+14155550123",
            "custom_vars": {
                "plan": "Premium",
                "renewal_date": "2026-03-31"
            }
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'March renewals',
    agent_id: '5b7e9c1d-2a4f-4c6e-8d0b-1f3a5c7e9b24',
    from_number: '+14155550100',
    start_time: '2026-03-02T09:00:00-05:00',
    retries: 2,
    retry_delay_seconds: 3600,
    max_concurrency: 5,
    calling_window: {
      start: '09:00',
      end: '18:00',
      days: [1, 2, 3, 4, 5],
      timezone: 'America/New_York'
    },
    items: [
      {
        name: 'Jane Doe',
        phone_number: '+14155550123',
        custom_vars: {plan: 'Premium', renewal_date: '2026-03-31'}
      }
    ]
  })
};

fetch('https://voice-api.onclarity.com/v1/projects/{projectId}/campaigns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "campaign": {
    "id": "3f1c2a8e-6b0d-4f6e-9a51-0d2b7c9e4a10",
    "project_id": "8d2e4b1a-1c3f-4e5a-9b7d-6f0a2c4e8b13",
    "name": "March renewals",
    "agent_id": "5b7e9c1d-2a4f-4c6e-8d0b-1f3a5c7e9b24",
    "from_number": "+14155550100",
    "start_time": "2026-03-02T14:00:00.000Z",
    "callback": false,
    "retries": 2,
    "retry_delay_seconds": 3600,
    "max_concurrency": 5,
    "calling_window": {
      "start": "09:00",
      "end": "18:00",
      "days": [
        1,
        2,
        3,
        4,
        5
      ],
      "timezone": "America/New_York"
    },
    "status": "scheduled",
    "started_at": null,
    "canceled_at": null,
    "ended_at": null,
    "created_at": "2026-02-27T15:12:40.000Z",
    "updated_at": "2026-02-27T15:12:40.000Z"
  },
  "items": [
    {
      "id": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d",
      "campaign_id": "3f1c2a8e-6b0d-4f6e-9a51-0d2b7c9e4a10",
      "name": "Jane Doe",
      "phone_number": "+14155550123",
      "channel": "voice",
      "country": "US",
      "agent_id": null,
      "callback": false,
      "custom_vars": {
        "plan": "Premium",
        "renewal_date": "2026-03-31"
      },
      "status": "scheduled",
      "failed_reason": null,
      "attempt_count": 0,
      "conversation_id": null,
      "start_time": null,
      "next_attempt_at": null,
      "callback_requested": false,
      "callback_origin_item_id": null,
      "callback_target_item_id": null,
      "created_at": "2026-02-27T15:12:40.000Z",
      "updated_at": "2026-02-27T15:12:40.000Z"
    }
  ]
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "Invalid or revoked token"
}

{
  "error": "publish_capability_required",
  "code": "PUBLISH_CAPABILITY_REQUIRED"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "Agent \"Billing bot\" is not published yet — publish it before it can take calls",
  "code": "AGENT_NOT_PUBLISHED",
  "agent_id": "<string>"
}

{
  "error": "max_concurrency: Number must be greater than or equal to 5",
  "issues": [
    {
      "path": "max_concurrency",
      "code": "too_small",
      "message": "Number must be greater than or equal to 5",
      "minimum": 5
    }
  ]
}

Authorizations

Authorization

string

header

required

Your organization API key (it starts with anek_org_). The same key works on the Voice API and the Support API. See Authentication.

Path Parameters

projectId

string

required

Project id

Body

application/json

name

string

required

Minimum string length: 1

agent_id

string | null

Agent that places the calls. Must be published.

Minimum string length: 1

from_number

string | null

Caller id to place the calls from (one of the project's outbound numbers).

Minimum string length: 1

start_time

string<date-time> | null

ISO 8601 with a UTC offset. Setting it schedules the campaign; omit to create a draft.

callback

boolean

default:false

Call people back when they ask for it during the call.

retries

integer

default:0

Required range: x >= 0

retry_delay_seconds

integer

default:0

Required range: x >= 0

max_concurrency

integer

default:5

Required range: 5 <= x <= 20

calling_window

object | null

A recurring window in which the campaign may dial. Outside it, contacts wait for the next window. When end is not after start the window runs past midnight (for example 22:00 to 02:00).

Show child attributes

items

object[]

Contacts to add now. More can be added later.

Show child attributes

Response

The campaign was created. Returns the campaign and the contacts that were added.

campaign

object

required

An outbound calling campaign.

Show child attributes

items

object[]

required

Show child attributes