---
title: "Update Campaign"
method: PATCH
path: "/v1/campaigns/{id}"
tags: ["Campaigns", "v1"]
---

# Update Campaign

`PATCH /v1/campaigns/{id}`

Update a specific campaign using its campaign ID. Supports changes to campaign attributes such as name, budget, status, associated list or custom feed, and campaign settings.

:::info
Requires the `campaigns:write` OAuth2 scope.
:::

## Path parameters

- `id` string, required

## Query parameters

- `account_id` string, required

## Request body

- object
  - `data` object, required
    - `type` string, required
    - `attributes` object, required — Subset of campaign attributes to update. Only `status`, `name`, and `budget` are mutable through this endpoint.
      - `name` string — New name for the campaign.
      - `status` 'draft' | 'scheduled' | 'running' | 'paused' | 'stopped' | 'terminated' | 'ended' — New lifecycle status. Only transitions allowed by the campaign's current state are accepted; invalid transitions surface as `422 validation_failed`.
      - `budget` number — New budget value, in units of the campaign's currency. Interpretation depends on the campaign's `budget_type` (total or daily).
    - `relationships` object — Optional relationship updates. Omit to leave the relationship unchanged.
      - `list` object — Repoint the campaign to a different audience list.
        - `id` string, required — Stable identifier of the target audience list.
        - `type` 'list', required
      - `campaign_settings` object — Patch the campaign settings toggles.
        - `id` string, required
        - `type` 'campaign_settings', required
        - `attributes` object, required
          - `brand_safety_domains_exclusion_enabled` boolean
          - `automatically_include_new_target_companies` boolean
          - `automatically_remove_target_companies` boolean
          - `ads_visible_only_on_weekdays` boolean

## Response `200`

Success

