Get lead enrichment

Retrieve one lead enrichment batch by its uuid. Use this endpoint after queueing lead enrichments when you already know the batch ID and want the most direct status check.

If you need to browse recent batches first, use list lead enrichments.

Request

Endpoint

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

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
uuid	Yes	string	Enrichment batch UUID returned by queue lead enrichments

Request samples

Retrieve one lead enrichment batch

cURL

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

Python

import requests

def get_lead_enrichment():
  url = "https://api.woodpecker.co/rest/v2/lead_finder/leads/enrichments/{uuid}"
  headers = {
    "x-api-key": "{YOUR_API_KEY}"
  }

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

  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_enrichment()

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

  public static void getLeadEnrichment() {
    try {
      String url = "https://api.woodpecker.co/rest/v2/lead_finder/leads/enrichments/{uuid}";

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

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

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

getLeadEnrichment();

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/{uuid}');

  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

Successfully fetched status details for a lead enrichment batch.

{
  "lead_enrichment": {
    "uuid": "088e2d8a-d8ac-41fc-969f-0ba4102682ac",
    "created": "2026-05-01T10:00:00+02:00",
    "leads": [
      {
        "uid": "0SVOUNZGlkzJ5fRrBxUdiQ_0000",
        "status": "PROCESSED",
        "processing_result": "NOT_CONVERTED_TO_PROSPECT"
      }
    ]
  }
}

Body schema

Field	Type	Description
lead_enrichment	object	One lead enrichment batch
└─ 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

404

The batch UUID was not found for the authenticated account. A 404 can mean the enrichment batch is unavailable to this account, or that the request URL points to the wrong resource.

{
  "title": "Not Found",
  "status": 404,
  "details": "Lead enrichment with uuid 088e2d8a-d8ac-41fc-969f-0ba4102682ac was not found",
  "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 resource was not found
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

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