# Update a campaign

`PATCH https://api.versionseven.ai/v1/campaigns/{campaign_id}`

Change a campaign's `name` or `description`, activate or pause it with `is_active`, or turn the AI Appointment Setter on or off with `responder_enabled`. Fields you don't send are left unchanged.

> **Note:** Activating a campaign runs the readiness preflight first: the sequence and its step content, its variables and lead data, the assigned sender accounts, sender email authentication and the subscription. A blocking check answers `409 CAMPAIGN_NOT_READY`, with every check listed in `details.checks`. Warnings alone answer `409 CAMPAIGN_ACTIVATION_WARNINGS` until you repeat the request with `ack_warnings: true`. Pausing never runs the preflight. To see the verdict without activating, call [Get the activation preflight](https://docs.versionseven.ai/api-reference/campaigns/get-campaign-preflight).

- Required scope: `campaigns:write`

## Request

**cURL**

```bash
curl -X PATCH "https://api.versionseven.ai/v1/campaigns/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $VICTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Node.js**

```javascript
const response = await fetch("https://api.versionseven.ai/v1/campaigns/550e8400-e29b-41d4-a716-446655440000", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.VICTORIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});

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

**Python**

```python
import os

import requests

response = requests.patch(
    "https://api.versionseven.ai/v1/campaigns/550e8400-e29b-41d4-a716-446655440000",
    headers={
        "Authorization": f"Bearer {os.environ['VICTORIA_API_KEY']}",
    },
    json={},
)
data = response.json()
```

## Headers

- `Authorization` (string, required): `Bearer` followed by a space and your API key, for example `Bearer vk_…`.

## Path parameters

- `campaign_id` (string · uuid, required): ID of the campaign.

## Request body

- `ack_warnings` (boolean or null, optional, default `false`): With is\_active=true: accept the non-blocking warnings the preflight reported (a CAMPAIGN\_ACTIVATION\_WARNINGS response lists them under details.checks) and activate anyway.
- `description` (string or null, optional, at most 2,000 characters): New description
- `is_active` (boolean or null, optional): Activate (true) or pause (false) the campaign. Activation runs the readiness preflight: a blocking check answers 409 CAMPAIGN\_NOT\_READY, warnings alone answer 409 CAMPAIGN\_ACTIVATION\_WARNINGS until acknowledged with ack\_warnings.
- `lead_database_filters` (object or null, optional): Replace the campaign's saved lead-database ICP filters
- `name` (string or null, optional, at most 2,000 characters): New campaign name
- `refill_policy` (object or null, optional): Replace the auto-refill policy (send {enabled:false} to disable; null is ignored)
- `responder_enabled` (boolean or null, optional): Toggle the AI auto-responder

## Response

### `200`

```json
{
  "campaign": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Q1 Enterprise Outreach",
    "is_active": true,
    "created_at": "2024-01-15T10:30:00+00:00",
    "updated_at": "2024-01-20T14:45:00+00:00",
    "ab_testing_enabled": true,
    "custom_fields": null,
    "description": "Targeting enterprise accounts in the tech sector",
    "enabled_accounts": [
      "string"
    ],
    "lead_database_filters": {},
    "refill_policy": {},
    "responder_enabled": true,
    "sequence": {
      "variation_a": [
        {
          "id": 1,
          "type": "email",
          "subject": "Question about {company}",
          "content": "Hi {first_name},\n\nAre you the right person to talk to about how {company} books sales meetings?\n\nThanks,\nJane",
          "delay": 2
        },
        {
          "id": 2,
          "type": "email",
          "subject": "Re: Question about {company}",
          "content": "Hi {first_name},\n\nFollowing up on my last note. Would a short call next week be useful?\n\nJane",
          "delay": 3
        },
        {
          "id": 3,
          "type": "email",
          "subject": "Closing the loop",
          "content": "Hi {first_name},\n\nI haven't heard back, so I'll assume the timing isn't right. If that changes, just reply to this email.\n\nJane",
          "delay": 0
        }
      ],
      "variation_b": []
    },
    "traffic_split": 50
  },
  "message": "Campaign updated",
  "success": true
}
```

