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

> ## Agent Instructions
> Use the public API base URL: https://api.teamfollowup.ai/api.
> Authenticate public API requests with Authorization: Bearer YOUR_API_KEY.
> Use product-owned terms: agents, calls, campaigns, contacts, phone numbers, billing, and configuration.

# Update campaign

> Update the campaign owned by this agent.

Required API key scope: `campaigns:write`.



## OpenAPI

````yaml /openapi.yaml patch /api/agent-builder/agents/{id}/campaign
openapi: 3.1.0
info:
  title: TFUAI Server API
  version: 1.0.0
  description: >-
    API reference for the TFUAI SaaS server.


    All published endpoints are mounted under `/api`. Responses use a standard
    envelope: `{ "success": true, ... }` on success and `{ "success": false,
    "error": "..." }` on failure.


    Product API modules are being launched module by module. This spec currently
    exposes only contracted public modules.


    Authenticate public API requests with an API key in the `Authorization`
    header: `Authorization: Bearer YOUR_API_KEY`.
servers:
  - url: https://api.teamfollowup.ai
    description: Production API origin. Public API paths are under /api.
  - url: https://devapi.teamfollowup.ai
    description: Development API origin. Public API paths are under /api.
security: []
tags:
  - name: Agents
    description: Manage voice agents, campaigns, workflows, and outcomes.
  - name: Analytics
    description: >-
      Minimal, non-billing performance summary: volume, conversion, and pickup
      metrics.
  - name: Calls
    description: Review calls, test runs, and execution history.
  - name: Campaign Workflows
    description: >-
      What runs after a call lands: for each outcome (booked, opted out, asked
      for a callback…), an ordered chain of actions — tag the contact, move a
      pipeline stage, send an SMS, book an appointment. Stored as a graph:
      `nodes` are the actions, `edges` say what follows what, and
      `dispositionEntries` maps each outcome to the node its chain starts at.


      **Pick the narrowest endpoint that does the job.**


      | To | Call | |

      | --- | --- | --- |

      | See what fires per outcome | `GET .../workflow/digest` | Reads as plain
      text, no graph walking |

      | Add steps to an outcome | `POST .../outcomes/{outcome}/nodes` | Server
      derives node ids, edge ids, handles, layout |

      | Change a message, tag or setting | `PATCH .../workflow` | Merges;
      carries no graph, so it cannot damage one |

      | Remove one step | `DELETE .../nodes/{nodeId}` | Also re-links the chain
      around it |

      | Author or replace the whole graph | `PUT .../workflow` | Replaces
      everything you send |


      `PUT` is the only one that can re-wire, position nodes, build an `if`,
      save an unconfigured draft, or copy a whole workflow — and the only one
      that can overwrite a change someone else made after you read it. Use it
      when you are genuinely authoring the graph, and send `expectedVersion`
      when you do. For everything else the narrower endpoints are both easier
      and safer.
  - name: Contacts
    description: Contact list, filters, contact call history, and do-not-call actions.
  - name: GHL
    description: CRM variables and contact helpers used by agent and campaign setup flows.
  - name: Phone Numbers
    description: >-
      Caller ID pool, number search, assignment, movement, and release
      endpoints.
  - name: Power Dialer
    description: >-
      Power Dialer queue, lead cadence, callback, parked lead, and campaign
      schedule endpoints.
  - name: Projects
    description: >-
      Project management endpoints: list, update, disconnect, configure project
      campaigns, and validate setup.
  - name: Skills and Tools
    description: Manage reusable agent behaviors and in-call tool descriptions.
  - name: Voices
    description: Voice catalogue endpoints for choosing the voice used by an agent.
