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

# Update a campaign

> Changes a campaign's settings: its name, start, sending days and time zone, lists and exclusions, tracking, daily limits and link. Send at least one; it answers the campaign as `GET /v1/campaigns/{campaignId}` does.

New `listIds` replace the campaign's lists but enroll nobody in a running campaign: add a list with `POST /v1/campaigns/{campaignId}/lists` for that. While an `ai-generated` campaign's steps are still being written, new `listIds` answer `409` `campaign_initializing`. Click tracking cannot be turned off while a step waits for a click (`409` `click_tracking_required_by_condition`).

Free. **Scope:** campaigns, with a key that can write.



## OpenAPI

````yaml /openapi.json patch /v1/campaigns/{campaignId}
openapi: 3.1.0
info:
  title: outbound.dev API
  version: v1
  description: Find people and companies, and see what every call costs, with one API key.
servers:
  - url: https://api.outbound.dev
security: []
tags:
  - name: People
    description: >-
      Search people with filters, a saved search or a plain-language query,
      count matches and look up filter values.
  - name: Companies
    description: >-
      Search companies, count matches, name one company by its name, domain or
      LinkedIn page, and list its people.
  - name: Saved searches
    description: Keep a search under a title and run it again, for people or for companies.
  - name: Lists
    description: >-
      Keep people or companies in lists: create and change lists, page through
      their rows, and add or remove people.
  - name: Folders
    description: Group lists of one kind into folders.
  - name: Enrichment
    description: >-
      Find people's work emails and phone numbers: one person, a batch of
      people, or a list.
  - name: Jobs
    description: >-
      Long tasks a call started: their progress, what they produced and what
      they were charged, and stopping them.
  - name: Accounts
    description: >-
      Connect the mailboxes and LinkedIn seats that campaigns and the inbox send
      from, and look after them.
  - name: Campaigns
    description: >-
      Email and LinkedIn campaigns: their steps, the people they enroll, their
      queue of messages, templates, the knowledge hubs and writing styles AI
      steps are written from, the tracking domain their links go through, and
      the lists every campaign leaves out.
  - name: Inbox
    description: >-
      Read and answer the conversations of your mailboxes and LinkedIn seats,
      and send new messages and invitations.
  - name: Account
    description: >-
      The calling key and its organization, its rate limits, and revoking the
      key.
  - name: Billing
    description: The balance, the ledger of every change to it, and the price list.
  - name: Usage and requests
    description: >-
      Calls and spend by day, and the record of every request of the last 30
      days.
