---
title: "Create Campaign"
method: POST
path: "/v2/campaigns"
tags: ["Campaigns"]
---

# Create Campaign

`POST /v2/campaigns`

## Request

- Base URL: `https://api.carecycle.ai`
- URL: `https://api.carecycle.ai/v2/campaigns`
- Auth: API key in header `x-api-key`

Create a new campaign as a draft. You can start from a template.

## Request body

- PostV2CampaignsRequestBody
  - `callerIdSource` 'client_main' | 'campaign_pool'
  - `name` string: Campaign name. A missing or blank name becomes "Untitled campaign".
  - `description` string, nullable: Campaign description
  - `templateId` string, uuid, nullable: Optional campaign template ID
  - `maxConcurrentCalls` integer, nullable: Optional Pulse call concurrency cap for this campaign
  - `direction` 'inbound' | 'outbound': Campaign direction
  - `kind` 'voice_ai' | 'agent_first': Campaign kind (defaults to voice_ai)
  - `dialerConfig` object, nullable
    - `voicemailMessage` string
    - `dialingRatio` number: Agent-first dials allowed per ready agent. 1 = progressive (default). Values above 1 over-dial to offset unanswered calls and can produce abandoned calls.

## Response `200`

POST /v2/campaigns Positive response

- PostV2CampaignsPositiveResponse
  - `campaign` object, required: Created campaign data
    - `id` string, uuid, required
    - `createdAt` string, date-time, nullable, required
    - `updatedAt` string, date-time, nullable, required
    - `configurationRevision` integer, required
    - `startDate` string, date-time, nullable, required
    - `endDate` string, date-time, nullable, required
    - `dialAfterhours` boolean, nullable, required
    - `primaryVoicemailGreeting` string, nullable
    - `afterHoursVoicemailGreeting` string, nullable
    - `name` string, required
    - `templateId` string, uuid, nullable, required
    - `templateName` string, nullable
    - `lastModifiedByName` string, nullable
    - `lastModifiedByIsStaff` boolean
    - `description` string, nullable, required
    - `tags` string[], required
    - `isReceptionist` boolean, required
    - `isSample` boolean, required: The campaign walkthrough's practice campaign. It can't go live and is removed when the walkthrough ends.
    - `callerIdSource` 'client_main' | 'campaign_pool', required
    - `status` 'draft' | 'active' | 'paused' | 'completed' | 'archived' | 'cancelled', required
    - `direction` 'inbound' | 'outbound', required
    - `pulseWorkflowId` string, uuid, nullable
    - `maxConcurrentCalls` integer, nullable, required
    - `vertical` 'aca' | 'medicare' | 'hospital_indemnity' | 'home_health_care' | 'final_expense' | 'null', nullable
    - `kind` 'voice_ai' | 'agent_first', required
    - `dialerConfig` object, nullable: Agent-first campaign voicemail defaults
      - `voicemailMessage` string
      - `dialingRatio` number: Agent-first dials allowed per ready agent. 1 = progressive (default). Values above 1 over-dial to offset unanswered calls and can produce abandoned calls.
    - `compatibilityWarnings` object[], required
      - `code` 'appointment_fallback_ignored_for_agent_first' | 'agent_first_callback_ignored_for_voice_ai', required
      - `message` string, required
    - `smsCompanyName` string, required: Client company name for SMS
    - `requiredVars` string[], required
    - `client` object, nullable, required
      - `id` string, uuid, required
      - `smsCompanyName` string
    - `hasInquiryCallback` boolean, required: Whether campaign has inquiry callback assistant
    - `customerStats` object, required
      - `total` number, required: Total customers in campaign
      - `totalCalls` number, required: Total calls made
      - `todayCalls` number, required: Calls made today
      - `todayInboundCalls` number, required: Inbound calls today
      - `todayOutboundCalls` number, required: Outbound calls today
      - `todayConnectRate` number, nullable, required
      - `todayDurationMs` number, required: Total call duration today in ms
      - `statusCounts` object, required
        - `expired` number, required
        - `failed` number, required
        - `pending` number, required
        - `completed` number, required
        - `exceeded_max_calls` number, required
        - `in_progress` number, required
        - `cancelled` number, required
        - `skipped` number, required
    - `transferConfig` object, nullable, required
      - `id` string, uuid, required
      - `clientId` string, uuid, nullable, required
      - `name` string, nullable, required
      - `description` string, nullable, required
      - `configuration` object, required
        - `version` 2, required
        - `destination` union, required
          - object
            - `type` 'direct', required
            - `phoneNumber` string, nullable, required
            - `externalHandoff` object, required
              - …
          - object
            - `type` 'dynamic', required
            - `pingUrl` string
            - `method` 'GET' | 'POST'
            - `timeout` integer
            - `headers` object
            - `body` object
            - `transferNumberField` string
            - `transferNumber` string
            - `successConditions` object[]
              - …
            - `fallback` union, required
              - …
            - `externalHandoff` object, required
              - …
          - object
            - `type` 'sip', required
            - `uri` string, nullable, required
            - `headers` object, required
            - `externalHandoff` object, required
              - …
          - object
            - `type` 'softphone', required
            - `routingConfigId` string, uuid, nullable, required
            - `handoffStrategy` 'wait-for-operator' | 'immediate-transfer', required
            - `voiceAiFallback` union, required
              - …
            - `agentWorkspace` object, required
              - …
            - `agentFirstHandling` object, required
              - …
        - `drafts` object, required
          - `direct` object
            - `type` 'direct', required
            - `phoneNumber` string, nullable, required
            - `externalHandoff` object, required
              - …
          - `dynamic` object
            - `type` 'dynamic', required
            - `pingUrl` string
            - `method` 'GET' | 'POST'
            - `timeout` integer
            - `headers` object
            - `body` object
            - `transferNumberField` string
            - `transferNumber` string
            - `successConditions` object[]
              - …
            - `fallback` union, required
              - …
            - `externalHandoff` object, required
              - …
          - `sip` object
            - `type` 'sip', required
            - `uri` string, nullable, required
            - `headers` object, required
            - `externalHandoff` object, required
              - …
          - `softphone` object
            - `type` 'softphone', required
            - `routingConfigId` string, uuid, nullable, required
            - `handoffStrategy` 'wait-for-operator' | 'immediate-transfer', required
            - `voiceAiFallback` union, required
              - …
            - `agentWorkspace` object, required
              - …
            - `agentFirstHandling` object, required
              - …
        - `warmTransfer` object, required
          - `mode` 'wait-for-operator' | 'immediate-summary', required
          - `summaryPrompt` string, nullable, required
      - `routingConfigId` string, uuid, nullable, required
      - `appointmentConfigId` string, uuid, nullable, required
      - `callFormId` string, uuid, nullable, required
      - `createdAt` string, date-time, nullable, required: Transfer config creation time. ISO 8601 timestamp
      - `updatedAt` string, date-time, nullable, required: Transfer config last update time. ISO 8601 timestamp
      - `usageHash` string
      - `usedByResources` object[]
        - `kind` 'transfer' | 'appointment' | 'scenario', required
        - `id` string, uuid, required
        - `name` string, required
      - `compatibilityWarnings` object[], required
        - `code` 'appointment_fallback_ignored_for_agent_first' | 'agent_first_callback_ignored_for_voice_ai', required
        - `message` string, required
        - `campaignId` string
        - `campaignName` string
        - `campaignKind` 'voice_ai' | 'agent_first'
      - `assignedCampaignCount` number
      - `usedByCampaigns` object[]
        - `id` string, required
        - `name` string, required
        - `kind` string, nullable, required
        - `status` string, nullable, required
      - `usedByReceptionist` boolean
      - `routingConfig` object, nullable, required: Reference to the assigned routing config. Campaign responses carry only id and name; fetch the full config (agents, groups, routing rules) from the transfer-configs endpoints.
        - `id` string, uuid, required
        - `name` string, required
    - `transferConfigIds` string[], required: Campaign-assigned transfer config IDs
    - `callFormId` string, uuid, nullable
    - `appointmentConfig` object, nullable, required
      - `id` string, uuid, required
      - `createdAt` string, date-time, nullable, required: Calendar creation time. ISO 8601 timestamp
      - `updatedAt` string, date-time, nullable, required: Calendar last update time. ISO 8601 timestamp
      - `clientId` string, uuid, nullable, required
      - `name` string, nullable, required
      - `description` string, nullable, required
      - `concurrentLimit` integer, required
      - `appointmentLength` integer, required
      - `appointmentSpacing` integer, required
      - `maxOptions` integer, required
      - `minDate` string, date, nullable, required: Earliest appointment date. Canonical format: YYYY-MM-DD
      - `maxDate` string, date, nullable, required: Latest appointment date. Canonical format: YYYY-MM-DD
      - `minHours` integer, nullable, required
      - `preferredMode` 'timezone' | 'zipcode', required
      - `appointmentMode` 'phone_call' | 'in_person' | 'video_call' | 'agent_phone_call', required
      - `showCallerIdOnBookingPage` boolean, required
      - `assignmentMode` 'customer_agent' | 'routing_config' | 'external_transfer', required
      - `routingConfigId` string, uuid, nullable, required
      - `transferConfigId` string, uuid, nullable, required
      - `workflows` object[], required
        - `id` string, uuid, required
        - `name` string, nullable
        - `enabled` boolean, required
        - `trigger` object, required
          - `anchor` 'event_starts' | 'event_ends', required
          - `offsetMinutes` integer, required
        - `condition` object
          - `kind` 'appointment_status', required
          - `statuses` string[], required
        - `action` union, required
          - object
            - `type` 'sms', required
            - `senderId` string, nullable
            - `template` string, required
          - object
            - `type` 'email', required
            - `senderId` string, nullable
            - `subject` string, required
            - `template` string, required
      - `bookingHours` object[], required
        - `startHour` integer, required
        - `startMinute` integer
        - `endHour` integer, required
        - `endMinute` integer
        - `dayOfWeek` integer[], required
      - `createdBy` string, uuid, nullable, required
      - `updatedBy` string, uuid, nullable, required
      - `usageHash` string
      - `usedByResources` object[]
        - `kind` 'transfer' | 'appointment' | 'scenario', required
        - `id` string, uuid, required
        - `name` string, required
      - `activeBookingLinkCount` integer
      - `upcomingAppointmentCount` integer
      - `usedByScenarios` object[]
        - `id` string, uuid, required
        - `name` string, required
      - `readiness` object
        - `ready` boolean, required
        - `issues` object[], required
          - `section` string, required
          - `message` string, required
      - `assignedCampaignCount` number
      - `assignedTransferConfigCount` number
      - `usedByCampaigns` object[]
        - `id` string, required
        - `name` string, required
        - `kind` string, nullable, required
        - `status` string, nullable, required
      - `usedByTransferConfigs` object[]
        - `id` string, required
        - `name` string, required
      - `usedByReceptionist` boolean
    - `campaignAutomations` object[], required
      - `id` string, uuid, required
      - `name` string, required
      - `triggerType` 'lead_created' | 'customer_created' | 'policy_created' | 'policy_status_changed' | 'campaign_completed' | 'campaign_failed' | 'temporal' | 'date_of_birth' | 'day_of_year' | 'policy_changed' | 'customer_field_changed' | 'time_in_campaign' | 'task_completed', required
      - `triggerConfig` union
        - object
          - `dateField` 'applicationApprovalDate' | 'effectiveDate' | 'terminationDate' | 'renewalDate' | 'enrollmentDate' | 'paidThroughDate' | 'gracePeriodStartDate', required
          - `offsetDays` integer, required
          - `direction` 'before' | 'after', required
        - object
          - `offsetDays` integer, required
          - `direction` 'before' | 'after', required
          - `atAge` integer
        - object
          - `month` integer, required
          - `day` integer, required
        - object
          - `days` integer, required
          - `sourceCampaignId` string, uuid
        - object
          - `sourceCampaignId` string, uuid, required
        - object
          - `tagName` string, required
          - `taskStatus` 'done' | 'cancelled', required
          - `policyStatusFilter` string[]
        - object
          - `fromStatus` 'Active' | 'Placed' | 'Pending' | 'Pending Effectuation' | 'Pending Followup' | 'Suspended' | 'Cancelled' | 'Terminated' | 'Future Cancel' | 'Deceased' | 'Not Approved' | 'ANY'
          - `toStatus` 'Active' | 'Placed' | 'Pending' | 'Pending Effectuation' | 'Pending Followup' | 'Suspended' | 'Cancelled' | 'Terminated' | 'Future Cancel' | 'Deceased' | 'Not Approved' | 'ANY'
          - `policySelection` 'changed_policy' | 'latest_effective_same_type'
          - `fromStatuses` string[]
          - `toStatuses` string[]
        - object
          - `filters` union[]
            - union
              - …
      - `isActive` boolean, required
      - `targetCampaignId` string, uuid, nullable, required
      - `relation` 'target' | 'source' | 'exit', required
  - `warnings` string[]: Creation compatibility notices, including incomplete older template snapshots

## Other responses

- `400`: POST /v2/campaigns Negative response 400
- `401`: POST /v2/campaigns Negative response 401
- `403`: POST /v2/campaigns Negative response 403
- `404`: POST /v2/campaigns Negative response 404
- `409`: POST /v2/campaigns Negative response 409
- `422`: POST /v2/campaigns Negative response 422
- `429`: POST /v2/campaigns Negative response 429
- `500`: POST /v2/campaigns Negative response 500
- `502`: POST /v2/campaigns Negative response 502
- `503`: POST /v2/campaigns Negative response 503

---

[API](https://skmtc.dev/carecycle/apis/carecycle-public-api.md) - [All operations](https://skmtc.dev/carecycle/apis/carecycle-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/carecycle/apis/carecycle-public-api/revisions/db390c743c36?raw)