paths:
  /api/agent-builder/agents/{id}/campaign:
    patch:
      tags:
        - Agents
      summary: Update campaign
      description: |-
        Update the campaign owned by this agent.

        Required API key scope: `campaigns:write`.
      operationId: update-agent-campaign
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
          description: Agent id.
          example: agent_1ffdb9717444d0e77346838911
        - name: locationId
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          description: Pair with campaignId; omit both for primary campaign.
          example: loc_abc123
        - name: campaignId
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          description: Pair with locationId; omit both for primary campaign.
          example: cmp_123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignsPatchCampaignRequest'
            examples:
              default:
                value:
                  active: true
                  activeTags:
                    - new_lead
                  inactiveTags:
                    - do_not_call
                  config:
                    calendarId: calendar_primary
      responses:
        '200':
          description: Campaign facet updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignsCampaignResponse'
              examples:
                default:
                  value:
                    success: true
                    campaign:
                      id: cmp_123
                      name: Roofing Follow Up
                      system: appointment_booking
                      agentType: appointment_booking
                      dialing: s2l_pd
                      active: true
                      isActive: false
                      type: s2l_pd
                      activeTags:
                        - new_lead
                      inactiveTags:
                        - do_not_call
                      callingWindow: null
                      config:
                        cadenceId: cad_123
                        calendarId: calendar_primary
                      fromNumbers:
                        - '+14155551234'
                      projectId: proj_123
                      locationId: loc_abc123
                      businessName: Acme Roofing
                      createdAt: '2026-07-08T10:00:00.000Z'
                      updatedAt: '2026-07-08T10:00:00.000Z'
        '400':
          description: Validation failed or the request body is malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentsErrorResponse'
              examples:
                default:
                  value:
                    success: false
                    error: VALIDATION
                    message: locationId is required.
                    details:
                      - field: locationId
                        message: locationId is required.
        '401':
          description: Missing or invalid authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentsErrorResponse'
              examples:
                default:
                  value:
                    success: false
                    error: Unauthorized
                    message: Authentication required.
        '403':
          description: >-
            Authenticated but missing the required `campaigns:write` scope or
            tenant access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentsErrorResponse'
              examples:
                default:
                  value:
                    success: false
                    error: FORBIDDEN
                    message: No access to agent "agent_1ffdb9717444d0e77346838911".
                insufficientScope:
                  value:
                    success: false
                    error: InsufficientScope
                    message: This API key does not have the required scope.
                    requiredScope: campaigns:write
        '404':
          description: Agent or related project not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentsErrorResponse'
              examples:
                default:
                  value:
                    success: false
                    error: NOT_FOUND
                    message: Agent "agent_1ffdb9717444d0e77346838911" not found.
        '409':
          description: Request conflicts with current agent state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentsErrorResponse'
              examples:
                default:
                  value:
                    success: false
                    error: IN_USE
                    message: Agent is referenced by one or more campaigns or projects.
                    references:
                      projectsV2:
                        - businessName: Acme Roofing
                          campaigns:
                            - id: cmp_123
                              name: Roofing Follow Up
                              agentId: agent_1ffdb9717444d0e77346838911
                      masterDb: []
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentsErrorResponse'
              examples:
                default:
                  value:
                    success: false
                    error: TooManyRequests
                    message: Too many requests, please try again later.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentsErrorResponse'
              examples:
                default:
                  value:
                    success: false
                    error: InternalError
                    message: Unexpected server error.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --request PATCH \
              --url https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign \
              --header 'Authorization: Bearer YOUR_API_KEY' \
              --header 'Content-Type: application/json' \
              --data '{
              "active": true,
              "activeTags": [
                "new_lead"
              ],
              "inactiveTags": [
                "do_not_call"
              ],
              "config": {
                "calendarId": "calendar_primary"
              }
            }'
