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 sample

Request title

cURL

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

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.IOException;
import java.net.URISyntaxException;

HttpClient client = HttpClient.newHttpClient();

long campaignId = 12345;
String apiKey = "YOUR_API_KEY";
String url = "https://api.woodpecker.co/rest/v2/campaigns/" + campaignId + "/run";

HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create(url))
  .header("x-api-key", apiKey)
  .POST(HttpRequest.BodyPublishers.noBody())
  .build();

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

Node.js

const runCampaign = async (campaignId, apiKey) => {
  const url = `https://api.woodpecker.co/rest/v2/campaigns/${campaignId}/run`;

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "x-api-key": apiKey,
    },
  });

  return await response.json();
};

try {
  const result = await runCampaign(12345, "YOUR_API_KEY");
  console.log(result);
} catch (error) {
  console.error("Error:", error);
}

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. Currently always null

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. Currently always null

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. Currently always null

500

Unknown error, please try again later.

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