paths:
  /v1/campaigns/{campaignId}:
    patch:
      tags:
        - Campaigns
      summary: Update a campaign
      description: >-
        Changes a campaign's settings: its name, start, sending days and time
        zone, lists and exclusions, tracking, daily limits and link. Send at
        least one; it answers the campaign as `GET /v1/campaigns/{campaignId}`
        does.


        New `listIds` replace the campaign's lists but enroll nobody in a
        running campaign: add a list with `POST
        /v1/campaigns/{campaignId}/lists` for that. While an `ai-generated`
        campaign's steps are still being written, new `listIds` answer `409`
        `campaign_initializing`. Click tracking cannot be turned off while a
        step waits for a click (`409` `click_tracking_required_by_condition`).


        Free. **Scope:** campaigns, with a key that can write.
      operationId: patchCampaignsCampaignId
      parameters:
        - name: campaignId
          in: path
          required: true
          description: The campaign's id.
          schema:
            type: string
            minLength: 24
            maxLength: 24
            pattern: ^[0-9a-fA-F]+$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              properties:
                name:
                  type: string
                  description: A new name.
                  minLength: 1
                  maxLength: 200
                listIds:
                  type: array
                  description: >-
                    The campaign's lists, replacing the ones it has, 1 to 10. A
                    running campaign does not enroll a new list's people: add a
                    list with `POST /v1/campaigns/{campaignId}/lists` for that.
                  minItems: 1
                  maxItems: 10
                  uniqueItems: true
                  items:
                    type: string
                    minLength: 24
                    maxLength: 24
                    pattern: ^[0-9a-fA-F]+$
                startDate:
                  type: string
                  description: >-
                    When sending may start, as an ISO 8601 date-time. Now when
                    left out.
                timezone:
                  type: string
                  description: >-
                    The IANA time zone the sending days and hours (9:00 to
                    17:00) are read in, such as `Europe/Lisbon`: a region, not
                    an abbreviation such as EST. UTC when a campaign is created
                    without one.
                emailDays:
                  type: array
                  description: >-
                    The days messages may go out, by English name with a capital
                    first letter. Monday to Friday when left out.
                  minItems: 1
                  maxItems: 7
                  uniqueItems: true
                  items:
                    type: string
                    enum:
                      - Monday
                      - Tuesday
                      - Wednesday
                      - Thursday
                      - Friday
                      - Saturday
                      - Sunday
                excludeLists:
                  type: array
                  description: >-
                    Up to 10 people lists whose people are never enrolled,
                    matched by person, email address or LinkedIn profile. An id
                    that is not one of your lists excludes nobody.
                  maxItems: 10
                  uniqueItems: true
                  items:
                    type: string
                    minLength: 24
                    maxLength: 24
                    pattern: ^[0-9a-fA-F]+$
                excludeCompanyLists:
                  type: array
                  description: >-
                    Up to 20 company or people lists: nobody who works at one of
                    their companies is enrolled. A list the organization does
                    not have answers `422` `exclude_company_lists_invalid`.
                  maxItems: 20
                  uniqueItems: true
                  items:
                    type: string
                    minLength: 24
                    maxLength: 24
                    pattern: ^[0-9a-fA-F]+$
                excludeContacted:
                  type: string
                  description: >-
                    Skips people your campaigns already wrote to: `none` (the
                    default) skips nobody, `ever` skips everyone written to, and
                    `last_1_month` to `last_1_year` skip those written to in
                    that time.
                  enum:
                    - none
                    - ever
                    - last_1_month
                    - last_3_months
                    - last_6_months
                    - last_1_year
                excludeEngagedContacts:
                  type: boolean
                  description: >-
                    Skips people who replied to one of your campaigns. False
                    when left out.
                isDynamic:
                  type: boolean
                  description: >-
                    Enrolls people added to the campaign's lists after launch,
                    as they arrive. False when left out.
                addUnsubscribeLink:
                  type: boolean
                  description: >-
                    Ends every email with a one-click unsubscribe link. True
                    when left out.
                openRateTrackingEnabledAt:
                  type: string
                  description: >-
                    Turns open tracking on from this ISO 8601 date-time, or off
                    with null. Off when left out.
                clickTrackingEnabledAt:
                  type: string
                  description: >-
                    Turns click tracking on from this ISO 8601 date-time, or off
                    with null. Off when left out. A step that waits for a click
                    needs it on.
                sendOnlyToValidatedEmailsEnabledAt:
                  type: string
                  description: >-
                    From this ISO 8601 date-time, enrolls only people whose
                    email address checked `valid`; null also enrolls catch-all
                    and unchecked addresses.
                dailyEmailLimit:
                  type: integer
                  description: >-
                    The most emails the campaign sends a day, 1 to 10,000, or
                    null for no limit.
                  minimum: 1
                  maximum: 10000
                dailyLinkedinConnectionLimit:
                  type: integer
                  description: >-
                    The most LinkedIn invitations the campaign sends a day, 1 to
                    10,000, or null for no limit.
                  minimum: 1
                  maximum: 10000
                dailyLinkedinMessageLimit:
                  type: integer
                  description: >-
                    The most LinkedIn messages and InMails the campaign sends a
                    day, 1 to 10,000, or null for no limit.
                  minimum: 1
                  maximum: 10000
                ctaLink:
                  type: string
                  description: >-
                    The link steps insert where they write `{CTA Link}`: an http
                    or https URL, or null or empty for none.
                  maxLength: 2000
            example:
              name: Portugal freight ops, directors
              dailyEmailLimit: 25
              clickTrackingEnabledAt: '2026-11-15T09:00:00.000Z'
      responses:
        '200':
          description: >-
            The campaign, with its settings under the names `POST /v1/campaigns`
            takes them. A field without a value is absent.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            X-Charged-Usd:
              $ref: '#/components/headers/ChargedUsd'
            X-Balance-Usd:
              $ref: '#/components/headers/BalanceUsd'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  type:
                    type: string
                    enum:
                      - manual
                      - ai-generated
                  status:
                    type: string
                    enum:
                      - initializing
                      - active
                      - stopped
                      - paused_manual
                      - initialization_failed
                  initializationStatus:
                    type: string
                    description: >-
                      How writing an `ai-generated` campaign stands: `pending`,
                      `analyzing_prompt`, `building_knowledge`,
                      `generating_topics`, then `completed` or `failed`. A
                      `manual` campaign is `completed` from the start.
                  listIds:
                    type: array
                    items:
                      type: string
                  startDate:
                    type: string
                    format: date-time
                    description: Nothing is sent before it.
                  timezone:
                    type: string
                    description: >-
                      The IANA time zone its sending days and hours (9:00 to
                      17:00) are read in.
                  emailDays:
                    type: array
                    items:
                      type: string
                      enum:
                        - Monday
                        - Tuesday
                        - Wednesday
                        - Thursday
                        - Friday
                        - Saturday
                        - Sunday
                    description: The days messages may go out.
                  excludeLists:
                    type: array
                    items:
                      type: string
                    description: People lists whose people are never enrolled.
                  excludeCompanyLists:
                    type: array
                    items:
                      type: string
                    description: Lists whose companies' people are never enrolled.
                  excludeContacted:
                    type: string
                    enum:
                      - none
                      - ever
                      - last_1_month
                      - last_3_months
                      - last_6_months
                      - last_1_year
                    description: >-
                      The people your campaigns already wrote to that are
                      skipped: `none`, `ever`, or those written to in the time
                      named.
                  excludeEngagedContacts:
                    type: boolean
                    description: People who replied to one of your campaigns are skipped.
                  isDynamic:
                    type: boolean
                    description: >-
                      People added to its lists after launch are enrolled as
                      they arrive.
                  addUnsubscribeLink:
                    type: boolean
                    description: Every email ends with a one-click unsubscribe link.
                  openRateTrackingEnabledAt:
                    type: string
                    format: date-time
                    description: >-
                      Since when opens are tracked. Absent while open tracking
                      is off.
                  clickTrackingEnabledAt:
                    type: string
                    format: date-time
                    description: >-
                      Since when links are tracked. Absent while click tracking
                      is off.
                  dailyEmailLimit:
                    type: integer
                  dailyLinkedinConnectionLimit:
                    type: integer
                  dailyLinkedinMessageLimit:
                    type: integer
                  ctaLink:
                    type: string
                    description: >-
                      The link steps insert where they write `{CTA Link}`.
                      Absent when there is none.
              example:
                id: 6a1f0c2b9d4e8a7f3c5b2e30
                name: Portugal freight ops
                type: manual
                status: initializing
                initializationStatus: completed
                listIds:
                  - 6a1f0c2b9d4e8a7f3c5b2e20
                startDate: '2026-11-17T09:00:00.000Z'
                timezone: Europe/Lisbon
                emailDays:
                  - Monday
                  - Tuesday
                  - Wednesday
                  - Thursday
                  - Friday
                excludeLists: []
                excludeCompanyLists: []
                excludeContacted: last_3_months
                excludeEngagedContacts: true
                isDynamic: false
                addUnsubscribeLink: true
                openRateTrackingEnabledAt: '2026-11-15T09:00:00.000Z'
                dailyEmailLimit: 40
                ctaLink: https://fernway.co/meet
        '429':
          $ref: '#/components/responses/RateLimited'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
        - apiKey: []
