Search for 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.

Search for prospects that match your criteria, including email, company, tags, and other available fields.

Retrieve a paginated list of prospects in your account, each containing snippet data, global status, and key dates such as the last contacted date.

The campaigns_details object provides information about the campaigns a prospect is enrolled in, including their campaign status, local status, and interest level. You can also sort prospects or filter them by specific fields and values.

Fields available for searching

email
first_name
last_name
company
organization_id
industry
website
tags
title
phone
address
city
state
country
snipet1 - snipet4
snippet5 - snippet15

Request

Endpoint

GET https://api.woodpecker.co/rest/v1/prospects?campaigns_details=true&search={search-field}={search_value},{search-field-2}={search_value-2}

Headers

x-api-key: {YOUR_API_KEY}

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

Parameters

Searching

Use the search parameter to find prospects matching your specific criteria

Parameter	Required	Type	Description
`search`	Yes	string	Comma-separated list of search criteria. A full list of searchable fields is available below. for `email`, you can use a full email address format `recipientname@mail.com` for an exact match or a string `recipientname` to look for a regex match `.recipientname.` You can search through multiple fields, for example: `?search=email=drew,company=companyName` Multiple search fields use `AND` operator; multiple fields of the same type use `OR` Fields other than `email` and `organization_id` use broad search `.{search-value}.`

Fields available for searching

email
first_name
last_name
company
organization_id
industry
website
tags
title
phone
address
city
state
country
snipet1 - snipet4
snippet5 - snippet15

Filtering

You can filter results by using one or more of the following parameters:

Parameter	Required	Type	Description
`campaigns_details`	No	boolean	Whether to add details of campaigns a prospect belongs to
`status`	No	string	Prospect's global status: `ACTIVE`, `BOUNCED`, `REPLIED`, `BLACKLIST`, `INVALID`
`campaigns_id`	No	integer	Comma-separated list of campaign IDs that prospects are enrolled in. Using this parameter will result in response body as described in getting prospects in campaign - refer to this guide
`contacted`	No	boolean	Whether a prospect has ever been contacted
`interested`	No	string	Returns prospects only if they have a specific interest level set in any of the campaigns they are enrolled in. Available values: `INTERESTED`, `MAYBE-LATER`, `NOT-INTERESTED`, `NOT-MARKED`
`diff`	No	string	Return prospects whose activity timestamp is greater than the provided date. Uses ISO 8601-like format: `2025-01-15T00:00:00%2B0200`. Available timestamps: `updated`, `last_opened` (only with `OPENED` activity paramater), `last_clicked` (only with `CLICKED` activity paramater)

Sorting and pagination

Parameter	Required	Type	Description
`page`	No	integer	Requested results page (1-based)
`per_page`	No	integer	Number of records per page. Default: 100, maximum: 1000
`sort`	No	string	Order the results based on the specified column. Default: order by ID ascending

For sorting, use + before the field name for ascending order and - for descending order. To sort by multiple fields, separate them with a comma.

To sort prospects by company name ascending and last_contacted date descending use: sort=+company,-last_contacted

Fields available for sorting

id
status
updated
email
last_contacted
last_replied
first_name
last_name
company
organization_id
industry
website
tags
title
phone
address
city
state
country
snipet1 - snipet4
snippet5 - snippet15
last_opened - available only with OPENED activity paramater
last_clicked - available only with CLICKED activity paramater
sent_mails - available only with OPENED or CLICKED activity paramater

Request sample

Search for prospects

The example below showcases how to search for a prospect with a specific email, together with details about the campaigns they are enrolled to.

cURL
Java
Node.js

curl --request GET \
  --url "https://api.woodpecker.co/rest/v1/prospects?campaigns_details=true&search=email=recipientname@mail.com" \
  --header "x-api-key: {YOUR_API_KEY}"

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

