Delete prospects

warning

This is a v1 legacy endpoint. It uses a different path /rest/v1 and may return different error codes and response formats compared to v2. While it remains functional, consider handling errors accordingly.

Delete prospects from your account, either globally (from the global prospect list) or locally (from specific campaigns). A prospect can exist in multiple campaigns but is always part of the global list. Deleting a prospect globally also removes them from any associated campaigns, while removing them from specific campaigns does not affect their presence in the global database.

The maximum length of the request URL is 4100 characters, approximately 360 prospects.

Request

Endpoint

DELETE https://api.woodpecker.co/rest/v1/prospects?id={prospect_id}

Headers

x-api-key: {YOUR_API_KEY}

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

Parameters

The endpoint requires the id parameter to specify which prospects to delete. The optional campaigns_id parameter allows targeting specific campaigns instead of deleting prospects globally.

Parameter	Required	Description
id	Yes	Comma-separated list of prospect IDs to delete
campaigns_id	No	Comma-separated list of campaigns from which the specified prospects should be removed.

Request sample

Delete two prospects globally

cURL

curl --request DELETE \
  --url "https://api.woodpecker.co/rest/v1/prospects?id={prospect_id1},{prospect_id2}" \
  --header "x-api-key: {YOUR_API_KEY}"

Java

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class WoodpeckerApiClient {
  public static void main(String[] args) {
    try {
      String apiKey = "YOUR_API_KEY";
      String url = "https://api.woodpecker.co/rest/v1/prospects?id={prospect_id1},{prospect_id2}";

      HttpURLConnection connection = (HttpURLConnection) new URL(url).openConnection();
      connection.setRequestMethod("DELETE");
      connection.setRequestProperty("x-api-key", apiKey);

      int responseCode = connection.getResponseCode();
      System.out.println("Response Code: " + responseCode);

      BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
      String inputLine;
      StringBuilder response = new StringBuilder();
      while ((inputLine = in.readLine()) != null) {
        response.append(inputLine);
      }
      in.close();

      System.out.println(response.toString());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Node.js

const axios = require("axios");

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://api.woodpecker.co/rest/v1/prospects";

async function deleteProspects(prospectIds) {
  if (!prospectIds || prospectIds.length === 0) {
    throw new Error("Prospect IDs list cannot be empty.");
  }

  const url = `${BASE_URL}?id=${prospectIds.join(",")}`;

  try {
    const response = await axios.delete(url, {
      headers: { "x-api-key": API_KEY },
    });

    console.log("Prospects deleted successfully:", response.status);
  } catch (error) {
    console.error("Error deleting prospects:", error.response ? error.response.data : error.message);
  }
}

const prospectIds = ["prospect_id1", "prospect_id2"];
deleteProspects(prospectIds);

Response

Response examples

200

Request processed successfully. If the specified prospects existed globally or in the given campaigns, they were removed.

Status: 200
Body: None

401

An issue with authorization. Please review the authorization guide

{
  "status": {
    "status": "ERROR",
    "code": "E_SESSION",
    "msg": "The API key you've entered is incorrect or no longer valid. Check if you pasted the key correctly. You can generate a new key in Woodpecker: Settings -> API Keys."
  }
}

Body schema

Field	Data Type	Description
status	object	Contains error details
└─status	string	Overall status, set to ERROR for non-2xx responses
└─code	string	Code indicating the error category
└─msg	string	Descriptive error message

403

API access denied. You subscription might not be active, lack the API add-on, or the key belongs to an inactive client company.

{
  "status": {
    "status": "ERROR",
    "code": "E_NO_PERMISSION",
    "msg": "Api access denied." | "You need to have an API keys addon to access our API."
  }
}

Body schema

Field	Data Type	Description
status	object	Contains error details
└─status	string	Overall status, set to ERROR for non-2xx responses
└─code	string	Code indicating the error category
└─msg	string	Descriptive error message

404

Please review the request URL

{
  "status": {
    "status": "ERROR",
    "code": "E_URL_NOT_FOUND",
    "msg": "URL not found: /Woodpecker/rest/v1/webhooks/someMadeUpURL"
  }
}

Body schema

Field	Data Type	Description
status	object	Contains error details
└─status	string	Overall status, set to ERROR for non-2xx responses
└─code	string	Code indicating the error category
└─msg	string	Descriptive error message

409

Please review the rate limits. API v1 is subject to the same rate limits as v2, however the response code is 409 instead of 429.

{
  "status": {
    "status": "ERROR",
    "code": "E_TOO_MANY_REQUESTS",
    "msg": "Too many requests in one time"
  }
}

Body schema

Field	Data Type	Description
status	object	Contains error details
└─status	string	Overall status, set to ERROR for non-2xx responses
└─code	string	Code indicating the error category
└─msg	string	Descriptive error message

500

An unknown error. Please review the request parameters and try again later.

{
  "status": {
    "status": "ERROR",
    "code": "E_UNNOWN",
    "msg": "Unknown error."
  }
}

Body schema

Field	Data Type	Description
status	object	Contains error details
└─status	string	Overall status, set to ERROR for non-2xx responses
└─code	string	Code indicating the error category
└─msg	string	Descriptive error message