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.

---

Request Body

Content-Type: application/json

{
  "items": [
    {
      "Linkedin URL": "https://linkedin.com/in/example",
      "Full name": "Jane Doe",
      "First name": "Jane",
      "Last name": "Doe",
      "Email": "[e-mail]",
      "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:

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

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

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