Update a campaign

PATCH/v1/campaigns/{campaign_id}

Scope: campaigns:write

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.

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.

Headers

AuthorizationstringRequired
Bearer followed by a space and your API key, for example Bearer vk_….

Path parameters

campaign_idstring · uuidRequired
ID of the campaign.

Request body

ack_warningsboolean or null
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.
Default false
descriptionstring or null
New description
at most 2,000 characters
is_activeboolean or null
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_filtersobject or null
Replace the campaign's saved lead-database ICP filters
namestring or null
New campaign name
at most 2,000 characters
refill_policyobject or null
Replace the auto-refill policy (send {enabled:false} to disable; null is ignored)
responder_enabledboolean or null
Toggle the AI auto-responder

Response

200

campaignobject or null
The updated campaign
Show 14 child attributesHide child attributes
- idstringRequired
  Campaign UUID
  Example "550e8400-e29b-41d4-a716-446655440000"
- namestringRequired
  Campaign name
  Example "Q1 Enterprise Outreach"
- is_activebooleanRequired
  Whether the campaign is currently active
  Example true
- created_atstring · date-timeRequired
  When the campaign was created
  Example "2024-01-15T10:30:00+00:00"
- updated_atstring · date-timeRequired
  When the campaign was last updated
  Example "2024-01-20T14:45:00+00:00"
- ab_testing_enabledboolean or null
  Whether A/B testing is enabled for message variations
  Example true
- custom_fieldsany or null
  Custom fields — object on newer campaigns, list on legacy ones
- descriptionstring or null
  Campaign description
  Example "Targeting enterprise accounts in the tech sector"
- enabled_accountsarray of strings or null
  List of connected account IDs used for outreach
- lead_database_filtersobject or null
  Lead-database search filters defining this campaign's ICP (same shape the lead database search accepts)
- refill_policyobject or null
  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_enabledboolean or null
  Whether AI auto-responder is enabled
  Example true
- sequenceany or null
  Campaign sequence: an object with variation_a and variation_b message templates, or an empty list on a campaign with no sequence yet
- traffic_splitinteger or null
  Traffic split percentage for A/B testing (0-100)
  Example 50
messagestring
Default "Campaign updated"
successboolean
Default true

Errors

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

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.
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.