Skip to content
LDLeadDrive
Sign inStart free

API reference

The LeadDrive API

Create prospecting runs and read scored leads from your own systems. Available on the Agency plan.

Authentication

Create a key in Workspace settings. The key is shown once and stored only as a hash, so it cannot be recovered later — if you lose it, revoke it and create another. Send it as a bearer token.

curl https://leaddrive.uk/api/v1/runs \
  -H "Authorization: Bearer ld_live_your_key_here"

A key is scoped to one workspace and can never read another. Revoking a key, or the workspace dropping below the Agency plan, disables it immediately.

POST
/api/v1/runs
Start a prospecting run. Consumes credits from the workspace exactly as the dashboard does, and respects the same concurrency limit — the API cannot be used to exceed your plan.
curl -X POST https://leaddrive.uk/api/v1/runs \
  -H "Authorization: Bearer ld_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "roofers",
    "location": "Manchester",
    "filters": { "minReviews": 5, "requireWebsite": true }
  }'

402 when the workspace is out of credits, 409 when too many runs are already in progress.

GET
/api/v1/runs
List runs, newest first. Paginate with ?limit= (max 100) and ?cursor= from the previous response.
{
  "data": [
    {
      "id": "clx...",
      "keyword": "roofers",
      "location": "Manchester",
      "status": "completed",
      "leadCount": 42,
      "creditsConsumed": 8,
      "createdAt": "2026-08-29T09:00:00.000Z",
      "completedAt": "2026-08-29T09:02:11.000Z"
    }
  ],
  "nextCursor": "clx..."
}
GET
/api/v1/runs/{id}/leads
Read the scored leads for a run. Filter with ?minScore=, paginate with ?limit= (max 200) and ?cursor=.
{
  "run": { "id": "clx...", "keyword": "roofers", "location": "Manchester", "status": "completed" },
  "data": [
    {
      "id": "clx...",
      "businessName": "Example Roofing",
      "website": "https://example.com",
      "email": "hello@example.com",
      "phone": "0161 000 0000",
      "score": 84,
      "tier": "A",
      "opportunityTags": ["No HTTPS", "Low reviews"],
      "insight": "No HTTPS and no mobile viewport tag detected on the homepage."
    }
  ],
  "nextCursor": null
}

Rate limits and errors

  • 30 run creations and 120 reads per minute, per key.
  • 401 means the key is wrong, revoked, or the plan no longer includes API access.
  • 429 includes a Retry-After header in seconds.
  • 503 means we could not verify your key right now — an outage on our side, not a problem with your credentials. Retry.

Webhooks

Rather than polling, add a Webhook push automation in Workspace settings and LeadDrive will POST completed runs to your endpoint. The endpoint must be public HTTPS.

{
  "event": "run.completed",
  "runId": "clx...",
  "workspaceId": "clx...",
  "leadCount": 42,
  "leads": [ { "id": "clx...", "companyName": "…", "score": 84 } ]
}
Create an API keyView plans