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

# Update Campaign

> Partially update a campaign's configuration

# Update Campaign

Partially update an existing campaign. All fields are optional — only the fields you send are updated. Use [Update Campaign Status](/api-reference/endpoints/update-campaign-status) instead to change just the status (`draft → active → paused → completed`).

## Endpoint

```
PUT /api/v1/campaigns/{campaign_id}
```

## Path parameters

<ParamField path="campaign_id" type="string" required>
  UUID of the campaign to update.
</ParamField>

## Request headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer talq_your_environment_token_here`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be set to `application/json`
</ParamField>

## Request body

All fields are optional. Send only what you want to change. Validation rules and ranges match [Create Campaign](/api-reference/endpoints/create-campaign).

### Identification

<ParamField body="name" type="string">
  Campaign name. Max 255 characters.
</ParamField>

<ParamField body="description" type="string">
  Free-form description.
</ParamField>

<ParamField body="campaign_type" type="string">
  Campaign category. Options: `sales`, `follow_up`, `reminder`, `custom`.
</ParamField>

<ParamField body="agent_id" type="string">
  UUID of the agent. Must exist in your environment.
</ParamField>

### Schedule

<ParamField body="start_date" type="string">
  Format: `YYYY-MM-DD`.
</ParamField>

<ParamField body="end_date" type="string">
  Optional end date. Must be after `start_date`. Format: `YYYY-MM-DD`. Send `null` to clear.
</ParamField>

<ParamField body="days_of_week" type="array">
  Array of weekday numbers (`1`–`7`, where `1` = Monday). Min 1 entry.
</ParamField>

<ParamField body="call_time_ranges" type="array">
  Time windows. Array of `{start: "HH:MM", end: "HH:MM"}` objects (24h format). Min 1 entry. Each window's `end` must be after its `start`.
</ParamField>

<ParamField body="timezone" type="string">
  IANA timezone (e.g., `America/New_York`). Max 50 characters.
</ParamField>

### Retry & Cooldown

<ParamField body="initial_call_delay" type="integer">
  Initial delay in seconds. Range: `0`+.
</ParamField>

<ParamField body="max_retries" type="integer">
  Range: `0`–`10`.
</ParamField>

<ParamField body="retry_cooldown_hours" type="integer">
  Range: `1`–`168`.
</ParamField>

<ParamField body="auto_complete" type="boolean">
  Auto-transition to `completed` when all contacts are processed.
</ParamField>

<ParamField body="retry_on_no_conversion" type="boolean">
  Retry calls that completed without conversion.
</ParamField>

<ParamField body="enable_post_completion_cooldown" type="boolean" />

<ParamField body="post_completion_cooldown_hours" type="integer">
  Range: `1`–`168`.
</ParamField>

<ParamField body="success_cooldown_hours" type="integer">
  Range: `1`–`168`.
</ParamField>

<ParamField body="voicemail_cooldown_hours" type="integer">
  Range: `1`–`168`.
</ParamField>

<ParamField body="no_answer_cooldown_hours" type="integer">
  Range: `1`–`168`.
</ParamField>

<ParamField body="busy_cooldown_hours" type="integer">
  Range: `1`–`168`.
</ParamField>

<ParamField body="failed_cooldown_hours" type="integer">
  Range: `1`–`168`.
</ParamField>

### Do-Not-Call (DNC)

<ParamField body="do_not_call_enabled" type="boolean" />

<ParamField body="do_not_call_list_source" type="string">
  Options: `environment`, `global`, `custom`.
</ParamField>

<ParamField body="do_not_call_custom_list" type="array">
  Array of phone numbers (E.164). Used when `do_not_call_list_source` is `custom`.
</ParamField>

<ParamField body="auto_add_to_dnc_enabled" type="boolean" />

<ParamField body="auto_dnc_trigger_statuses" type="array" />

<ParamField body="auto_dnc_trigger_errors" type="array" />

## Examples

<RequestExample>
  ```bash theme={null}
  # Update only the call windows + timezone
  curl -X PUT "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1" \
    -H "Authorization: Bearer talq_your_environment_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "call_time_ranges": [
        {"start": "10:00", "end": "12:00"},
        {"start": "14:00", "end": "16:00"}
      ],
      "timezone": "America/Sao_Paulo"
    }'
  ```

  ```javascript theme={null}
  const response = await fetch('https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1', {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      call_time_ranges: [
        { start: '10:00', end: '12:00' },
        { start: '14:00', end: '16:00' }
      ],
      timezone: 'America/Sao_Paulo'
    })
  });

  const result = await response.json();
  ```

  ```python theme={null}
  import requests

  url = "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1"
  headers = {
      "Authorization": "Bearer talq_your_environment_token_here",
      "Content-Type": "application/json"
  }
  data = {
      "call_time_ranges": [
          {"start": "10:00", "end": "12:00"},
          {"start": "14:00", "end": "16:00"}
      ],
      "timezone": "America/Sao_Paulo"
  }

  response = requests.put(url, headers=headers, json=data)
  result = response.json()
  ```
</RequestExample>

<RequestExample>
  ```bash theme={null}
  # Switch to custom DNC list and tighten retry policy
  curl -X PUT "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1" \
    -H "Authorization: Bearer talq_your_environment_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "max_retries": 2,
      "retry_cooldown_hours": 12,
      "success_cooldown_hours": 168,
      "do_not_call_enabled": true,
      "do_not_call_list_source": "custom",
      "do_not_call_custom_list": ["+15551234567"],
      "auto_add_to_dnc_enabled": true,
      "auto_dnc_trigger_statuses": ["completed"]
    }'
  ```
</RequestExample>

## Response

### Success Response (200 OK)

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "id": "campaign-uuid-1",
      "name": "Sales Campaign Q1",
      "campaign_type": "sales",
      "status": "active",
      "agent_id": "agent-uuid-1",
      "start_date": "2024-01-01",
      "end_date": null,
      "days_of_week": [1, 2, 3, 4, 5],
      "call_time_ranges": [
        {"start": "10:00", "end": "12:00"},
        {"start": "14:00", "end": "16:00"}
      ],
      "timezone": "America/Sao_Paulo",
      "max_retries": 3,
      "retry_cooldown_hours": 24,
      "do_not_call_enabled": false,
      "updated_at": "2024-01-15T11:30:00Z"
    }
  }
  ```
</ResponseExample>

## Error responses

### 422 Validation Error

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "The given data was invalid.",
    "errors": {
      "call_time_ranges.0.end": [
        "The call time ranges.0.end must be a date after call time ranges.0.start."
      ]
    }
  }
  ```
</ResponseExample>

### 404 Not Found

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Campaign not found"
  }
  ```
</ResponseExample>

### 409 Conflict — Active Calls

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Cannot update schedule while there are queued calls. Pause the campaign first.",
    "code": "CAMPAIGN_HAS_ACTIVE_CALLS"
  }
  ```
</ResponseExample>

## Notes

* Use `PATCH /v1/campaigns/{id}/status` to change status — it's a separate endpoint with its own validation.
* Updating `call_time_ranges` or `timezone` while the campaign is `active` may delay queued calls until they fall back into the new windows.
* Sending `"end_date": null` clears a previously set end date.

## Related endpoints

* [Get Campaign](/api-reference/endpoints/get-campaign)
* [Update Campaign Status](/api-reference/endpoints/update-campaign-status)
* [Delete Campaign](/api-reference/endpoints/delete-campaign)
* [List Campaigns](/api-reference/endpoints/list-campaigns)