Queue lead enrichments

Queue one or more Lead Finder search results for enrichment. This endpoint starts an asynchronous lead enrichment batch and returns a batch uuid that you can later check with list lead enrichments or get lead enrichment.

Request

Credit usage

This call can use account credits. Credits are applied only when enrichment finds data. Enriching a lead and finding an email costs 1.5 credits.

Endpoint

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

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

You can enrich up to 50 leads in one request.

Pass the lead context returned by lead search whenever possible, not only uid, because enrichment usually needs signals such as linkedin_url or full_name with company_website. We recommend passing through the whole lead payload with all values that are available. If lead search does not return a value, you can omit that optional field or pass the returned null or empty array value.

{
  "leads": [
    {
      "uid": "0SVOUN5zYlkzJ5fMrBxUdiQ_0000",
      "full_name": "Erlich Bachman",
      "first_name": "Erlich",
      "last_name": "Bachman",
      "gender": "Male",
      "linkedin_url": "linkedin.com/in/erlich-bachman-404xyz",
      "company_name": "Bachmanity",
      "company_website": "bachmanity.com",
      "industry": "Software as a Service",
      "job_title": "Ceo",
      "job_title_role": "Operations",
      "job_title_levels": [
        "Cxo"
      ],
      "location_name": "Palo Alto, California, United States",
      "city": "Palo Alto",
      "state": "California",
      "country": "United States"
    }
  ],
  "target_campaign_ids": [123,654]
}

Body schema

Field	Type	Required	Description
`leads`	array[object]	Yes	Non-empty list of leads to enrich
└─ `uid`	string	Yes	Lead identifier returned by the lead search response
└─ `full_name`	string/null	No	Full lead name
└─ `first_name`	string/null	No	Lead first name
└─ `last_name`	string/null	No	Lead last name
└─ `gender`	string/null	No	Lead gender when available
└─ `linkedin_url`	string/null	No	Lead LinkedIn profile URL
└─ `company_name`	string/null	No	Company name
└─ `company_website`	string/null	No	Company website
└─ `industry`	string/null	No	Industry name
└─ `job_title`	string/null	No	Current job title
└─ `job_title_role`	string/null	No	Job title role
└─ `job_title_levels`	array[string]	No	Job title levels
└─ `location_name`	string/null	No	Full human-readable location
└─ `city`	string/null	No	City
└─ `state`	string/null	No	State or region
└─ `country`	string/null	No	Country
`target_campaign_ids`	array[integer]	No	IDs of campaigns where enriched leads should be added as prospects. Use an empty array to add them only to the global prospect list

Request samples

Queue leads for enrichment

cURL
Python
Java
Node.js
PHP

curl --request POST \
  --url "https://api.woodpecker.co/rest/v2/lead_finder/leads/enrichments" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "leads": [
      {
        "uid": "0SVOUN5zYlkzJ5fMrBxUdiQ_0000",
        "full_name": "Erlich Bachman",
        "first_name": "Erlich",
        "last_name": "Bachman",
        "gender": "Male",
        "linkedin_url": "linkedin.com/in/erlich-bachman-404xyz",
        "company_name": "Bachmanity",
        "company_website": "bachmanity.com",
        "industry": "Software as a Service",
        "job_title": "Ceo",
        "job_title_role": "Operations",
        "job_title_levels": ["Cxo"],
        "location_name": "Palo Alto, California, United States",
        "city": "Palo Alto",
        "state": "California",
        "country": "United States"
      }
    ],
    "target_campaign_ids": []
  }'

import requests

