> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev.setoo.work/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create campaign

> Create a new outbound voice calling campaign

Creates a new outbound voice calling campaign. A campaign requires an **agent**, a **voice number**, and a **contact list** (which must contain at least 2 contacts before starting).

<Note>
  Creating a campaign creates it in `DRAFT` status (or `SCHEDULED` if `scheduledAt` is supplied). Outbound dialing begins once you call [`POST /campaigns/{id}/start`](/docs/api-reference/campaigns/start-campaign) or when the scheduled start time arrives.
</Note>

### Body parameters

<ParamField body="name" type="string" required>
  Unique campaign name across your tenant.
</ParamField>

<ParamField body="agentId" type="string" required>
  UUID of the AI voice agent that will handle conversations.
</ParamField>

<ParamField body="voiceNumberId" type="string" required>
  UUID of the purchased voice number to dial from. List numbers via [`GET /voice-numbers`](/docs/api-reference/numbers/list-voice-numbers).
</ParamField>

<ParamField body="contactListId" type="string" required>
  UUID of the contact list to dial. A minimum of 2 contacts in the list is required to start dialing.
</ParamField>

<ParamField body="description" type="string">
  Optional description or objective of the campaign.
</ParamField>

<ParamField body="scheduledAt" type="string">
  ISO-8601 timestamp to automatically start dialing (e.g. `2026-06-10T09:00:00.000Z`). If provided, status is set to `SCHEDULED`.
</ParamField>

<ParamField body="timezone" type="string" default="Asia/Kolkata">
  IANA timezone identifier used to evaluate calling windows (e.g. `America/New_York`, `UTC`, `Asia/Kolkata`).
</ParamField>

<ParamField body="callWindowStart" type="string" default="00:00">
  Earliest time of day allowed to place calls in `HH:mm` format (e.g. `09:00`).
</ParamField>

<ParamField body="callWindowEnd" type="string" default="23:59">
  Latest time of day allowed to place calls in `HH:mm` format (e.g. `18:00`).
</ParamField>

<ParamField body="callDays" type="integer[]" default="[1,2,3,4,5,6,7]">
  Allowed days of the week to place calls (`1` = Monday through `7` = Sunday).
</ParamField>

<ParamField body="dialTimeout" type="integer" default="60">
  Number of seconds to let a call ring before timing out. Must be between 10 and 300 seconds.
</ParamField>

<ParamField body="maxAttempts" type="integer" default="3">
  Maximum dial attempts per contact before marking as unreached. Must be between 1 and 10.
</ParamField>

<ParamField body="redialDelayMin" type="integer" default="30">
  Minutes to wait before redialing an unanswered or busy contact. Minimum 1 minute.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value metadata attached to the campaign.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.agentic-os.com/api/v1/campaigns \
    -H "Authorization: Bearer $AGENTIC_OS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Q3 Renewal Outreach",
      "agentId": "11111111-1111-1111-1111-111111111111",
      "voiceNumberId": "22222222-2222-2222-2222-222222222222",
      "contactListId": "33333333-3333-3333-3333-333333333333",
      "callWindowStart": "09:00",
      "callWindowEnd": "18:00",
      "callDays": [1, 2, 3, 4, 5],
      "dialTimeout": 45,
      "maxAttempts": 3,
      "redialDelayMin": 60,
      "timezone": "America/New_York"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.agentic-os.com/api/v1/campaigns",
      headers={
          "Authorization": f"Bearer {API_KEY}",
          "Content-Type": "application/json",
      },
      json={
          "name": "Q3 Renewal Outreach",
          "agentId": "11111111-1111-1111-1111-111111111111",
          "voiceNumberId": "22222222-2222-2222-2222-222222222222",
          "contactListId": "33333333-3333-3333-3333-333333333333",
          "callWindowStart": "09:00",
          "callWindowEnd": "18:00",
          "callDays": [1, 2, 3, 4, 5],
          "dialTimeout": 45,
          "maxAttempts": 3,
          "redialDelayMin": 60,
          "timezone": "America/New_York",
      },
  )
  print(response.json())
  ```

  ```javascript Node theme={null}
  const response = await fetch("https://api.agentic-os.com/api/v1/campaigns", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Q3 Renewal Outreach",
      agentId: "11111111-1111-1111-1111-111111111111",
      voiceNumberId: "22222222-2222-2222-2222-222222222222",
      contactListId: "33333333-3333-3333-3333-333333333333",
      callWindowStart: "09:00",
      callWindowEnd: "18:00",
      callDays: [1, 2, 3, 4, 5],
      dialTimeout: 45,
      maxAttempts: 3,
      redialDelayMin: 60,
      timezone: "America/New_York",
    }),
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "id": "770e8400-e29b-41d4-a716-446655440000",
  "tenantId": "990e8400-e29b-41d4-a716-446655440000",
  "name": "Q3 Renewal Outreach",
  "description": null,
  "agentId": "11111111-1111-1111-1111-111111111111",
  "voiceNumberId": "22222222-2222-2222-2222-222222222222",
  "contactListId": "33333333-3333-3333-3333-333333333333",
  "status": "DRAFT",
  "totalContacts": 150,
  "dialedContacts": 0,
  "answeredContacts": 0,
  "dialTimeout": 45,
  "maxAttempts": 3,
  "redialDelayMin": 60,
  "scheduledAt": null,
  "timezone": "America/New_York",
  "callWindowStart": "09:00",
  "callWindowEnd": "18:00",
  "callDays": [1, 2, 3, 4, 5],
  "metadata": {},
  "createdAt": "2026-06-01T10:00:00.000Z",
  "updatedAt": "2026-06-01T10:00:00.000Z"
}
```