public class WoodpeckerApiClient {
  public static void main(String[] args) {
    try {
      HttpClient client = HttpClient.newHttpClient();

      HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.woodpecker.co/rest/v1/prospects?campaigns_details=true&search=email=recipientname@mail.com"))
            .header("x-api-key", "{YOUR_API_KEY}")
            .GET()
            .build();

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

      System.out.println("Response Code: " + response.statusCode());
      System.out.println("Response: " + response.body());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

const axios = require("axios");

const API_URL = "https://api.woodpecker.co/rest/v1/prospects?campaigns_details=true&search=email=recipientname@mail.com";
const API_KEY = "{YOUR_API_KEY}";

async function searchProspects() {
  try {
    const response = await axios.get(API_URL, {
      headers: {
        "x-api-key": API_KEY,
      },
    });

    console.log("Response Status:", response.status);
    console.log("Response Data:", response.data);
  } catch (error) {
    console.error("Error:", error.response ? error.response.data : error.message);
  }
}

searchProspects();

Response

Response examples

An array of prospect objects. Some fields will be returned only when the request uses specific paramaters. Such properties are not available in the example below and have a note in the body schema

[
  {
    "id": 1234567890,
    "email": "erlich@bachmanity.com",
    "first_name": "Erlich",
    "last_name": "Bachman",
    "company": "Bachmanity",
    "organization_id": 654321789,
    "industry": "IT",
    "website": "https://bachmanity.com",
    "linkedin_url": "https://linkedin.com/erlich-bachman",
    "tags": "#VISIONARY",
    "title": "CEO",
    "phone": "+1 987-654-321",
    "address": "700 Welch Road",
    "city": "Palo Alto",
    "state": "California",
    "country": "United States",
    "last_contacted": "2025-03-20T14:32:34+0100",
    "last replied": "2025-03-21T08:11:35+0100",
    "updated": "2025-03-21T08:11:35+0100",
    "encrypted": false,
    "snipet1": "You are running a successful startup incubator Bachmanity",
    "snipet2": "",
    "snipet3": "",
    "snipet4": "",
    "snippet1": "",
    "snippet2": "",
    "snippet3": "",
    "snippet4": "",
    "snippet5": "",
    "snippet6": "",
    "snippet7": "",
    "snippet8": "",
    "snippet9": "",
    "snippet10": "",
    "snippet11": "",
    "snippet12": "",
    "snippet13": "",
    "snippet14": "",
    "snippet15": "",
    "snippet_labels": { "custom_snippet": "You are running a successful startup incubator Bachmanity" },
    "status": "REPLIED",
    "campaigns_details": [
      {
        "campaign_id": 654321,
        "campaign_name": "SaaS in America",
        "campaign_status": "RUNNING",
        "campaign_prospect_status": "ACTIVE",
        "interested": "NOT_MARKED"
      },
      {
        "campaign_id": 987654,
        "campaign_name": "SaaS in Europe",
        "campaign_status": "RUNNING",
        "campaign_prospect_status": "REPLIED",
        "interested": "INTERESTED"
      }
    ]
  }
]

Body schema

Field	Type	Description
`[].prospect`	object	Contains prospect data
└─ `id`	integer	Unique identifier of a prospect
└─ `email`	string	Prospect's email address
└─ `first_name`	string	Prospect's first name
└─ `last_name`	string	Prospect's last name
└─ `company`	string	Prospect's company name
└─ `organization_id`	integer	Unique identifier of a prospect's company
└─ `industry`	string	Prospect's industry
└─ `website`	string	Prospect's website URL
└─ `linkedin_url`	string	Prospect's LinkedIn profile URL
└─ `tags`	string	Tags associated with the prospect. Tags start with a `#` and are separated with a space
└─ `title`	string	Prospect's job title
└─ `phone`	string	Prospect's phone number
└─ `address`	string	Prospect's address
└─ `city`	string	Prospect's city
└─ `state`	string	Prospect's state or region
└─ `country`	string	Prospect's country
└─ `snippet_labels`	object	Custom snippet labels
└─└─ `label_name`	string	Key - value pairs representing a snippet label and its value
└─ `last_contacted`	string	Date when the prospect was last contacted (ISO 8601 format)
└─ `last replied`	string	Date when the prospect last replied (ISO 8601 format). Note the missing `_`
└─ `updated`	string	Date when the prospect was last updated (ISO 8601 format)
└─ `encrypted`	boolean	Whether a prospect is encrypted
└─ `snipet`	string	Legacy. Always equal to the corresponding `snippetX` values. There are 4 snipet fields (`snipet1` to `snipet4`)
└─ `snippet`	string	Prospect custom snippets. There are 15 snippet fields (`snippet1` to `snippet15`)
└─ `status`	string	Prospect's global status
└─ `campaigns_details`	array[object]	Campaign details
└─└─ `[].campaign_id`	integer	Campaign ID the prospect is enrolled in
└─└─ `[].campaign_name`	string	Campaign name
└─└─ `[].campaign_status`	string	Current status of the campaign. Available values: `RUNNING`, `DRAFT`, `STOPPED`, `PAUSED`, `EDITED`, `COMPLETED`
└─└─ `[].campaign_prospect_status`	string	Current campaign status of a prospect. Available values: `ACTIVE`, `BOUNCED`, `TO-CHECK`, `TO-REVIEW`, `REPLIED`, `AUTOREPLIED`, `BLACKLIST`, `PAUSED`, `INVALID`
└─└─ `[].interested`	string	Interest level of a prospect in a given campaign. Available values: `INTERESTED`, `MAYBE_LATER`, `NOT_INTERESTED`, `NOT_MARKED`.
└─└─ `[].sent_mails`	integer/null	Available only with `activity` parameter. Total number of emails sent in all campaigns
└─└─ `[].last_open`	string/null	Available only with `OPENED` activity parameter. Timestamp when the prospect has last opened an email
└─└─ `[].last_clicked`	string/null	Available only with `CLICKED` activity parameter. Timestamp when the prospect has last clicked a link in an email
└─└─ `[].click_url`	string/null	Available only with `CLICKED` activity parameter. URL of the clicked link. Each clicked link will result in a separate prospect object

There are no prospects matching your criteria. Please review the request parameters and your prospect database.

{
  "message": "There are no prospects matching the given criteria."
}

Body schema

Field	Data Type	Description
`message`	string	Descriptive response message

Invalid request or malformed request syntax.

{
  "status": {
    "status": "ERROR",
    "code": "E_WRONG_PARAM",
    "msg": "Wrong param [param_name]=requested_param" | "Unknown param:madeUpParam" | "Wrong param, required activity=OPENED|NOT-OPENED" | "Wrong param, required activity=CLICKED|NOT-CLICKED"
  }
}