> ## Documentation Index > Fetch the complete documentation index at: https://docs.topcalls.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update a campaign > Partially update a campaign. Every field is optional; only the fields you send are changed. `status` can never be set here. Use the lifecycle endpoints (start/pause/resume/stop) to change it. `config` is merged shallowly with the campaign's existing configuration: keys you send overwrite the existing value, keys you omit are left untouched, and a key sent with value `null` deletes it from the stored configuration. Nested objects (e.g. `analysis_schema`) are replaced whole rather than merged. Values you provide (other than `null`) go through the same validation as `POST /v1/campaigns`. `lead_list_ids`, when included, replaces the campaign's full set of attached lead lists (an empty array detaches all of them). Omit the field to leave the current lists unchanged. A configuration change takes effect on the campaign's next dispatch buffer fill (typically within seconds), not on calls already queued. ## OpenAPI ````yaml /api-reference/openapi.json patch /v1/campaigns/{campaign_id} openapi: 3.0.3 info: title: TopCalls Voice API description: > TopCalls Voice Gateway API for creating and managing AI-powered phone calls. ## Authentication All API requests require authentication. Include your API key in the `Authorization` header: ``` Authorization: Bearer tc_live_xxxxx ``` ## Rate Limits Direct call creation via `POST /v1/calls` is limited to your account's `max_calls_per_minute` setting (default: 20) per minute. Exceeding it returns `429 Too Many Requests` with a `Retry-After` header. All endpoints are additionally subject to a flat limit of 120 requests per minute per account (all methods). On a `429`, wait for the number of seconds in the `Retry-After` header, then retry the same request. For automated clients, back off progressively on repeated `429`s. Limits are per account and are shared by all API keys. ## Error Format All errors follow RFC 7807 Problem+JSON format: ```json { "type": "https://api.topcalls.ai/errors/insufficient_quota", "title": "Insufficient Quota", "status": 402, "detail": "You need 5 minutes but have 3.5 remaining" } ``` version: 1.0.0 contact: name: TopCalls Support url: https://topcalls.ai license: name: Proprietary servers: - url: https://api.topcalls.ai description: Production security: [] tags: - name: Calls description: Create and manage phone calls - name: Phone Numbers description: Manage phone numbers and carriers - name: Account description: Account information and usage - name: Webhooks description: Webhook configuration and events - name: Configuration description: Available AI models, voices, and platform capabilities paths: /v1/campaigns/{campaign_id}: patch: tags: - Campaigns summary: Update a campaign description: | Partially update a campaign. Every field is optional; only the fields you send are changed. `status` can never be set here. Use the lifecycle endpoints (start/pause/resume/stop) to change it. `config` is merged shallowly with the campaign's existing configuration: keys you send overwrite the existing value, keys you omit are left untouched, and a key sent with value `null` deletes it from the stored configuration. Nested objects (e.g. `analysis_schema`) are replaced whole rather than merged. Values you provide (other than `null`) go through the same validation as `POST /v1/campaigns`. `lead_list_ids`, when included, replaces the campaign's full set of attached lead lists (an empty array detaches all of them). Omit the field to leave the current lists unchanged. A configuration change takes effect on the campaign's next dispatch buffer fill (typically within seconds), not on calls already queued. operationId: updateCampaign parameters: - name: campaign_id in: path required: true description: Campaign UUID schema: type: string format: uuid - $ref: '#/components/parameters/IdempotencyKeyHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateCampaignRequest' examples: rename: summary: Rename a campaign value: name: Spring outreach v2 clear_a_config_key: summary: Clear background_audio, keep other config keys value: config: background_audio: null replace_lead_lists: summary: Replace the attached lead lists value: lead_list_ids: - 564d4fd4-03bc-400a-abe0-05540fbeff88 responses: '200': description: Campaign updated content: application/json: schema: allOf: - $ref: '#/components/schemas/Campaign' - type: object properties: lead_list_ids: type: array items: type: string format: uuid '400': description: >- Invalid request body, empty body, or phone_number_ids/lead_list_ids not owned by your account content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: Campaign not found content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - bearerAuth: [] components: parameters: IdempotencyKeyHeader: name: Idempotency-Key in: header required: false description: | Optional client-supplied idempotency key. When present, the gateway caches the response for 24 hours and returns the same response on retried requests with the same key (account-scoped). Safe for retries on network blips. Format: 8-255 ASCII characters from `[A-Za-z0-9_-]`. schema: type: string minLength: 8 maxLength: 255 pattern: ^[A-Za-z0-9_-]+$ example: a1b2c3d4-e5f6-7890-abcd-ef0123456789 schemas: UpdateCampaignRequest: type: object description: | Request body for updating a campaign. Every field is optional, but the body must not be empty. `status` is never accepted here; use the lifecycle endpoints (start/pause/resume/stop) instead. `config` is merged shallowly with the campaign's existing configuration: an included key overwrites the existing value, an omitted key is left as-is, and a key sent with value `null` deletes it from the stored configuration. Nested objects are replaced whole, not deep-merged. Non-null config values are validated the same way as `POST /v1/campaigns`. `lead_list_ids`, when included, replaces the full set of lead lists attached to the campaign (send an empty array to detach all of them). Omit it to leave the current lists unchanged. A configuration change takes effect on the campaign's next dispatch buffer fill, not on calls already queued. properties: name: type: string minLength: 1 description: type: string timezone: type: string description: >- IANA timezone name used to interpret dispatch hours and schedule_time. dispatch_hours_start: type: string pattern: ^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d)?$ description: Local time of day dispatch may begin. Accepts HH:MM or HH:MM:SS. dispatch_hours_end: type: string pattern: ^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d)?$ description: Local time of day dispatch must stop. Accepts HH:MM or HH:MM:SS. dispatch_weekdays: type: array items: type: integer minimum: 1 maximum: 7 description: Weekdays dispatch is allowed, 1=Monday through 7=Sunday. dispatch_hours_overrides: type: object additionalProperties: type: array items: type: object required: - start - end properties: start: type: string pattern: ^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d)?$ end: type: string pattern: ^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d)?$ description: | Per-weekday overrides of the default dispatch hours, keyed by ISO weekday string ("1"-"7"). Each value is an array of time windows for that day; an empty array marks the day off entirely. max_attempts_per_lead: type: integer minimum: 1 max_parallel_calls: type: integer minimum: 1 schedule_time: type: string format: date-time description: >- When set to a future time, the campaign starts as scheduled instead of running immediately. lead_list_ids: type: array items: type: string format: uuid description: | Replaces the full set of lead lists attached to this campaign. Every id must belong to your account. Omit this field to leave the current lists unchanged; send an empty array to detach all of them. config: type: object additionalProperties: true description: | Shallow merge with the campaign's existing configuration. Send `null` for a key to delete it. Non-null values follow the same fields and validation as `CampaignConfig`. Campaign: type: object description: | Campaign record. Returned by GET /v1/campaigns and GET /v1/campaigns/{campaign_id}. Projected to this documented field set; additional internal columns are never included. additionalProperties: true properties: id: type: string format: uuid account_id: type: string format: uuid name: type: string description: type: string nullable: true status: type: string enum: - draft - scheduled - running - paused - completed - failed - cancelled timezone: type: string nullable: true description: >- IANA timezone name used to interpret dispatch hours and schedule_time. schedule_time: type: string format: date-time nullable: true dispatch_hours_start: type: string nullable: true description: Local time of day dispatch may begin, HH:MM:SS. dispatch_hours_end: type: string nullable: true description: Local time of day dispatch must stop, HH:MM:SS. dispatch_weekdays: type: array items: type: integer minimum: 1 maximum: 7 description: Weekdays dispatch is allowed, 1=Monday through 7=Sunday. dispatch_hours_overrides: type: object nullable: true additionalProperties: true description: Per-weekday overrides of the default dispatch hours. max_attempts_per_lead: type: integer max_parallel_calls: type: integer nullable: true conversion_outcomes: type: array items: type: string nullable: true outcome_mapping: type: object nullable: true additionalProperties: true pause_reason: type: string nullable: true config: type: object additionalProperties: true description: >- Call configuration applied to every call dispatched by this campaign. created_at: type: string format: date-time updated_at: type: string format: date-time nullable: true Problem: type: object required: - status - title properties: type: type: string format: uri description: Error type URI title: type: string description: Error title status: type: integer description: HTTP status code detail: type: string description: Human-readable error detail code: type: string description: > Machine-readable error code for programmatic handling. Present on errors that carry a stable identifier (e.g. `PROMPT_SAFETY_FRAUD`, `job_not_found`, `too_many_ids`, `no_matches`). Distinct from the per-field `errors[].code` used for validation failures. Scenario- specific — see each endpoint's response examples for the exact value. instance: type: string format: uuid description: Request instance ID errors: type: array description: Validation errors (for 400 responses) items: type: object properties: path: type: string description: Field path (e.g., "phone_number", "metadata.from_number") message: type: string description: Error message code: type: string description: Error code (e.g., "invalid_string", "custom") details: type: string description: Additional error details (for provider errors) responses: Unauthorized: description: Unauthorized (missing or invalid API key) content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: status: 401 title: Unauthorized detail: Invalid or missing API key Forbidden: description: Forbidden (missing required scope) content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: status: 403 title: Forbidden detail: 'Missing required scope: calls:write' securitySchemes: bearerAuth: type: http scheme: bearer description: | Use `Authorization: Bearer tc_live_xxxxx` ````