> ## Documentation Index > Fetch the complete documentation index at: https://docs.pineyard.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update a campaign. Allowed on DRAFT and PAUSED campaigns. **Required scope:** `campaigns.edit` Scopes apply to scoped API keys. Keys issued without scopes can call every `/v1` endpoint. ## OpenAPI ````yaml /api-reference/openapi.json patch /v1/campaigns/{id} openapi: 3.0.3 info: title: Pineyard API version: 1.0.0 description: >- Programmatic access to agents, campaigns, calls, phone numbers, WhatsApp and results in your Pineyard workspace. servers: - url: https://api.pineyard.ai description: Production security: - bearerAuth: [] paths: /v1/campaigns/{id}: patch: summary: Update a campaign. Allowed on DRAFT and PAUSED campaigns. parameters: - schema: type: string required: true name: id in: path requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 100 description: type: string nullable: true maxLength: 280 agentId: type: string minLength: 1 channel: type: string enum: - VOICE - WHATSAPP - VOICE_THEN_WHATSAPP - WHATSAPP_THEN_VOICE - CUSTOM - EMAIL whatsappOutreachTemplateId: type: string nullable: true whatsappTemplateByMetric: anyOf: - type: object properties: key: type: string minLength: 1 maxLength: 120 map: type: object additionalProperties: type: string minLength: 1 maxLength: 64 required: - key - map - type: object properties: {} additionalProperties: false messageDeclinedLeads: type: boolean workflowId: type: string nullable: true dailyMessageCap: type: integer nullable: true minimum: 1 maximum: 100000 outreachRules: type: array nullable: true items: type: object properties: trigger: type: string enum: - MESSAGE_REPLY - NO_REPLY_AFTER - CALL_ENDED afterDays: type: integer minimum: 1 maximum: 90 condition: oneOf: - type: object properties: kind: type: string enum: - ai_interested describe: type: string maxLength: 500 required: - kind - type: object properties: kind: type: string enum: - reply_contains any: type: array items: type: string minLength: 1 maxLength: 80 minItems: 1 maxItems: 20 required: - kind - any - type: object properties: kind: type: string enum: - metric_is key: type: string minLength: 1 maxLength: 120 values: type: array items: type: string minLength: 1 maxLength: 80 minItems: 1 maxItems: 20 required: - kind - key - values - type: object properties: kind: type: string enum: - call_outcome_in values: type: array items: type: string minLength: 1 maxLength: 40 minItems: 1 maxItems: 10 required: - kind - values conditions: type: array items: oneOf: - type: object properties: kind: type: string enum: - ai_interested describe: type: string maxLength: 500 required: - kind - type: object properties: kind: type: string enum: - reply_contains any: type: array items: type: string minLength: 1 maxLength: 80 minItems: 1 maxItems: 20 required: - kind - any - type: object properties: kind: type: string enum: - metric_is key: type: string minLength: 1 maxLength: 120 values: type: array items: type: string minLength: 1 maxLength: 80 minItems: 1 maxItems: 20 required: - kind - key - values - type: object properties: kind: type: string enum: - call_outcome_in values: type: array items: type: string minLength: 1 maxLength: 40 minItems: 1 maxItems: 10 required: - kind - values minItems: 1 maxItems: 5 match: type: string enum: - ALL - ANY default: ALL action: type: string enum: - HAND_OFF - STOP - MARK_INTERESTED default: HAND_OFF required: - trigger maxItems: 20 reservedConcurrency: type: integer minimum: 1 maximum: 10 variableMap: type: object additionalProperties: type: string uploadId: type: string countryCode: type: string pattern: ^\+\d{1,3}$ phoneColumn: type: string altPhoneColumns: type: array items: type: string minLength: 1 maxItems: 5 nameColumn: type: string firstNameColumn: type: string lastNameColumn: type: string removeInvalidRows: type: boolean transliterateCalleeNames: type: boolean timezone: type: string scheduledStartAt: type: string format: date-time scheduledEndAt: type: string format: date-time dailyWindowStart: type: string pattern: ^\d{2}:\d{2}$ dailyWindowEnd: type: string pattern: ^\d{2}:\d{2}$ retryCount: type: integer minimum: 0 maximum: 10 cooldownMinutes: type: integer minimum: 5 maximum: 43200 retryDelaysMinutes: type: array items: type: integer minimum: 1 maximum: 43200 maxItems: 10 retryConcurrencyPercent: type: integer nullable: true minimum: 0 maximum: 100 notificationUserIds: type: array items: type: string campaignTypeId: type: string nullable: true customExtractionKeys: type: array items: type: object properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ type: type: string enum: - string - number - integer - boolean - array - date - datetime description: type: string minLength: 1 maxLength: 500 required: - name - type - description maxItems: 40 source: type: string enum: - CSV - CRM_MANUAL - CRM_WEBHOOK - API defaultCrmConnectionId: type: string nullable: true defaultCrmSegmentId: type: string nullable: true contactMergeMode: type: string enum: - APPEND - REPLACE followupEnabled: type: boolean followupMaxAttempts: type: integer minimum: 1 maximum: 10 churnEnabled: type: boolean churnMaxAttempts: type: integer minimum: 1 maximum: 10 churnIntervalHours: type: integer minimum: 1 maximum: 2160 churnDelaysHours: type: array items: type: integer minimum: 1 maximum: 2160 maxItems: 10 goal: type: string nullable: true maxLength: 500 briefText: type: string nullable: true maxLength: 200000 briefFileName: type: string nullable: true maxLength: 255 incompleteRetryEnabled: type: boolean incompleteRetryMaxAttempts: type: integer minimum: 1 maximum: 5 incompleteRetryIntervalMinutes: type: integer minimum: 1 maximum: 1440 incompleteRetryDelaysMinutes: type: array items: type: integer minimum: 1 maximum: 1440 maxItems: 5 incompleteCallSeconds: type: integer minimum: 5 maximum: 300 referralMaxDepth: type: integer minimum: 0 maximum: 3 skipRetryOnFirstVoicemail: type: boolean messageRetryEnabled: type: boolean messageRetryMaxAttempts: type: integer minimum: 1 maximum: 10 messageRetryIntervalSeconds: type: integer minimum: 1 maximum: 604800 messageRetryDelaysSeconds: type: array items: type: integer minimum: 1 maximum: 604800 maxItems: 10 messageRetryWindowSeconds: type: integer minimum: 1 maximum: 2592000 messageRetryTieredEnabled: type: boolean messageRetryTransientMaxAttempts: type: integer minimum: 1 maximum: 100 autoReseedEnabled: type: boolean incompleteRetryBackfillToday: type: boolean incompleteRetryBackfill: type: object properties: kind: type: string enum: - today - hours - days - all value: type: integer minimum: 1 maximum: 2160 required: - kind churnBackfill: type: object properties: kind: type: string enum: - today - hours - days - all value: type: integer minimum: 1 maximum: 2160 required: - kind dailyDialCap: type: integer nullable: true minimum: 1 maximum: 100000 dialDays: type: array items: type: integer minimum: 0 maximum: 6 minItems: 1 maxItems: 7 evaluationMetrics: type: array items: type: object properties: key: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ label: type: string minLength: 1 maxLength: 60 allowedValues: type: array items: type: string minLength: 1 maxLength: 40 minItems: 2 maxItems: 24 prompt: type: string minLength: 1 maxLength: 5000 builtin: type: boolean required: - key - label - allowedValues - prompt maxItems: 12 required: - name responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string name: type: string description: type: string nullable: true agentId: type: string nullable: true agentName: type: string nullable: true channel: type: string enum: - VOICE - WHATSAPP - VOICE_THEN_WHATSAPP - WHATSAPP_THEN_VOICE - CUSTOM - EMAIL whatsappOutreachTemplateId: type: string nullable: true whatsappTemplateByMetric: nullable: true messageDeclinedLeads: type: boolean dailyMessageCap: type: number nullable: true outreachRules: type: array nullable: true items: type: object properties: trigger: type: string enum: - MESSAGE_REPLY - NO_REPLY_AFTER - CALL_ENDED afterDays: type: integer minimum: 1 maximum: 90 condition: oneOf: - type: object properties: kind: type: string enum: - ai_interested describe: type: string maxLength: 500 required: - kind - type: object properties: kind: type: string enum: - reply_contains any: type: array items: type: string minLength: 1 maxLength: 80 minItems: 1 maxItems: 20 required: - kind - any - type: object properties: kind: type: string enum: - metric_is key: type: string minLength: 1 maxLength: 120 values: type: array items: type: string minLength: 1 maxLength: 80 minItems: 1 maxItems: 20 required: - kind - key - values - type: object properties: kind: type: string enum: - call_outcome_in values: type: array items: type: string minLength: 1 maxLength: 40 minItems: 1 maxItems: 10 required: - kind - values conditions: type: array items: oneOf: - type: object properties: kind: type: string enum: - ai_interested describe: type: string maxLength: 500 required: - kind - type: object properties: kind: type: string enum: - reply_contains any: type: array items: type: string minLength: 1 maxLength: 80 minItems: 1 maxItems: 20 required: - kind - any - type: object properties: kind: type: string enum: - metric_is key: type: string minLength: 1 maxLength: 120 values: type: array items: type: string minLength: 1 maxLength: 80 minItems: 1 maxItems: 20 required: - kind - key - values - type: object properties: kind: type: string enum: - call_outcome_in values: type: array items: type: string minLength: 1 maxLength: 40 minItems: 1 maxItems: 10 required: - kind - values minItems: 1 maxItems: 5 match: type: string enum: - ALL - ANY default: ALL action: type: string enum: - HAND_OFF - STOP - MARK_INTERESTED default: HAND_OFF required: - trigger maxItems: 20 whatsappEnabled: type: boolean whatsappAgentTemplateIds: type: array items: type: string whatsappPaymentLinkEnabled: type: boolean recoveryLinkEnabled: type: boolean whatsappAutomations: type: array items: type: object properties: key: type: string label: type: string detail: type: string required: - key - label - detail workflowId: type: string nullable: true status: type: string reservedConcurrency: type: number variableMap: type: object additionalProperties: type: string countryCode: type: string nullable: true phoneColumn: type: string nullable: true altPhoneColumns: type: array items: type: string removeInvalidRows: type: boolean transliterateCalleeNames: type: boolean uploadId: type: string nullable: true timezone: type: string nullable: true scheduledStartAt: type: string nullable: true scheduledEndAt: type: string nullable: true dailyWindowStart: type: string nullable: true dailyWindowEnd: type: string nullable: true retryCount: type: number cooldownMinutes: type: number retryDelaysMinutes: type: array items: type: number retryConcurrencyPercent: type: number nullable: true startedAt: type: string nullable: true endedAt: type: string nullable: true createdAt: type: string updatedAt: type: string campaignTypeId: type: string nullable: true campaignTypeName: type: string nullable: true customExtractionKeys: type: array items: type: object properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ type: type: string enum: - string - number - integer - boolean - array - date - datetime description: type: string minLength: 1 maxLength: 500 required: - name - type - description effectiveExtractionKeys: type: array items: type: object properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ type: type: string enum: - string - number - integer - boolean - array - date - datetime description: type: string minLength: 1 maxLength: 500 required: - name - type - description notificationUserIds: type: array items: type: string source: type: string enum: - CSV - CRM_MANUAL - CRM_WEBHOOK - API - INBOUND defaultCrmConnectionId: type: string nullable: true defaultCrmSegmentId: type: string nullable: true followupEnabled: type: boolean followupMaxAttempts: type: number churnEnabled: type: boolean churnMaxAttempts: type: number churnIntervalHours: type: number churnDelaysHours: type: array items: type: number goal: type: string nullable: true incompleteRetryEnabled: type: boolean incompleteRetryMaxAttempts: type: number incompleteRetryIntervalMinutes: type: number incompleteRetryDelaysMinutes: type: array items: type: number incompleteCallSeconds: type: number referralMaxDepth: type: number skipRetryOnFirstVoicemail: type: boolean messageRetryEnabled: type: boolean messageRetryMaxAttempts: type: number messageRetryIntervalSeconds: type: number messageRetryDelaysSeconds: type: array items: type: number messageRetryWindowSeconds: type: number messageRetryTieredEnabled: type: boolean messageRetryTransientMaxAttempts: type: number autoReseedEnabled: type: boolean briefFileName: type: string nullable: true briefUploadedAt: type: string nullable: true briefText: type: string nullable: true dailyDialCap: type: number nullable: true dialDays: type: array items: type: number evaluationMetrics: type: array items: type: object properties: key: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ label: type: string minLength: 1 maxLength: 60 allowedValues: type: array items: type: string minLength: 1 maxLength: 40 minItems: 2 maxItems: 24 prompt: type: string minLength: 1 maxLength: 5000 builtin: type: boolean required: - key - label - allowedValues - prompt maxItems: 12 contactCount: type: number receivedCalls: type: number required: - id - name - agentId - agentName - channel - status - reservedConcurrency - variableMap - startedAt - endedAt - createdAt - updatedAt - campaignTypeId - campaignTypeName - customExtractionKeys - effectiveExtractionKeys - notificationUserIds - source - defaultCrmConnectionId - defaultCrmSegmentId '400': description: >- - `campaign_type_not_found`: campaignTypeId does not exist or is not ACTIVE. - `crm_connection_not_active`: CRM connection exists but is not ACTIVE. - `inbound_campaign_action_not_supported`: Operation is not valid for INBOUND campaigns (uploads, pause/resume/restart, source switch, re-engage, remessage, outreach). - `internal_error`: An unexpected error. A `400` with this code usually means the body is not valid JSON; a `413` means the body is larger than 1 MB. - `invalid_body`: The request body (or query) failed validation. Details are in `issues` (or `detail`). `422` on `POST /v1/campaigns/{campaignId}/leads`. - `metric_key_collision`: A metric key collides with an extraction field name. '401': description: >- - `invalid_api_key`: The API key is unknown, revoked or expired, or its workspace was deleted. - `unauthorized`: No `Authorization: Bearer` header, or an empty token. '403': description: >- - `api_key_not_allowed`: This action needs a person signed in to the dashboard (sign-ins, payments, email, and similar). - `api_key_owner_inactive`: The member the key acts for was removed or suspended. - `forbidden`: The key lacks the permission named in `requiredPermission`, or the resource belongs to another workspace. - `workspace_pending_approval`: The workspace has not been approved yet. - `workspace_suspended`: The workspace is suspended. '404': description: >- - `agent_not_found`: Agent id missing or not in this workspace (400 on POST /v1/campaigns, inbound-number assignment and suggest routes). - `campaign_not_found`: No campaign with that id in this workspace. - `workflow_not_found`: No workflow with that id (or workflows not enabled). '409': description: >- - `campaign_not_draft`: Campaign can only be changed in DRAFT (or PAUSED/CREDIT_EXHAUSTED for edits; contacts only in DRAFT). - `campaign_source_locked`: Campaign source cannot change once it has contacts or API deliveries, or is not DRAFT. - `workflow_not_active`: Workflow is not ACTIVE (not published or archived). '413': description: >- - `internal_error`: An unexpected error. A `400` with this code usually means the body is not valid JSON; a `413` means the body is larger than 1 MB. '429': description: '- `rate_limited`: Too many requests.' '500': description: >- - `internal_error`: An unexpected error. A `400` with this code usually means the body is not valid JSON; a `413` means the body is larger than 1 MB. '502': description: >- - `provider_error`: The calling service rejected the request (`upstreamStatus` 4xx) or was unavailable (5xx). '503': description: '- `database_unavailable`: The service is temporarily unavailable.' components: securitySchemes: bearerAuth: type: http scheme: bearer description: Your API key, e.g. `pk_live_xxxxxxxxxxxxxxxxxxxxxxxx`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.