# Get a list of prospects

> **Documentation index**
> Browse the [Woodpecker developer documentation index](https://developers.woodpecker.co/llms.txt) to discover related API references, guides, webhooks, MCP tools, and CLI documentation.

> :::warning
This is a v1 legacy endpoint. It uses a different path `/rest/v1` and may return different error codes and [response formats](#response) compared to v2. While it remains functional, consider handling errors accordingly.
:::

:::warning
This is a v1 legacy endpoint. It uses a different path `/rest/v1` and may return different error codes and [response formats](#response) 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](#sorting-and-pagination) the prospects or [filter](#filtering) them by specific fields and values. 

If you are looking for: 
* prospects in a specific campaign - visit [this guide](https://developers.woodpecker.co/docs/prospects/get-prospects-campaign.md)
* searching for prospects - visit [this guide](https://developers.woodpecker.co/docs/prospects/get-search-prospects.md)

## 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](https://developers.woodpecker.co/docs/getting-started/authentication.md).

### 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`

<details> 
  <summary> Fields available for sorting </summary> 
  * 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
</details>

#### 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`.

  
  ```bash
  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}"
  ```
  
  
  ```Python
  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()
  ```
  
  
  ```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) {
      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();
      }
    }
  }
  ```
  
  
  ```js
  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
  <?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](#body-schema)

  ```json
  [
    {
      "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 |
| &nbsp;&nbsp;└─ `id` | integer | Unique identifier of a prospect |
| &nbsp;&nbsp;└─ `email` | string | Prospect's email address |
| &nbsp;&nbsp;└─ `first_name` | string | Prospect's first name |
| &nbsp;&nbsp;└─ `last_name` | string | Prospect's last name |
| &nbsp;&nbsp;└─ `company` | string | Prospect's company name |
| &nbsp;&nbsp;└─&nbsp;`organization_id` | integer | Unique identifier of a prospect's company |
| &nbsp;&nbsp;└─ `industry` | string | Prospect's industry |
| &nbsp;&nbsp;└─ `website` | string | Prospect's website URL |
| &nbsp;&nbsp;└─ `linkedin_url` | string | Prospect's LinkedIn profile URL |
| &nbsp;&nbsp;└─ `tags` | string | Tags associated with the prospect. Tags start with a `#` and are separated with a space |
| &nbsp;&nbsp;└─ `title` | string | Prospect's job title |
| &nbsp;&nbsp;└─ `phone` | string | Prospect's phone number |
| &nbsp;&nbsp;└─ `address` | string | Prospect's address |
| &nbsp;&nbsp;└─ `city` | string | Prospect's city |
| &nbsp;&nbsp;└─ `state` | string | Prospect's state or region |
| &nbsp;&nbsp;└─ `country` | string | Prospect's country |
| &nbsp;&nbsp;└─ `snippet_labels` | object | Custom snippet labels |
| &nbsp;&nbsp;&nbsp;&nbsp;└─└─ `label_name` | string | Key - value pairs representing a snippet label and its value |
| &nbsp;&nbsp;└─ `last_contacted` | string | Date when the prospect was last contacted (ISO 8601 format) |
| &nbsp;&nbsp;└─ `last replied` | string | Date when the prospect last replied (ISO 8601 format). Note the missing `_` |
| &nbsp;&nbsp;└─ `updated` | string | Date when the prospect was last updated (ISO 8601 format) |
| &nbsp;&nbsp;└─ `encrypted` | boolean | Whether a prospect is [encrypted](https://woodpecker.co/help-center/en/articles/5258897) |
| &nbsp;&nbsp;└─ `snipet` | string | Legacy. Always equal to the corresponding `snippetX` values. There are 4 snipet fields (`snipet1` to `snipet4`) |
| &nbsp;&nbsp;└─ `snippet` | string | Prospect custom snippets. There are 15 snippet fields (`snippet1` to `snippet15`) |
| &nbsp;&nbsp;└─ `status` | string | Prospect's **global** status |
| &nbsp;&nbsp;└─ `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 `-` |
| &nbsp;&nbsp;└─&nbsp;`interest_level` | object/null | Prospect's Interest Level information. Available only with `interested` parameter  |
| &nbsp;&nbsp;&nbsp;&nbsp;└─└─ `level` | string | Prospect's Interest Level. Available levels: `INTERESTED`, `MAYBE_LATER`, `NOT_INTERESTED` or `NOT_MARKED`  |
| &nbsp;&nbsp;&nbsp;&nbsp;└─└─&nbsp;`ai_detected` | boolean | Indicates whether the `level` was set by AI or by the user  |
| &nbsp;&nbsp;└─ `campaign_id` | integer/null | Available only with `interested` parameter. Campaign ID where the prospect has a defined interest level |
| &nbsp;&nbsp;└─ `sent_mails` | integer/null | Available only with `activity` parameter. Total number of emails sent in all campaigns |
| &nbsp;&nbsp;└─ `last_open` | string/null | Available only with `OPENED` activity parameter. Timestamp when the prospect has last opened an email |
| &nbsp;&nbsp;└─ `last_clicked` | string/null | Available only with `CLICKED` activity parameter. Timestamp when the prospect has last clicked a link in an email |
| &nbsp;&nbsp;└─ `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.

  ```json
  {
    "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.

  ```json
  {
    "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"
    }
  }
  ```

  #### Body schema

  A list of all available `status.code` values is available [here](https://developers.woodpecker.co/docs/prospects.md#error-codes)

  | 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                       |

  
  

  An issue with authorization. Please review the [authorization guide](https://developers.woodpecker.co/docs/getting-started/authentication.md)

  ```json
  {
    "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

  A list of all available `status.code` values is available [here](https://developers.woodpecker.co/docs/prospects.md#error-codes)

  | 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                       |

  
  

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

  ```json
  {
    "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

  A list of all available `status.code` values is available [here](https://developers.woodpecker.co/docs/prospects.md#error-codes)

  | 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                       |

  
  

  Please review the [request URL](#endpoint)

  ```json
  {
    "status": {
      "status": "ERROR",
      "code": "E_URL_NOT_FOUND",
      "msg": "URL not found: /Woodpecker/rest/v1/webhooks/someMadeUpURL"
    }
  }
  ```
  #### Body schema

  A list of all available `status.code` values is available [here](https://developers.woodpecker.co/docs/prospects.md#error-codes)

  | 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                       |

  
  

  Please review the [rate limits](https://developers.woodpecker.co/docs/getting-started/rate-limiting.md). API v1 is subject to the same rate limits as v2, however the response code is `409` instead of `429`. 

  ```json
  {
    "status": {
      "status": "ERROR",
      "code": "E_TOO_MANY_REQUESTS",
      "msg": "Too many requests in one time"
    }
  }
  ```
  #### Body schema

  A list of all available `status.code` values is available [here](https://developers.woodpecker.co/docs/prospects.md#error-codes)

  | 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                       |

  
  

  An unknown error. Please try again later. 

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

  #### Body schema

  A list of all available `status.code` values is available [here](https://developers.woodpecker.co/docs/prospects.md#error-codes)

  | 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                       |