List lead enrichments

List lead enrichment batches requested for the authenticated account. Use this endpoint after queueing lead enrichments to inspect requested jobs and their per-lead processing state.

If you already have a specific batch uuid, use get lead enrichment for a direct lookup.

Request

Endpoint

GET https://api.woodpecker.co/rest/v2/lead_finder/leads/enrichments

Headers

x-api-key: {YOUR_API_KEY}

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

Parameters

By default, the endpoint returns lead enrichment batches requested during the last 24 hours. Use created_after to fetch batches requested after the provided cutoff date.

Parameter	Required	Type	Description
created_after	No	string	Cutoff date in YYYY-MM-DD format. When provided, the endpoint returns batches requested after this date instead of using the default last-24-hours cutoff

Request samples

Retrieve lead enrichment batches

cURL

curl --request GET \
  --url "https://api.woodpecker.co/rest/v2/lead_finder/leads/enrichments?created_after=2026-05-01" \
  --header "x-api-key: {YOUR_API_KEY}"

Python

import requests

def get_lead_enrichments():
  url = "https://api.woodpecker.co/rest/v2/lead_finder/leads/enrichments"
  headers = {
    "x-api-key": "{YOUR_API_KEY}"
  }
  params = {
    "created_after": "2026-05-01"
  }

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

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

if __name__ == "__main__":
  get_lead_enrichments()

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

  public static void getLeadEnrichments() {
    try {
      String url = "https://api.woodpecker.co/rest/v2/lead_finder/leads/enrichments?created_after=2026-05-01";

      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 getLeadEnrichments() {
  const url = "https://api.woodpecker.co/rest/v2/lead_finder/leads/enrichments";
  const headers = {
    "x-api-key": "{YOUR_API_KEY}"
  };
  const params = {
    created_after: "2026-05-01"
  };

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

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

getLeadEnrichments();

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/leads/enrichments', [
    'query' => [
      'created_after' => '2026-05-01',
    ],
  ]);

  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

Lead enrichment batches for the authenticated account that match the selected cutoff. Use uuid with get lead enrichment when you need to inspect one batch directly.

{
  "lead_enrichments": [
    {
      "uuid": "e345310f-cfa7-42e3-b2fc-d888a332a899",
      "created": "2026-05-01T10:00:00+02:00",
      "leads": [
        {
          "uid": "0SVAICGlkzJ5fMrBxUdiQ_0000",
          "status": "PROCESSED",
          "processing_result": "NOT_CONVERTED_TO_PROSPECT"
        }
      ]
    },
    {
      "uuid": "eed003ca-b107-4126-bdb6-b5638737d508",
      "created": "2026-05-01T10:10:00+02:00",
      "leads": [
        {
          "uid": "0SVOUNZGlkzJ5fMcHsUdiQ_0000",
          "status": "PROCESSED",
          "processing_result": "NOT_CONVERTED_TO_PROSPECT"
        }
      ]
    }
  ]
}

Body schema

Field	Type	Description
lead_enrichments	array[object]	Recent lead enrichment batches
└─ uuid	string	Enrichment batch identifier
└─ created	string	Batch creation timestamp in ISO 8601 format
└─ leads	array[object]	Leads included in the batch
└─ uid	string	Lead identifier
└─ status	string	Processing status: PENDING or PROCESSED
└─ processing_result	string/null	Processing result: CONVERTED_TO_PROSPECT, NOT_CONVERTED_TO_PROSPECT, or null while pending

400

Invalid request or malformed request syntax.

{
  "title": "Bad Request",
  "status": 400,
  "details": "Value of created_after 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.

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