components:
  schemas:
    CampaignsPatchCampaignRequest:
      type: object
      additionalProperties: {}
      minProperties: 1
      properties:
        name:
          type: string
          minLength: 1
          example: Speed to Lead
        active:
          type: boolean
          description: Switch the campaign live. Defaults to paused.
          example: true
        description:
          type: string
          example: Call new leads as soon as they enter the intake flow.
        activeTags:
          type: array
          items:
            type: string
          example:
            - new_lead
        inactiveTags:
          type: array
          items:
            type: string
          example:
            - do_not_call
        callIfDnd:
          type: boolean
          example: false
        agentId:
          type:
            - string
            - 'null'
          example: agent_2b7c9f4a
        dialing:
          type: string
          enum:
            - s2l
            - pd
            - s2l_pd
          description: Dispatch mode.
          example: s2l_pd
        callingWindow:
          oneOf:
            - $ref: '#/components/schemas/CampaignsCallingWindow'
            - type: array
              items:
                $ref: '#/components/schemas/CampaignsCallingWindow'
            - type: 'null'
        multipleTimezoneCheck:
          type: boolean
          example: true
        dropOutsideWindow:
          type: boolean
          example: false
        masterCampaignEnabled:
          type: boolean
          example: true
        config:
          $ref: '#/components/schemas/CampaignsConfig'
        fromNumbers:
          type: array
          items:
            type: string
          example:
            - '+14155551234'
    CampaignsCampaignResponse:
      type: object
      additionalProperties: false
      required:
        - success
        - campaign
      properties:
        success:
          type: boolean
        campaign:
          $ref: '#/components/schemas/CampaignsCampaign'
    AgentsErrorResponse:
      type: object
      additionalProperties: {}
      required:
        - success
        - error
        - message
      properties:
        success:
          type: boolean
        error:
          type: string
          description: Machine-readable error code.
          example: VALIDATION
        message:
          type: string
          description: Human-readable explanation safe to show to an operator.
          example: locationId is required.
        references:
          type: object
          additionalProperties: {}
          description: Structured conflict details. Present on delete conflicts.
        details:
          type: array
          description: Field-level validation details when available.
          items:
            type: object
            additionalProperties: false
            required:
              - field
              - message
            properties:
              field:
                type:
                  - string
                  - 'null'
                example: locationId
              message:
                type: string
                example: locationId is required.
    CampaignsCallingWindow:
      type: object
      additionalProperties: false
      required:
        - days
        - start
        - end
        - tz
      properties:
        days:
          type: array
          minItems: 1
          items:
            type: integer
            minimum: 1
            maximum: 7
          description: ISO weekday numbers. Monday is 1 and Sunday is 7.
          example:
            - 1
            - 2
            - 3
            - 4
            - 5
        start:
          type: string
          pattern: ^\d{2}:\d{2}$
          example: '09:00'
        end:
          type: string
          pattern: ^\d{2}:\d{2}$
          example: '17:00'
        tz:
          type: string
          example: America/New_York
    CampaignsConfig:
      type: object
      additionalProperties: {}
      properties:
        cadenceId:
          type: string
          example: cadence_123
        calendarId:
          type: string
          example: calendar_primary
        collectAddress:
          type: boolean
          example: true
        transferNumber:
          type: string
          example: '+14155550100'
        transferToAssignedUser:
          type: boolean
          example: false
        advancedRouting:
          type: boolean
          example: false
        transferRoutes:
          type: array
          items:
            $ref: '#/components/schemas/CampaignsTransferRoute'
        s2lDoubleDial:
          type: boolean
          example: true
        callbackDoubleDial:
          type: boolean
          example: true
        callNowSkipTags:
          type: array
          items:
            type: string
          example:
            - already_booked
        appliedTag:
          type: string
          description: >-
            Objective tag for `add_tag` agents: the GHL tag applied when the
            tagging objective is met.
          example: qualified_lead
        confirmedTag:
          type: string
          description: >-
            Objective tag for `appointment_confirmation` agents: the GHL tag
            applied when the appointment is confirmed.
          example: appt_confirmed
        fallbackTag:
          type: string
          description: >-
            Objective tag for `live_transfer_and_tag` agents: the GHL tag
            applied when the live transfer fails to connect, so the lead still
            gets follow-up.
          example: transfer_failed
    CampaignsCampaign:
      type: object
      additionalProperties: {}
      required:
        - id
        - name
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          example: campaign_speed_to_lead_123
        name:
          type: string
          example: Speed to Lead
        active:
          type: boolean
          description: The campaign's live state.
          example: false
        masterCampaignEnabled:
          type: boolean
          example: false
        description:
          type:
            - string
            - 'null'
          example: Call new leads as soon as they enter the intake flow.
        activeTags:
          type: array
          items:
            type: string
          example:
            - new_lead
        inactiveTags:
          type: array
          items:
            type: string
          example:
            - do_not_call
        callIfDnd:
          type: boolean
          example: false
        agentId:
          type:
            - string
            - 'null'
          example: agent_2b7c9f4a
        agentName:
          type:
            - string
            - 'null'
          example: Front Desk Agent
        system:
          type:
            - string
            - 'null'
          description: >-
            Legacy V2 template this campaign was cloned from. It is the clone
            SOURCE, not the campaign's behaviour: what the agent can do is
            decided by its installed capabilities, and on agents created since
            multi-capability support this value only reflects the FIRST
            capability selected. Read it as provenance. Normally one of
            `appointment_confirmation`, `appointment_booking`, `live_transfer`,
            `live_transfer_and_tag`, `live_transfer_and_booking`, `add_tag`,
            `inbound_receptionist`, but this field is returned as stored and is
            not validated on the way out, so treat an unfamiliar value as opaque
            rather than an error.
          example: live_transfer
        agentType:
          type:
            - string
            - 'null'
          enum:
            - appointment_confirmation
            - appointment_booking
            - live_transfer
            - live_transfer_and_tag
            - live_transfer_and_booking
            - add_tag
            - inbound_receptionist
            - null
          deprecated: true
          description: >-
            This module still speaks the seven legacy V2 template ids, so the
            value here is the same one as `system`, not the three-value campaign
            type the Agents module publishes. Null when the campaign carries no
            recognised template. Prefer `agentType` on the Agents module
            (`outreach`, `inbound`, `appointment`) plus the campaign's
            capabilities.
          example: appointment_booking
        dialing:
          type:
            - string
            - 'null'
          enum:
            - s2l
            - pd
            - s2l_pd
            - confirmation
            - reactivation
            - null
          description: >-
            Dispatch mode. Two values are read-only. `confirmation` is what a
            Reminder campaign stores; note that List agents reports the same
            campaign as `pd`, so the two endpoints differ on this field.
            `reactivation` is retired and reads only: campaigns created before
            it was withdrawn still report it and still dial, but it can no
            longer be set on a create or an update. Only `s2l`, `pd`, and
            `s2l_pd` are writable.
          example: s2l_pd
        callingWindow:
          oneOf:
            - $ref: '#/components/schemas/CampaignsCallingWindow'
            - type: array
              items:
                $ref: '#/components/schemas/CampaignsCallingWindow'
            - type: 'null'
        multipleTimezoneCheck:
          type: boolean
          example: true
        dropOutsideWindow:
          type: boolean
          example: false
        config:
          $ref: '#/components/schemas/CampaignsConfig'
        fromNumbers:
          type: array
          items:
            type: string
          example:
            - '+14155551234'
        agencyName:
          type:
            - string
            - 'null'
          example: Acme Agency
        projectId:
          type:
            - string
            - 'null'
          description: Id of the project this campaign belongs to.
          example: proj_123
        locationId:
          type:
            - string
            - 'null'
          description: CRM location id of the project this campaign belongs to.
          example: loc_abc123
        businessName:
          type:
            - string
            - 'null'
          description: Visible business name of the project this campaign belongs to.
          example: Acme Roofing
        isActive:
          type: boolean
          deprecated: true
          description: >-
            Storage spelling of `active`, still emitted for clients written
            before the canonical names. Same value. Build on `active`.
          example: false
        type:
          type:
            - string
            - 'null'
          deprecated: true
          description: >-
            Storage spelling of `dialing`, still emitted for clients written
            before the canonical names. Same value. Build on `dialing`.
          example: s2l_pd
        createdAt:
          type: string
          format: date-time
          example: '2026-07-08T16:20:00.000Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-07-08T16:30:00.000Z'
    CampaignsTransferRoute:
      type: object
      additionalProperties: false
      required:
        - id
        - number
        - condition
      properties:
        id:
          type: string
          example: route_sales
        number:
          type: string
          example: '+14155550100'
        condition:
          type: string
          example: Use for pricing or booking questions.
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Send your API key as `Authorization: Bearer YOUR_API_KEY`.'

````