- object
  - `data` CampaignV1, required
    - `type` 'campaign', required — The type of the object.
    - `id` string, required — The unique identifier for the campaign.
    - `attributes` object, required
      - `name` string, required — Human-readable name of the campaign.
      - `status` 'draft' | 'scheduled' | 'running' | 'paused' | 'stopped' | 'terminated' | 'ended', required — Lifecycle status of the campaign. - `draft` — campaign is still being configured. No delivery, no spend. Can be transitioned into `scheduled` / `running` once `can_be_started` is `true`. - `scheduled` — campaign is fully configured and queued; ads start delivering when `start_date` is reached. No spend yet. - `running` — campaign is actively serving ads and consuming budget. - `paused` — campaign was previously `scheduled` or `running` and has been paused by the user. Delivery is halted and no further budget is consumed; can be resumed back to `running`. - `stopped` — delivery is automatically halted by Leadfeeder because of an external blocker (most commonly an unresolved billing issue on the account). The campaign resumes automatically once the blocker is cleared; the user cannot transition out of this state directly. Surfaced both for campaigns whose underlying status is `stopped` and for campaigns that are technically `scheduled` while the account has a billing issue. - `terminated` — campaign was permanently stopped by the user before reaching `end_date`. Terminal state; cannot be resumed. - `ended` — campaign reached its scheduled `end_date` and completed naturally. Terminal state.
      - `start_date` string, date-time, required — Scheduled start datetime of the campaign. Always present — a campaign cannot be created without a start date. Caveat: if a campaign gets stuck in `scheduled` past its original start date (for example because of an unresolved billing issue on the account), `start_date` is updated in place to the date the campaign is unstuck and actually begins delivering. Treat this field as the campaign's effective start, not necessarily the originally-configured one.
      - `end_date` string, date-time, nullable, required — Scheduled end datetime of the campaign. `null` for open-ended campaigns. Otherwise set from the moment an end date is configured, regardless of the campaign's lifecycle status.
      - `location_type` 'global' | 'region' | 'country' | 'city', required — Geographical granularity of the campaign's targeting.
      - `budget_type` 'total' | 'daily', required — How the campaign's budget cap is applied.
      - `budget` number, required — Configured budget value, expressed in the smallest indivisible unit consistent with the campaign's `currency`. The meaning depends on `budget_type`: total spend cap for `total`, daily cap for `daily`.
      - `total_budget` number, required — Effective total spend cap for the campaign, in units of `currency`. For `budget_type=total` this equals `budget`; for `budget_type=daily` it is the daily budget multiplied by the scheduled run length.
      - `budget_spent` number, float, required — Amount already spent by the campaign, in units of `currency`.
      - `budget_left` number, float, required — Remaining budget headroom (`total_budget - budget_spent`), in units of `currency`. Never negative.
      - `currency` string, required — ISO 4217 currency code for all monetary fields on the campaign (`budget`, `total_budget`, `budget_spent`, `budget_left`). Not user-controllable: it is inherited from the subscription that was active at the moment the campaign was started. Leadfeeder's billing system is currency-agnostic and assumes every chargeable campaign on an account uses the same currency as the current subscription — campaigns are not run across multiple currencies.
      - `can_be_started` boolean, required — Whether the campaign currently passes all preflight checks required to transition out of `draft`. `false` indicates missing configuration (budget, audience, locations, …).
      - `targets_crm_open_opportunities` boolean, required — `true` when the campaign's audience list is the dynamic "CRM accounts with open opportunities" list.
      - `created_at` string, date-time, required — Datetime when the campaign was created.
      - `updated_at` string, date-time, required — Datetime when the campaign was last updated.
    - `relationships` object, required — Reference pointers to related resources. Each relationship carries `id` / `type` by default; when the matching value is requested through `include=`, the resource is inlined under the same key with its full `attributes` block.
      - `created_by` object, nullable, required — The user who created the campaign.
        - `id` string, required — The Leadfeeder user ID.
        - `type` string, required
      - `list` union, required — Audience list (target companies) backing the campaign. Inlined as a full `list` resource when `include=list` is set; otherwise an `id` / `type` reference.
        - object — Reference returned by default — `id` / `type` only, when `include=list` is not requested.
          - `id` string, required
          - `type` 'list', required
        - ListV1
          - `type` 'list', required — The type of the object
          - `id` string, required — The unique identifier for the list
          - `attributes` object, required
            - `name` string, required — The human-readable name of the List
            - `scope` 'company' | 'contact', required — The scope type of the list
            - `created_at` string, date-time, required — Date and time when the list was created
            - `updated_at` string, date-time — Date and time when the list was updated
          - `relationships` object, required
            - `created_by` object, required
              - …
      - `custom_feed` union, required — Custom website-visit feed used for retargeting. Inlined as a full `custom_feed` resource when `include=custom_feed` is set; otherwise an `id` / `type` reference.
        - object — Reference returned by default — `id` / `type` only, when `include=custom_feed` is not requested.
          - `id` string, required
          - `type` 'custom_feed', required
        - CustomFeedV1
          - `type` 'custom_feed', required — The type of the object
          - `id` string, required — The unique identifier for the custom feed.
          - `attributes` object, required
            - `name` string, required — Name of the custom feed.
            - `created_at` string, date-time, required — Datetime when the custom feed was created.
            - `updated_at` string, date-time, required — Datetime when the custom feed was last updated.
            - `deletable` boolean, required — Whether this custom feed can be deleted.
            - `viewable` boolean, required — Whether this custom feed can be viewed.
            - `notifications` union[], required — Notification subscriptions configured for this custom feed.
              - …
            - `advanced_filters` object, nullable — Advanced filters configuration for the custom feed. Returns null if no filters are configured.
              - …
          - `relationships` object, required
            - `created_by` object, nullable, required — The user who originally created the custom feed.
              - …
            - `folder` object, nullable
              - …
      - `campaign_settings` union, required — Campaign-level configuration toggles. Inlined as a full `campaign_settings` resource when `include=campaign_settings` is set; otherwise an `id` / `type` reference.
        - object — Reference returned by default — `id` / `type` only, when `include=campaign_settings` is not requested.
          - `id` string, required
          - `type` 'campaign_settings', required
        - CampaignSettingsV1
          - `type` 'campaign_settings', required — The type of the object.
          - `id` string — Identifier of the campaign settings resource. Matches the parent campaign's id.
          - `attributes` object, required
            - `brand_safety_domains_exclusion_enabled` boolean, required — When `true`, Leadfeeder's brand-safety domain exclusion list is applied to the campaign, preventing ad delivery on flagged domains.
            - `automatically_include_new_target_companies` boolean, required — When `true`, companies that newly enter the target audience list are automatically added to the campaign's active targets.
            - `automatically_remove_target_companies` boolean, required — When `true`, companies removed from the target audience list are automatically deactivated as campaign targets.
            - `ads_visible_only_on_weekdays` boolean, required — When `true`, ads served by the campaign are limited to Monday–Friday delivery windows.
      - `campaign_summary` union, required — Aggregated lifetime performance summary. Inlined as a full `campaign_summary` resource when `include=campaign_summary` is set; otherwise an `id` / `type` reference.
        - object — Reference returned by default — `id` / `type` only, when `include=campaign_summary` is not requested.
          - `id` string, required
          - `type` 'campaign_summary', required
        - CampaignSummaryV1
          - `type` 'campaign_summary', required — The type of the object.
          - `id` string — Identifier of the campaign summary resource. Matches the parent campaign's id.
          - `attributes` object, required
            - `clicks` integer, required — Total ad clicks recorded over the campaign lifetime.
            - `impressions` integer, required — Total ad impressions delivered over the campaign lifetime.
            - `targeted_count` integer, required — Number of companies currently targeted by the campaign.
            - `audience_count` integer, required — Size of the audience list backing the campaign.
            - `reached_count` integer, required — Distinct companies that received at least one impression.
            - `influenced_count` integer, required — Distinct companies attributed to the campaign through subsequent tracked engagement.
            - `visits_count` integer, required — Website visits attributed to the campaign.
            - `currency` string, required — ISO 4217 currency code in which monetary values are reported.
            - `ecpm` number, float, required — Effective cost per mille (per 1000 impressions).
            - `ecpc` number, float, required — Effective cost per click.
            - `ctr` number, float, required — Click-through rate (`clicks / impressions`) expressed as a decimal ratio. Multiply by 100 to convert to a percentage: `0.05` means 5%.
            - `total_cost` number, float, required — Total spend over the campaign lifetime.
            - `ecpv` number, float, required — Effective cost per attributed website visit.
            - `vtr` number, float, required — Visit-through rate (`visits_count / impressions`) expressed as a decimal ratio. Multiply by 100 to convert to a percentage: `0.01` means 1%.
            - `cost_per_company` number, float, required — Total cost divided by reached_count.
      - `campaign_locations` union[], required — Geographical targets attached to the campaign. Each item is inlined with its `attributes` when `include=campaign_locations` is set; otherwise each entry is an `id` / `type` reference only.
        - union
          - object — Reference returned by default — `id` / `type` only, when `include=campaign_locations` is not requested.
            - `id` string, required
            - `type` 'campaign_location', required
          - CampaignLocationV1
            - `type` 'campaign_location', required — The type of the object.
            - `id` string, required — Identifier of the campaign-location association.
            - `attributes` object, required
              - …
  - `meta` object, required
    - `request_id` string, required — A unique identifier assigned to each API request for end-to-end traceability.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized. The request was rejected because the credentials are missing, invalid, expired, or have been revoked. The client must re-authenticate before retrying. Clients can differentiate via the `code` value of the first item in `errors`.
- `403` — Forbidden. The credentials are valid but the caller is not authorized to perform the request — typically because the user lacks the required permission, the OAuth scope is insufficient, the subscription plan does not include the required entitlement, the `account_id` does not belong to the authenticated user, or the target list is read-only and its members cannot be modified. Clients can differentiate via the `code` value of the first item in `errors`.
- `404` — Not found
- `422` — Unprocessable entity
- `429` — Too many requests. Either the per-second rate limit or the monthly quota configured for the API key / OAuth application has been exceeded. Clients can differentiate via the `code` value of the first item in `errors`.
- `500` — Internal server error
- `504` — Server timeout

---

[API](https://skmtc.net/leadfeeder/apis/leadfeeder-public-api.md) · [All operations](https://skmtc.net/leadfeeder/apis/leadfeeder-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/leadfeeder/leadfeeder-public-api/revisions/9e2e63ba2a4e/schema)