def queue_lead_enrichments():
  url = "https://api.woodpecker.co/rest/v2/lead_finder/leads/enrichments"
  headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json"
  }
  payload = {
    "leads": [
      {
        "uid": "0SVOUN5zYlkzJ5fMrBxUdiQ_0000",
        "full_name": "Erlich Bachman",
        "first_name": "Erlich",
        "last_name": "Bachman",
        "gender": "Male",
        "linkedin_url": "linkedin.com/in/erlich-bachman-404xyz",
        "company_name": "Bachmanity",
        "company_website": "bachmanity.com",
        "industry": "Software as a Service",
        "job_title": "Ceo",
        "job_title_role": "Operations",
        "job_title_levels": ["Cxo"],
        "location_name": "Palo Alto, California, United States",
        "city": "Palo Alto",
        "state": "California",
        "country": "United States"
      }
    ],
    "target_campaign_ids": []
  }

  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__":
  queue_lead_enrichments()

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

  public static void queueLeadEnrichments() {
    try {
      String url = "https://api.woodpecker.co/rest/v2/lead_finder/leads/enrichments";
      String jsonData = """
        {
          "leads": [
            {
              "uid": "0SVOUN5zYlkzJ5fMrBxUdiQ_0000",
              "full_name": "Erlich Bachman",
              "first_name": "Erlich",
              "last_name": "Bachman",
              "gender": "Male",
              "linkedin_url": "linkedin.com/in/erlich-bachman-404xyz",
              "company_name": "Bachmanity",
              "company_website": "bachmanity.com",
              "industry": "Software as a Service",
              "job_title": "Ceo",
              "job_title_role": "Operations",
              "job_title_levels": ["Cxo"],
              "location_name": "Palo Alto, California, United States",
              "city": "Palo Alto",
              "state": "California",
              "country": "United States"
            }
          ],
          "target_campaign_ids": []
        }
        """;

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

const axios = require("axios");

async function queueLeadEnrichments() {
  const url = "https://api.woodpecker.co/rest/v2/lead_finder/leads/enrichments";
  const headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json"
  };
  const data = {
    leads: [
      {
        uid: "0SVOUN5zYlkzJ5fMrBxUdiQ_0000",
        full_name: "Erlich Bachman",
        first_name: "Erlich",
        last_name: "Bachman",
        gender: "Male",
        linkedin_url: "linkedin.com/in/erlich-bachman-404xyz",
        company_name: "Bachmanity",
        company_website: "bachmanity.com",
        industry: "Software as a Service",
        job_title: "Ceo",
        job_title_role: "Operations",
        job_title_levels: ["Cxo"],
        location_name: "Palo Alto, California, United States",
        city: "Palo Alto",
        state: "California",
        country: "United States"
      }
    ],
    target_campaign_ids: []
  };

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

queueLeadEnrichments();

<?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/leads/enrichments', [
    'json' => [
      'leads' => [
        [
          'uid' => '0SVOUN5zYlkzJ5fMrBxUdiQ_0000',
          'full_name' => 'Erlich Bachman',
          'first_name' => 'Erlich',
          'last_name' => 'Bachman',
          'gender' => 'Male',
          'linkedin_url' => 'linkedin.com/in/erlich-bachman-404xyz',
          'company_name' => 'Bachmanity',
          'company_website' => 'bachmanity.com',
          'industry' => 'Software as a Service',
          'job_title' => 'Ceo',
          'job_title_role' => 'Operations',
          'job_title_levels' => ['Cxo'],
          'location_name' => 'Palo Alto, California, United States',
          'city' => 'Palo Alto',
          'state' => 'California',
          'country' => 'United States',
        ],
      ],
      'target_campaign_ids' => [],
    ],
  ]);

  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

Batch accepted for processing. Use get lead enrichment to check the status. Use list lead enrichments to browse recent batches.

{
  "uuid": "4480b1e0-70d2-4b4a-be49-6bf9637bf0bf",
  "leads_count": 5,
  "status": "ENQUEUED"
}

Body schema

Field	Type	Description
`uuid`	string/null	Enrichment batch identifier used for polling
`leads_count`	integer	Number of leads queued in this response
`status`	string	Queue status. `ENQUEUED` - at least one lead was accepted and all eligible leads were queued `PARTIALLY_ENQUEUED` - some leads were queued. Usually because available credits can cover fewer leads than requested `NOT_ENQUEUED` - none of the submitted leads were queued because they are already pending `CREDITS_EXHAUSTED` - Not enough credits. An account admin can manage credits in the billing section of the app

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

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

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

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

Request​

Endpoint​

Headers​

Body​

Body schema​

Request samples​

Queue leads for enrichment​

Response​

Response examples​

Body schema​

Body schema​

Body schema​

Body schema​

Body schema​

Request

Endpoint

Headers

Body

Body schema

Request samples

Queue leads for enrichment

Response

Response examples

Body schema

Body schema

Body schema

Body schema

Body schema