Get search criteria

Retrieve the current list of Lead Finder criteria you can use when building a lead search request. The response is grouped into freetext criteria, where you provide your own value, and enumerated criteria, where you should first fetch allowed values from the search criteria values endpoint.

Use this endpoint as the source of truth for supported criteria instead of hardcoding the example list from the documentation. The criteria available to your account can change over time.

info

For enumerated criteria, call Get search criteria values before building your lead search request so you can use currently supported values.

Request

Endpoint

GET https://api.woodpecker.co/rest/v2/lead_finder/search_criteria

Headers

x-api-key: {YOUR_API_KEY}

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

Request samples

Retrieve the current Lead Finder criteria catalog

cURL

curl --request GET \
  --url "https://api.woodpecker.co/rest/v2/lead_finder/search_criteria" \
  --header "x-api-key: {YOUR_API_KEY}"

Python

import requests

def get_search_criteria():
  url = "https://api.woodpecker.co/rest/v2/lead_finder/search_criteria"
  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__":
  get_search_criteria()

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

  public static void getSearchCriteria() {
    try {
      String url = "https://api.woodpecker.co/rest/v2/lead_finder/search_criteria";

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

Node.js

const axios = require("axios");

async function getSearchCriteria() {
  const url = "https://api.woodpecker.co/rest/v2/lead_finder/search_criteria";
  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);
  }
}

getSearchCriteria();

PHP

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

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

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

try {
  $response = $client->get('lead_finder/search_criteria');
  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 examples

200

The current Lead Finder search criteria grouped by criterion type.

{
  "search_criteria": {
    "freetext": [
      { "name": "CITY" },
      { "name": "COMPANY_NAME" },
      { "name": "COMPANY_WEBSITE" },
      { "name": "COMPANY_CITY" },
      { "name": "FIRST_NAME" },
      { "name": "LAST_NAME" }
    ],
    "enumerated": [
      { "name": "INDUSTRY" },
      { "name": "CURRENT_JOB_TITLE" },
      { "name": "PAST_JOB_TITLE" },
      { "name": "COUNTRY" },
      { "name": "JOB_TITLE_LEVEL" },
      { "name": "JOB_TITLE_ROLE" },
      { "name": "GENDER" },
      { "name": "YEARS_OF_EXPERIENCE" },
      { "name": "COMPANY_COUNTRY" },
      { "name": "COMPANY_SIZE" },
      { "name": "COMPANY_TYPE" },
      { "name": "US_STATE" }
    ]
  }
}

Body schema

Field	Type	Description
search_criteria	object	Container for the currently supported Lead Finder criteria
└─ freetext	array[object]	Criteria where you provide your own value directly in the lead search payload
└─ [].name	string	Criterion name
└─ enumerated	array[object]	Criteria where you should first fetch allowed values from the search criteria values endpoint
└─ [].name	string	Criterion name

401

An issue with authorization. Please review the authentication guide.

{
  "title": "Unauthorized",
  "status": 401,
  "details": "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
details	string	A detailed message explaining the authorization problem
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC

404

Please review the request URL.

{
  "title": "Not Found",
  "status": 404,
  "details": "Requested resource does not exist",
  "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
details	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC

500

Unexpected error, please try again later.

{
  "title": "Internal server error",
  "status": 500,
  "details": "An unexpected error has occurred. Please try again later.",
  "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
details	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC