Lead-search runs

A lead search finds people by criteria, such as job title, location, company, industry, headcount, seniority and keywords, with no target person known in advance. It can deliver thousands of results, so it runs in the background: you start a run, then poll it.

1. Start a run

curl https://app.loice.ai/api/v1/lead-search \
  -H "Authorization: Bearer $LOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "filters": {
      "jobTitle": ["Head of Sales"],
      "location": ["Germany"],
      "headcount": ["51-200"]
    },
    "count": 500
  }'

The answer comes back at once with the run (status: "queued") and your balance after the worst case has been reserved. If the balance cannot cover the worst case, the run is refused uncharged with reason: "insufficient-credits". One run can be active per workspace at a time. Starting another answers 409 run_already_active.

2. Poll it

curl https://app.loice.ai/api/v1/lead-search/runs/$RUN_ID \
  -H "Authorization: Bearer $LOICE_API_KEY"

Poll every few seconds while status is queued, processing or cancelling. A terminal status (completed, cancelled or failed) carries the final deliveredCount and creditsCharged. Results arrive in pages of 25 and stay readable after the run finishes. Polling is free. Results are directory-style: name, title, company, location and profile URL, never contact data. To get a verified email for a result, pass its linkedinUrl to POST /api/v1/find with "mode": "linkedin".

3. Load more

To continue a finished run, start a new run with continueFromRunId set to its id. Leads that were already delivered are never delivered or billed again.

Cancel

curl -X POST https://app.loice.ai/api/v1/lead-search/runs/$RUN_ID/cancel \
  -H "Authorization: Bearer $LOICE_API_KEY"

A queued run ends cancelled at once and charges nothing.
A processing run answers cancelling and stops at its next page. Only the leads already delivered are charged.
Cancelling again answers the same; a finished run answers already-terminal.

Cancelling is free. For how a run is billed, see Billing and points.

Get started

Using the API

1. Start a run

2. Poll it

3. Load more

Cancel

​1. Start a run

​2. Poll it

​3. Load more

​Cancel

1. Start a run

2. Poll it

3. Load more

Cancel