- `campaign` (object or null, optional): The updated campaign
  - `id` (string, required, example `"550e8400-e29b-41d4-a716-446655440000"`): Campaign UUID
  - `name` (string, required, example `"Q1 Enterprise Outreach"`): Campaign name
  - `is_active` (boolean, required, example `true`): Whether the campaign is currently active
  - `created_at` (string · date-time, required, example `"2024-01-15T10:30:00+00:00"`): When the campaign was created
  - `updated_at` (string · date-time, required, example `"2024-01-20T14:45:00+00:00"`): When the campaign was last updated
  - `ab_testing_enabled` (boolean or null, optional, example `true`): Whether A/B testing is enabled for message variations
  - `custom_fields` (any or null, optional): Custom fields — object on newer campaigns, list on legacy ones
  - `description` (string or null, optional, example `"Targeting enterprise accounts in the tech sector"`): Campaign description
  - `enabled_accounts` (array of strings or null, optional): List of connected account IDs used for outreach
  - `lead_database_filters` (object or null, optional): Lead-database search filters defining this campaign's ICP (same shape the lead database search accepts)
  - `refill_policy` (object or null, optional): Automatic lead-refill settings for the campaign: `enabled`, `min_backlog`, `target_backlog`, `max_add_per_run`, `max_tokens_per_run`, `cooldown_hours` and `mode`.
  - `responder_enabled` (boolean or null, optional, example `true`): Whether AI auto-responder is enabled
  - `sequence` (any or null, optional): Campaign sequence: an object with variation\_a and variation\_b message templates, or an empty list on a campaign with no sequence yet
  - `traffic_split` (integer or null, optional, example `50`): Traffic split percentage for A/B testing (0-100)
- `message` (string, optional, default `"Campaign updated"`)
- `success` (boolean, optional, default `true`)

## Errors

Errors share one JSON body: `success`, `error`, `message`, optional `details`, and `request_id`. For example:

```json
{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "Invalid or inactive API key",
  "request_id": "734d11a1-54d4-414c-9e8d-4e1ada977db4"
}
```

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | The request didn't match the endpoint's schema: a missing or malformed field, a bad query parameter, or a value out of range. `details.errors` lists each failing field with its `field`, `message` and `type`. |
| 401 | `UNAUTHORIZED` | The `Authorization` header is missing or malformed, or the API key is unknown or has been deactivated. |
| 401 | `API_KEY_EXPIRED` | The API key is past its expiry date. Create a new key in the Victoria AI app. |
| 403 | `INSUFFICIENT_SCOPE` | The API key doesn't have the scope this endpoint requires, such as `leads:write`. |
| 403 | `ORGANIZATION_DEACTIVATED` | The organization that owns this API key has been deactivated. |
| 404 | `CAMPAIGN_NOT_FOUND` | No campaign with this ID exists in your organization. |
| 404 | `NOT_FOUND` | No endpoint matches the path. A resource ID in the path that isn't a valid UUID also answers `NOT_FOUND`. |
| 409 | `CAMPAIGN_NOT_READY` | The campaign can't be activated: at least one readiness check is blocking, such as a step missing content, a variable with no personalization field, an unassigned or unauthenticated sender, or no enrolled leads. `details.checks` lists every check with its status. |
| 409 | `CAMPAIGN_ACTIVATION_WARNINGS` | The campaign's readiness checks passed with warnings only. `details.checks` lists them. Repeat the request with `ack_warnings: true` to activate anyway. |
| 413 | `PAYLOAD_TOO_LARGE` | The request body is larger than 1 MB. |
| 429 | `RATE_LIMITED` | Too many requests for this API key: more than 100 a minute to one endpoint, or 600 a minute in total. Retry after the number of seconds in the `Retry-After` header. See [Rate limits](https://docs.versionseven.ai/guides/rate-limits). |
| 500 | `INTERNAL_ERROR` | Something failed on our side. The response never includes internal details; quote its `request_id` when you contact support. |
| 503 | `UPSTREAM_TIMEOUT` | A service the API depends on timed out. The request is safe to retry. |
| 503 | `AUTH_UNAVAILABLE` | The API key couldn't be checked because the authentication service was unavailable. The request is safe to retry. |

## Response headers

| Header | Description |
| --- | --- |
| `X-Request-ID` | Correlation ID for the request, also returned as `request_id` in error bodies. Send your own `X-Request-ID`, up to 128 letters, digits, `.`, `_`, `:` or `-`, and it's used instead. |
| `RateLimit-Limit` | Requests allowed to this endpoint per minute. |
| `RateLimit-Remaining` | Requests you can still send to this endpoint right now. |
| `RateLimit-Reset` | Seconds until the endpoint's full limit is available again. |
| `Retry-After` | On a `429`: seconds to wait before retrying. |