> ## Documentation Index
> Fetch the complete documentation index at: https://powerlead.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Start a new Bulk Enrichment Job

## POST `/public/v1/bulk/start`

**Start a new Bulk Enrichment Job**

This endpoint initiates a new asynchronous enrichment job based on a batch of contact data provided in the request. It validates and queues the request for processing. The job status and results can be retrieved using the returned `task_id`.

***

### Authorization

**Header:**
`X-API-Key: <your_api_key>`

API key must be generated from your account at [dashboard.powerlead.com](https://dashboard.powerlead.com).

***

### Request Body

**Content-Type:** `application/json`

```json theme={null}
{
  "items": [
    {
      "Linkedin URL": "https://linkedin.com/in/example",
      "Full name": "Jane Doe",
      "First name": "Jane",
      "Last name": "Doe",
      "Email": "jane.doe@example.com",
      "Company name": "Example Inc.",
      "Company domain": "example.com"
    }
  ],
  "return_fields": {
    "phone": true,
    "email": true
  },
  "webhook": {
    "url": "https://your.app.local/api/webhook",
    "timeout_sec": 5,
    "max_retries": 5,
    "secret": "your-secret-key",
    "headers": {
      "X-API-Key": "custom-client-header"
    }
  }
}
```

**Webhook Configuration (optional):**

You can optionally provide a `webhook` configuration block to receive automatic notifications upon job completion. If provided, Powerlead will send a `POST` request to your webhook URL containing job status and results.

**Webhook Fields:**

* `url` (required): Your webhook endpoint.
* `timeout_sec`: Max time to wait for response (default: 5, range: 1–30).
* `max_retries`: Number of retry attempts (default: 5, range: 0–10).
* `secret`: Secret used to sign the request body (HMAC-SHA256).
* `headers`: Custom headers to include (cannot override `Host`, `Content-Length`).

Please note that webhook retry attempts are executed with exponential intervals. For example, for 3 retries, the second call (first retry) will happen in 1 minute after the first attempt, the second - in 2 minutes after the first attempt, and the third - in 4 minutes after the second attempt.

**Webhook Payload Example:**

```json theme={null}
{
  "event": "csv_enrichment.completed",
  "delivery_id": "1a2b3c-...",
  "job_uuid": "b3b2d4-...",
  "status": "DONE",
  "created_at": "2025-08-12T14:26:57Z",
  "updated_at": "2025-08-12T14:31:12Z",
  "done_at": "2025-08-12T14:31:12Z",
  "results": [ ... ]
}
```

### Success Response

**HTTP 200 OK**

```json theme={null}
{
  "task_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "draft"
}
```

* `task_id`: Unique identifier of the submitted job.
* `status`: Initial job status (typically `"draft"` or `"queued"` depending on processing stage).

***

### Error Responses

**HTTP 422 Unprocessable Entity** – Invalid or incomplete input

```json theme={null}
{
  "detail": [
    {
      "loc": ["items", 0, "Email"],
      "msg": "value is not a valid email address",
      "type": "value_error"
    }
  ]
}
```

### Notes

* This API does **not** store data into internal contact databases.
* No marketing triggers are activated as part of this flow.
* Rate limits, credit usage, and concurrent job caps apply.
* Enrichment jobs are processed asynchronously — use the `/status/{task_id}` and `/result/{task_id}` endpoints to track progress and retrieve results.
* If a webhook is configured, a POST request will be sent automatically to your system once processing completes.