Queue prospect enrichments

Queue one or more prospects for enrichment. This endpoint starts an asynchronous prospect enrichment batch and returns a batch uuid that you can later check with list prospect enrichments or get prospect enrichment.

Use this flow to enrich prospects that already exist in your account's main prospect database. The endpoint matches submitted records by email and updates matching prospects after enrichment; it does not create new prospects or update records that are not already in that database.

Request

Credit usage

This call can use account credits. Credits are applied only when enrichment finds data. Successfully enriching an existing prospect costs 1.5 credits.

Endpoint

POST https://api.woodpecker.co/rest/v2/lead_finder/prospects/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

Provide wide prospect context whenever possible. Enrichment usually needs additional signals, such as linkedin_url or first_name and last_name together with company_website. Each submitted email should belong to an existing prospect in your account's main prospect database.

{
  "prospects": [
    {
      "email": "erlich@bachmanity.com",
      "first_name": "Erlich",
      "last_name": "Bachman",
      "linkedin_url": "https://www.linkedin.com/in/erlich-bachman-404xyz",
      "company_name": "Bachmanity",
      "company_website": "https://bachmanity.com"
    },
    {
      "email": "jared@piedpiper.com",
      "first_name": "Jared",
      "last_name": "Dunn",
      "company_name": "Pied Piper",
      "company_website": "https://piedpiper.com"
    }
  ]
}

Body schema

Field	Type	Required	Description
prospects	array[object]	Yes	Non-empty list of prospects to enrich
└─ email	string	Yes	Email address of an existing prospect in the account's main prospect database. The endpoint uses this value as the enrichment identity
└─ first_name	string	No	Prospect's first name
└─ last_name	string	No	Prospect's last name
└─ linkedin_url	string	No	Prospect's LinkedIn profile URL
└─ company_name	string	No	Prospect's company name
└─ company_website	string	No	Prospect's company website

Request samples

Queue prospects for enrichment

cURL

curl --request POST \
  --url "https://api.woodpecker.co/rest/v2/lead_finder/prospects/enrichments" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "prospects": [
      {
        "email": "erlich@bachmanity.com",
        "first_name": "Erlich",
        "last_name": "Bachman",
        "linkedin_url": "https://www.linkedin.com/in/erlich-bachman-404xyz",
        "company_name": "Bachmanity",
        "company_website": "https://bachmanity.com"
      },
      {
        "email": "jared@piedpiper.com",
        "first_name": "Jared",
        "last_name": "Dunn",
        "company_name": "Pied Piper",
        "company_website": "https://piedpiper.com"
      }
    ]
  }'

Python

import requests

def queue_prospect_enrichments():
  url = "https://api.woodpecker.co/rest/v2/lead_finder/prospects/enrichments"
  headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json"
  }
  payload = {
    "prospects": [
      {
        "email": "erlich@bachmanity.com",
        "first_name": "Erlich",
        "last_name": "Bachman",
        "linkedin_url": "https://www.linkedin.com/in/erlich-bachman-404xyz",
        "company_name": "Bachmanity",
        "company_website": "https://bachmanity.com"
      },
      {
        "email": "jared@piedpiper.com",
        "first_name": "Jared",
        "last_name": "Dunn",
        "company_name": "Pied Piper",
        "company_website": "https://piedpiper.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__":
  queue_prospect_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) {
    queueProspectEnrichments();
  }

  public static void queueProspectEnrichments() {
    try {
      String url = "https://api.woodpecker.co/rest/v2/lead_finder/prospects/enrichments";
      String jsonData = """
        {
          "prospects": [
            {
              "email": "erlich@bachmanity.com",
              "first_name": "Erlich",
              "last_name": "Bachman",
              "linkedin_url": "https://www.linkedin.com/in/erlich-bachman-404xyz",
              "company_name": "Bachmanity",
              "company_website": "https://bachmanity.com"
            },
            {
              "email": "jared@piedpiper.com",
              "first_name": "Jared",
              "last_name": "Dunn",
              "company_name": "Pied Piper",
              "company_website": "https://piedpiper.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 queueProspectEnrichments() {
  const url = "https://api.woodpecker.co/rest/v2/lead_finder/prospects/enrichments";
  const headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json"
  };
  const data = {
    prospects: [
      {
        email: "erlich@bachmanity.com",
        first_name: "Erlich",
        last_name: "Bachman",
        linkedin_url: "https://www.linkedin.com/in/erlich-bachman-404xyz",
        company_name: "Bachmanity",
        company_website: "https://bachmanity.com"
      },
      {
        email: "jared@piedpiper.com",
        first_name: "Jared",
        last_name: "Dunn",
        company_name: "Pied Piper",
        company_website: "https://piedpiper.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);
  }
}

queueProspectEnrichments();

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', [
    'json' => [
      'prospects' => [
        [
          'email' => 'erlich@bachmanity.com',
          'first_name' => 'Erlich',
          'last_name' => 'Bachman',
          'linkedin_url' => 'https://www.linkedin.com/in/erlich-bachman-404xyz',
          'company_name' => 'Bachmanity',
          'company_website' => 'https://bachmanity.com',
        ],
        [
          'email' => 'jared@piedpiper.com',
          'first_name' => 'Jared',
          'last_name' => 'Dunn',
          'company_name' => 'Pied Piper',
          'company_website' => 'https://piedpiper.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

Batch accepted for processing. Use list prospect enrichments to check recent statuses. Use get prospect enrichment when you already know the returned uuid.

{
  "uuid": "e9e6abc4-799e-4c24-b412-7917b1db919d",
  "prospects_count": 2,
  "total_prospects_count": 2,
  "status": "ENQUEUED"
}

Body schema

Field	Type	Description
uuid	string/null	Enrichment batch identifier. null when nothing was queued
prospects_count	integer	Number of prospects queued in this response
total_prospects_count	integer	Number of prospects submitted in the request
status	string	Queue status. ENQUEUED - at least one prospect was accepted and all eligible prospects were queued PARTIALLY_ENQUEUED - some prospects were queued. Usually because available credits can cover fewer prospects than requested NOT_ENQUEUED - none of the submitted prospects 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

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