Skip to main content

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