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

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

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

:::info Credit usage
This request can use account credits. Credits are applied only when enrichment finds data. Successfully enriching an existing prospect costs 1.5 credits.
:::

### Endpoint

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

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.

```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"
    }
  ]
}
```

#### 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

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

  

  Batch accepted for processing. Use [list prospect enrichments](https://developers.woodpecker.co/docs/lead-finder/prospect-enrichment/list-prospect-enrichments.md) to check recent statuses. Use [get prospect enrichment](https://developers.woodpecker.co/docs/lead-finder/prospect-enrichment/get-prospect-enrichment.md) when you already know the returned `uuid`.

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

  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 |