Get search criteria values

Retrieve allowed values for a selected Lead Finder criterion. Use this endpoint for enumerated criteria returned by Get search criteria, such as COUNTRY, INDUSTRY, JOB_TITLE_ROLE, or COMPANY_SIZE.

This endpoint supports filtering and pagination so you can power autocomplete or searchable dropdowns in your integration before calling the lead search endpoint. Pagination metadata is returned in the response body.

Request

Endpoint

GET https://api.woodpecker.co/rest/v2/lead_finder/search_criteria/{criterion_name}/values

Headers

x-api-key: {YOUR_API_KEY}

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

Parameters

Parameter	Required	Type	Description
criterion_name	Yes	string	Path parameter - the criterion whose allowed values you want to list. Use a criterion name returned by Get search criteria. Use capital letters
search_phrase	No	string	Text filter applied to the value list. The search matches partial substrings, so con can match construction as well as semiconductors. Maximum length: 50 characters.
page	No	integer	1-based page number. Default: 1. Minimum: 1.
limit	No	integer	Number of values to return per page. Default: 10. Minimum: 1. Maximum: 50.

Request samples

Retrieve past job title values

cURL

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

Python

import requests

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

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

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

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

getSearchCriteriaValues();

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/PAST_JOB_TITLE/values');
  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

A paginated list of matching values for the selected criterion.

{
  "criterion_name": "PAST_JOB_TITLE",
  "search_phrase": null,
  "page": 1,
  "limit": 10,
  "values": [
    "owner",
    "manager",
    "president",
    "director",
    "ceo",
    "teacher",
    "project manager",
    "partner",
    "principal",
    "intern"
  ],
  "total_found": 4999,
  "last": false
}

Body schema

Field	Type	Description
criterion_name	string	The criterion whose values were returned
search_phrase	string/null	The trimmed search phrase used to filter the values, or null when no filter was used
page	integer	Current 1-based page number
limit	integer	Maximum number of values returned in this page
values	array[string]	Matching values for the selected criterion
total_found	integer	Total number of matching values across all pages
last	boolean	Whether the current page is the last available page

400

Invalid request parameters or malformed request syntax. This can happen when criterion_name is not supported, page is lower than 1, limit is lower than 1, or search_phrase is longer than 50 characters.

{
  "title": "Bad Request",
  "status": 400,
  "details": "Value of {field} is incorrect.",
  "timestamp": "2025-03-05 17:57:00",
  "extra": null
}

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 which parameter was rejected
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC
extra	string/null	Additional information about the error, when available

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. Unsupported criterion names are returned as 400.

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