Skip to main content
PATCH
/
api
/
v1
/
campaigns
/
{campaign_id}
/
status
# Request 1: Activate a draft campaign
curl -X PATCH "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1/status" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active"
  }'

{
  "success": true,
  "message": "Campaign status updated successfully",
  "data": {
    "id": "campaign-uuid-1",
    "status": "active",
    "updated_at": "2024-01-01T12:00:00Z"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.talkover.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Update Campaign Status

Update the status of a campaign to control its lifecycle. This endpoint allows you to activate, pause, complete, or cancel campaigns.

​
Endpoint

PATCH /api/v1/campaigns/{campaign_id}/status

​
Path Parameters

​
campaign
string
required
The unique identifier of the campaign. You can find this in your dashboard under Campaigns.

​
Request Headers

​
Authorization
string
required
Bearer token for authentication. Format: Bearer talq_your_environment_token_here
​
Content-Type
string
required
Application JSON. Format: application/json

​
Request Body

​
status
string
required
New status for the campaign. Options: draft, active, paused, completed, cancelled.

​
Valid Status Values

StatusDescription
draftCampaign is in draft mode and not yet active
activeCampaign is running and making calls
pausedCampaign is paused and not making new calls
completedCampaign has finished all scheduled calls
cancelledCampaign was cancelled and will not make more calls

​
Example Requests

# Request 1: Activate a draft campaign
curl -X PATCH "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1/status" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active"
  }'

# Request 2: Pause an active campaign
curl -X PATCH "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1/status" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paused"
  }'

# Request 3: Cancel a campaign
curl -X PATCH "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1/status" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "cancelled"
  }'

​
Response

​
Success Response (200 OK)

{
  "success": true,
  "message": "Campaign status updated successfully",
  "data": {
    "id": "campaign-uuid-1",
    "status": "active",
    "updated_at": "2024-01-01T12:00:00Z"
  }
}

​
Response Fields

​
success
boolean
required
Indicates if the operation was successful.
​
message
string
required
Success message describing the operation.
​
data
object
required
Updated campaign status data.

​
Error Responses

​
404 Not Found

{
  "success": false,
  "message": "Campaign not found"
}

​
422 Validation Error

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "status": [
      "The selected status is invalid."
    ]
  }
}

​
400 Bad Request

{
  "success": false,
  "message": "Cannot transition from active to draft status"
}

​
401 Unauthorized

{
  "success": false,
  "message": "Unauthorized"
}

​
403 Forbidden

{
  "success": false,
  "message": "Cannot update campaign status"
}

​
500 Server Error

{
  "success": false,
  "message": "Internal server error."
}

​
Error Codes

CodeDescriptionHTTP Status
CAMPAIGN_NOT_FOUNDSpecified campaign does not exist404
VALIDATION_ERRORInvalid status value provided422
INVALID_TRANSITIONInvalid status transition attempted400
INVALID_TOKENAuthentication token is invalid or missing401
FORBIDDENCannot update campaign status403
SERVER_ERRORInternal server error occurred500

​
Status Transition Rules

Current StatusAllowed Transitions
draftactive, cancelled
activepaused, completed, cancelled
pausedactive, completed, cancelled
completedNone (final state)
cancelledNone (final state)

​
Important Notes

Status transitions. Not all status transitions are allowed. See the transition rules above.
Final states. Once a campaign reaches completed or cancelled status, it cannot be changed.
Active campaigns. Activating a campaign will start making calls according to the schedule.
Paused campaigns. Pausing a campaign stops new calls but doesn’t affect calls already in progress.
Cancelled campaigns. Cancelling a campaign stops all future calls and cannot be undone.

​
Best Practices

  1. Check current status - Verify the current status before attempting transitions
  2. Plan transitions - Understand the allowed status transitions for your use case
  3. Monitor effects - Track how status changes affect campaign performance
  4. Handle errors - Implement proper error handling for invalid transitions
  5. Use appropriate statuses - Use paused for temporary stops and cancelled for permanent stops
  • Get Campaign: GET /api/v1/campaigns/{campaign_id}
  • Update Campaign: PUT /api/v1/campaigns/{campaign_id}
  • Create Campaign: POST /api/v1/campaigns
  • Delete Campaign: DELETE /api/v1/campaigns/{campaign_id}
  • List Campaigns: GET /api/v1/campaigns