Run campaign

This request starts a campaign and changes its status to RUNNING. Prospects enrolled in the campaign will be processed based on the campaign settings and delivery times.

Request

Endpoint

POST https://api.woodpecker.co/rest/v2/campaigns/{campaign_id}/run

Headers

x-api-key: {YOUR_API_KEY}

For details on how to authenticate your requests, please see the authentication guide.

Request samples

Request title

cURL

curl --request POST \
  --url "https://api.woodpecker.co/rest/v2/campaigns/{campaign_id}/run" \
  --header "x-api-key: {YOUR_API_KEY}"

Python

import requests

def runCampaign(campaign_id):
  url = f"https://api.woodpecker.co/rest/v2/campaigns/{campaign_id}/run"
  headers = {
    "x-api-key": "{YOUR_API_KEY}"
  }

  response = requests.post(url, headers=headers)

  if response.status_code == 200:
    print("POST successful — campaign is now running.")
  else:
    print("POST failed with status:", response.status_code)

if __name__ == "__main__":
  runCampaign(123)

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class WoodpeckerApiClient {
  private static final String API_KEY = "{YOUR_API_KEY}";

  public static void main(String[] args) {
    int campaignId = 123;
    runCampaign(campaignId);
  }

  public static void runCampaign(int campaignId) {
    try {
      String url = "https://api.woodpecker.co/rest/v2/campaigns/" + campaignId + "/run";

      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
        .uri(new URI(url))
        .header("x-api-key", API_KEY)
        .POST(HttpRequest.BodyPublishers.noBody())
        .build();

      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

      if (response.statusCode() == 200) {
        System.out.println("POST successful — campaign is now running.");
      } else {
        System.err.println("POST failed with status: " + response.statusCode());
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Node.js

const axios = require("axios");

async function runCampaign(campaignId) {
  const url = `https://api.woodpecker.co/rest/v2/campaigns/${campaignId}/run`;
  const headers = {
    "x-api-key": "{YOUR_API_KEY}"
  };

  try {
    const response = await axios.post(url, null, { headers: headers });

    if (response.status === 200) {
      console.log("POST successful — campaign is now running.");
    } else {
      console.error("POST failed with status:", response.status);
    }
  } catch (error) {
    console.error("Request error:", error.response?.status || error.message);
  }
}

runCampaign(123);

PHP

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new Client([
  'base_uri' => 'https://api.woodpecker.co/rest/v2/',
  'headers'  => [
    'x-api-key' => getenv('WOODPECKER_API_KEY'),
  ],
]);

$campaignId = '{campaign_id}';

try {
  $response = $client->post("campaigns/{$campaignId}/run");
  echo $response->getStatusCode(), "\n";
  echo $response->getBody(), "\n";
} catch (RequestException $e) {
  echo "Error: ", $e->getMessage(), "\n";
  if ($e->hasResponse()) {
    echo $e->getResponse()->getBody(), "\n";
  }
}

Response

Response examples

200

The campaign has been run.

Status: 200
Body: none

400

Invalid request or malformed syntax. Please review the request

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Value of campaign_id is incorrect.",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
detail	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC

401

An issue with authorization. Please review the authorization guide

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid api key",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
detail	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC

403

The campaign uses features that are not covered by your current subscription.

{
  "code": "MISSING_FEATURES",
  "message": "Upgrade your plan",
  "details": null
}

Body schema

Field	Type	Description
code	string	Error code
message	string	Descriptive error message
details	string/null	Additional information

404

The requested campaign doesn't exist.

{
  "code": "CAMPAIGN_NOT_EXIST",
  "message": "Campaign not found",
  "details": null
}

Body schema

Field	Type	Description
code	string	Error code
message	string	Descriptive error message
details	string/null	Additional information

409

The campaign configuration is invalid. This may be due to missing required fields or the use of features that are not currently supported by the API. Please review the campaign configuration for more details.

{
  "code": "VALIDATION_FAILURE" | "API_UNSUPPORTED_CAMPAIGN_FEATURES",
  "message": "Validation failure" | "Campaign contains currently unsupported features",
  "details": null
}

Body schema

Field	Type	Description
code	string	Error code
message	string	Descriptive error message
details	string/null	Additional information

500

Unexpected error, please try again later.

{
  "type": "UNKNOWN",
  "message": "Unknown error during run campaign call",
  "details": null
}