---
title: "Create a voice campaign and start outbound calling."
method: POST
path: "/v1/voice_campaigns"
tags: ["Voice Campaigns"]
---

# Create a voice campaign and start outbound calling.

`POST /v1/voice_campaigns`

## Request

- Base URL: `https://api.capacity.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.capacity.com/v1/voice_campaigns`
- Auth: one of:
  - API key in header `x-capacity-id`
  - HTTP bearer

Creates and schedules a voice campaign. The contacts to dial can be supplied two ways:

- **Inline contacts**: omit `contact_list_id` and provide a non-empty `contacts` array. A new contact list is created from `name`, the contacts are bulk-upserted into it, and the campaign is scheduled against it.
- **Existing list**: supply `contact_list_id` referencing a list already in the caller's org. The campaign is scheduled against that list directly; any `contacts` array sent alongside is ignored. The list must contain at least one contact with both a primary phone number and a timezone.

Either `contact_list_id` or a non-empty `contacts` array is required.

## Request body

- VoiceCampaignPostSchema
  - `name` string, required: Display name for the campaign and its underlying contact list.
  - `from_number` string, required: E.164-formatted outbound phone number.
  - `exchange_id` integer, required: Exchange ID that handles the call once the destination answers.
  - `contact_list_id` integer: ID of an existing contact list to use for this campaign. Mutually exclusive with contacts. The list must belong to the caller's org and contain at least one contact with both a primary phone number and a timezone.
  - `contacts` VoiceCampaignContactSchema[]: Optional when `contact_list_id` is supplied; if both are supplied, `contacts` is ignored. Required (non-empty) when `contact_list_id` is omitted.
    - `to_number` string, required: E.164-formatted destination phone number.
    - `timezone` string, required: IANA timezone for the contact (e.g. "America/Chicago").
  - `send_window` VoiceCampaignSendWindowSchema, required: Daily calling window for the campaign. `start` and `end` are applied in each contact's local timezone, so a single campaign reaches every contact during their own waking hours. The `timezone` field on the send window is primarily for UI display of start time, etc.
    - `timezone` string, required: IANA timezone for the campaign (e.g. `America/Chicago`).
    - `start` string, required: Window start in HH:MM, evaluated in each contact's timezone. Must be 08:00 or later.
    - `end` string, required: Window end in HH:MM, evaluated in each contact's timezone. Must be 21:00 or earlier and after start.
  - `start_time_utc` string, date-time: UTC timestamp for the first dial attempt. Defaults to now if omitted.
  - `repeat_interval_hours` integer: Hours between campaign repeats.
  - `retry_attempts` integer: Maximum dial attempts per contact (0-3).
  - `dial_to_agent_ratio` integer: Number of simultaneous dials per available agent.
  - `repeat_end_utc` string, date-time: UTC timestamp after which the campaign stops repeating.

## Response `201`

The created campaign.

- VoiceCampaignSchema: Campaign object.
  - `id` string
  - `userId` string
  - `orgId` string
  - `timeZone` string
  - `name` string
  - `outboundNumber` string
  - `contactListId` string
  - `status` string
  - `exchangeId` string
  - `startTimeWindow` string, date-time
  - `endTimeWindow` string, date-time
  - `startTime` string, date-time
  - `repeatInterval` integer
  - `repeatEnd` string, date-time
  - `retryAttempts` integer
  - `dialToAgentRatio` integer
  - `createdAt` string, date-time

## Other responses

- `400`: The request contains malformed data or violates data integrity
- `422`: The request was well-formed but was unable to be followed due to semantic errors. This is usually due to the request data failing to pass validations.

---

[API](https://skmtc.dev/capacity/apis/capacity-api-docs.md) - [All operations](https://skmtc.dev/capacity/apis/capacity-api-docs/llms.txt) - [OpenAPI document](https://skmtc.dev/capacity/apis/capacity-api-docs/revisions/74c85bb61004?raw)