Get a list of 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.

Retrieve a paginated list of prospects available in your account. Each prospect is returned together with their snippet data, global status, dates like last_contacted date. You can sort the prospects or filter them by specific fields and values.

If you are looking for:

prospects in a specific campaign - visit this guide
searching for prospects - visit this guide

Request

Endpoint

GET https://api.woodpecker.co/rest/v1/prospects

Headers

x-api-key: {YOUR_API_KEY}

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

Parameters

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

Filtering

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

Parameter	Required	Type	Description
`id`	No	integer	Comma-separated list of prospect IDs to retrieve
`status`	No	string	Prospect's global status: `ACTIVE`, `BOUNCED`, `REPLIED`, `BLACKLIST`, `INVALID`
`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`. A prospect marked INTERESTED in N campaigns will return N prospect objects. Please mind `_` in the response
`activity`	No	string	Returns prospects based on their click and open activity. Available values: `OPENED`, `NOT-OPENED`, `CLICKED`, `NOT-CLICKED`
`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)

Request samples

Get a list of prospects

The example below showcases how to fetch last 50 most recently updated prospects with a global status REPLIED.

cURL
Python
Java
Node.js
PHP

curl --request GET \
  --url "https://api.woodpecker.co/rest/v1/prospects?sort=-updated&status=REPLIED&per_page=50" \
  --header "x-api-key: {YOUR_API_KEY}"

import requests

def getRepliedProspects():
  url = "https://api.woodpecker.co/rest/v1/prospects?sort=-updated&status=REPLIED&per_page=50"
  headers = {
    "x-api-key": "{YOUR_API_KEY}"
  }

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

  if response.status_code == 200:
    print("GET successful:", response.json())
  else:
    print("GET failed with status:", response.status_code)

if __name__ == "__main__":
  getRepliedProspects()

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) {
    getRepliedProspects();
  }

  public static void getRepliedProspects() {
    try {
      String url = "https://api.woodpecker.co/rest/v1/prospects?sort=-updated&status=REPLIED&per_page=50";

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

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

      if (response.statusCode() == 200) {
        System.out.println("GET response: " + response.body());
      } else {
        System.err.println("GET request failed: " + response.statusCode());
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

const axios = require("axios");

async function getRepliedProspects() {
  const url = "https://api.woodpecker.co/rest/v1/prospects?sort=-updated&status=REPLIED&per_page=50";
  const headers = {
    "x-api-key": "{YOUR_API_KEY}"
  };

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

    if (response.status === 200) {
      console.log("GET successful:", response.data);
    } else {
      console.error("GET failed with status:", response.status);
    }
  } catch (error) {
    console.error("Request error:", error.response?.status || error.message);
  }
}

getRepliedProspects();

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

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

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

try {
  $response = $client->get('prospects', [
    'query' => [
      'sort'     => '-updated',
      'status'   => 'REPLIED',
      'per_page' => 50,
    ],
  ]);
  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 headers

Header	Type	Description
`X-Total-Count`	integer	Total number of prospects that match the criteria. Do not use together with `campaigns_details` parameter

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-404xyz",
    "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"
  }
]

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
└─ `interested`	string/null	Deprecated. Available only with `interested` parameter and when an interest level is defined. Available values: `INTERESTED`, `MAYBE-LATER`, `NOT-INTERESTED`. Please mind `_` instead of `-`
└─ `interest_level`	object/null	Prospect's Interest Level information. Available only with `interested` parameter
└─└─ `level`	string	Prospect's Interest Level. Available levels: `INTERESTED`, `MAYBE_LATER`, `NOT_INTERESTED` or `NOT_MARKED`
└─└─ `ai_detected`	boolean	Indicates whether the `level` was set by AI or by the user
└─ `campaign_id`	integer/null	Available only with `interested` parameter. Campaign ID where the prospect has a defined interest level
└─ `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"
  }
}