API Reference

Finish an active campaign gracefully

Finishes an active campaign gracefully by stopping workflows that have not started and draining workflows already in progress.

POST/v1/accounts/{accountGroupId}/campaigns/{campaignId}/finish

Integration notes

Required API permission

campaigns:write.

Prerequisites

integration_api_key, account_group_access.

Idempotency

send a stable Idempotency-Key header when retrying this request.

Parameters

accountGroupIdPath

Type: string

Account group ID that scopes the request.

Required

campaignIdPath

Type: string

Campaign ID that identifies the campaign to read or mutate.

Required

Idempotency-KeyHeader

Type: string

Request field for idempotency key.

Required

Request body

This endpoint does not define a request body.

Responses

200

Finishing campaign metadata and workflow summary

Schema: FinishingCampaignSuccessResponse

400

Request validation failed

Schema: ValidationErrorResponse

401

Invalid or missing API key

Schema: ErrorResponse

403

Missing required permission

Schema: ErrorResponse

404

Resource not found

Schema: ErrorResponse

409

Conflict — resource is in a state that prevents this operation

Schema: ErrorResponse

429

Rate limit exceeded

Schema: ErrorResponse

500

Internal server error

Schema: ErrorResponse

502

Upstream service error

Schema: ErrorResponse

Response examples

200 Example JSONFinishingCampaignSuccessResponse

{
    "success": true,
    "data": {
        "campaign": {
            "id": "507f1f77bcf86cd799439011",
            "name": "Avery Stone",
            "description": "string",
            "status": "draft",
            "selectedLeadCount": 25,
            "includeConversationHistory": true,
            "autoCancelOnMessageReceived": true,
            "outreachLanguage": "en",
            "businessHours": {
                "window": {
                    "start": "string",
                    "end": "string"
                },
                "days": [
                    "Mon"
                ],
                "timezone": "string"
            },
            "messageHours": {
                "window": {
                    "start": "string",
                    "end": "string"
                },
                "days": [
                    "Mon"
                ],
                "timezone": "string"
            },
            "maxRunsPerDay": 25,
            "createdAt": "string",
            "updatedAt": "string",
            "startedAt": "string",
            "finishRequestedAt": "string",
            "rateLimitedUntil": "string"
        },
        "instancesContinuing": 25,
        "instancesStopped": 25
    },
    "error": null,
    "traceId": "507f1f77bcf86cd799439011"
}

400 Example JSONValidationErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

401 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

403 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

404 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

409 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

429 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

500 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

502 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}