components:
  headers:
    RequestId:
      description: The request's id. Quote it when you write to support.
      schema:
        type: string
        example: req_6a1f0c2b9d4e8a7f3c5b2e10
    ChargedUsd:
      description: What this call cost, in US dollars as an exact six-decimal string.
      schema:
        type: string
        example: '0.005000'
    BalanceUsd:
      description: >-
        The organization's balance after this call, in US dollars as an exact
        six-decimal string.
      schema:
        type: string
        example: '9.995000'
    RateLimitLimit:
      description: >-
        The calls allowed in the window of the route's limit with the fewest
        calls left.
      schema:
        type: integer
        example: 20
    RateLimitRemaining:
      description: The calls left in that window.
      schema:
        type: integer
        example: 19
    RateLimitReset:
      description: Seconds until that window resets.
      schema:
        type: integer
        example: 42
    RetryAfter:
      description: Seconds to wait before calling again.
      schema:
        type: integer
        example: 42
  responses:
    RateLimited:
      description: >-
        Too many calls. Wait the seconds in Retry-After, then call again. When
        the limit reached does not say when it resets, such as a mail provider's
        own limit on a mailbox, Retry-After is 60. The RateLimit headers
        describe this API's own limits, so they come only with a 429 one of
        those gave. The body is empty.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
    Error:
      description: The request was refused. The body names the reason in `error.code`.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: >-
        Something failed on our side and nothing was charged. Retry with
        backoff; quote X-Request-Id if it persists. The body is empty.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - doc_url
          properties:
            code:
              type: string
              description: >-
                Stable and machine-readable: branch on it. It never changes
                meaning.
            message:
              type: string
              description: >-
                A human-readable explanation for logs. It may be reworded at any
                time.
            param:
              type: string
              description: The request field the error is about, when there is one.
            doc_url:
              type: string
              description: The code's entry in the errors reference.
            request_id:
              type: string
              description: >-
                The request's id, as in the X-Request-Id header. Quote it to
                support.
      example:
        error:
          code: insufficient_balance
          message: Your balance cannot cover this call. Add funds and try again.
          doc_url: https://docs.outbound.dev/errors#insufficient_balance
          request_id: req_6a1f0c2b9d4e8a7f3c5b2e10
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        An API key from the console, starting `ob_live_`, sent as
        `Authorization: Bearer <key>`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.