List prospect enrichments

List prospect enrichment statuses for the authenticated account. Use this endpoint after queueing prospect enrichments to inspect recent enrichment jobs and their per-prospect processing state.

With an empty request, this endpoint returns recent prospect enrichment statuses. With an emails filter, it returns statuses for the selected prospects. If you already know the batch uuid, use get prospect enrichment for a direct lookup.

Request

Endpoint

POST https://api.woodpecker.co/rest/v2/lead_finder/prospects/enrichments/statuses/query

Headers

x-api-key: {YOUR_API_KEY}
Content-Type: application/json

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

Body

To retrieve recent prospect enrichment statuses, send an empty body. To retrieve statuses for selected prospects, send emails:

{
  "emails": [
    "erlich@bachmanity.com"
  ]
}

Body schema

Field	Type	Required	Description
emails	array[string]	No	Optional list of prospect emails to filter by

Request samples

Query statuses for selected prospect emails

cURL

curl --request POST \
  --url "https://api.woodpecker.co/rest/v2/lead_finder/prospects/enrichments/statuses/query" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "emails": [
      "erlich@bachmanity.com"
    ]
  }'

Python

import requests

def query_prospect_enrichment_statuses():
  url = "https://api.woodpecker.co/rest/v2/lead_finder/prospects/enrichments/statuses/query"
  headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json"
  }
  payload = {
    "emails": [
      "erlich@bachmanity.com"
    ]
  }

  response = requests.post(url, headers=headers, json=payload)

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

if __name__ == "__main__":
  query_prospect_enrichment_statuses()

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

  public static void queryProspectEnrichmentStatuses() {
    try {
      String url = "https://api.woodpecker.co/rest/v2/lead_finder/prospects/enrichments/statuses/query";
      String jsonData = """
        {
          "emails": [
            "erlich@bachmanity.com"
          ]
        }
        """;

      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
        .uri(new URI(url))
        .header("x-api-key", API_KEY)
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(jsonData))
        .build();

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

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

Node.js

const axios = require("axios");

async function queryProspectEnrichmentStatuses() {
  const url = "https://api.woodpecker.co/rest/v2/lead_finder/prospects/enrichments/statuses/query";
  const headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json"
  };
  const data = {
    emails: [
      "erlich@bachmanity.com"
    ]
  };

  try {
    const response = await axios.post(url, data, { headers });

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

queryProspectEnrichmentStatuses();

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'),
    'Content-Type' => 'application/json',
  ],
]);

try {
  $response = $client->post('lead_finder/prospects/enrichments/statuses/query', [
    'json' => [
      'emails' => [
        'erlich@bachmanity.com',
      ],
    ],
  ]);

  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

Prospect enrichment statuses for the authenticated account. Use uuid with get prospect enrichment when you need to inspect one batch directly.

{
  "prospect_enrichments": [
    {
      "uuid": "e9e6abc4-799e-4c22-b412-7917b1db919d",
      "prospect_email": "erlich@bachmanity.com",
      "created": "2026-05-15T11:14:56+02:00",
      "status": "PROCESSED_NOT_ENRICHED"
    },
    {
      "uuid": "e9e6abc4-799e-4c22-b412-7917b1db919d",
      "prospect_email": "jared@piedpiper.com",
      "created": "2026-05-15T11:14:56+02:00",
      "status": "PROCESSED_ENRICHED"
    }
  ]
}

Body schema

Field	Type	Description
prospect_enrichments	array[object]	Prospect enrichment status records
└─ uuid	string	Enrichment batch identifier
└─ prospect_email	string	Prospect email address
└─ created	string	Record creation timestamp in ISO 8601 format
└─ status	string	Processing status. PENDING - enrichment is queued or still being processed PROCESSED_ENRICHED - enrichment finished and found additional prospect data PROCESSED_NOT_ENRICHED - enrichment finished but did not find additional prospect data

400

Invalid request or malformed request syntax.

{
  "title": "Bad Request",
  "status": 400,
  "details": "string",
  "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 the validation or request problem
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.

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