# Queue lead enrichments

> **Documentation index**
> Browse the [Woodpecker developer documentation index](https://developers.woodpecker.co/llms.txt) to discover related API references, guides, webhooks, MCP tools, and CLI documentation.

> 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](https://developers.woodpecker.co/docs/lead-finder/lead-search-and-enrichment/list-lead-enrichments.md) or [get lead enrichment](https://developers.woodpecker.co/docs/lead-finder/lead-search-and-enrichment/get-lead-enrichment.md).

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](https://developers.woodpecker.co/docs/lead-finder/lead-search-and-enrichment/list-lead-enrichments.md) or [get lead enrichment](https://developers.woodpecker.co/docs/lead-finder/lead-search-and-enrichment/get-lead-enrichment.md).

## Request

:::info Credit usage
This request can use account credits. Credits are applied only when enrichment finds data. Enriching a lead and finding an email costs 1.5 credits.
:::

### Endpoint

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

### Headers

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

For details on how to authenticate your requests, please see the [authentication guide](https://developers.woodpecker.co/docs/getting-started/authentication.md).

### Body

You can enrich up to 50 leads in one request. 

Pass the lead context returned by [lead search](https://developers.woodpecker.co/docs/lead-finder/lead-search-and-enrichment/post-search-leads.md) 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.

```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": [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](https://developers.woodpecker.co/docs/lead-finder/lead-search-and-enrichment/post-search-leads.md) 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

  
  ```bash
  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": []
    }'
  ```
  
  
  ```python
  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()
  ```
  
  
  ```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) {
      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();
      }
    }
  }
  ```
  
  
  ```js
  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
  <?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](https://developers.woodpecker.co/docs/lead-finder/lead-search-and-enrichment/get-lead-enrichment.md) to check the status. Use [list lead enrichments](https://developers.woodpecker.co/docs/lead-finder/lead-search-and-enrichment/list-lead-enrichments.md) to browse recent batches. 

  ```json
  {
    "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.

  ```json
  {
    "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](https://developers.woodpecker.co/docs/getting-started/authentication.md).

  ```json
  {
    "title": "Unauthorized",
    "status": 401,
    "detail": "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 |
  | `detail` | 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.

  ```json
  {
    "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.

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