API quickstart

From zero to your first search in three steps. Base URL: https://<your-leadintel-host>/v1.

1. Create an API key in the dashboard

Sign in, open Settings → API keys, choose a name and the scopes your integration needs (for this guide search:create and search:read), and copy the key. It is shown once; keep it in a secret store. See scopes.

export LEADINTEL_API_KEY=li_live_<key>

2. Call the API with curl

curl -X POST https://<your-leadintel-host>/v1/searches \
  -H "Authorization: Bearer $LEADINTEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: dentists-cairo-1" \
  -d '{"query":"dental clinics","location":{"country":"EG","cities":["Cairo"]},"max_results":100,"depth":"basic"}'

# 202 with a search id; poll it, then read results
curl https://<your-leadintel-host>/v1/searches/<search_id> -H "Authorization: Bearer $LEADINTEL_API_KEY"
curl "https://<your-leadintel-host>/v1/searches/<search_id>/results?limit=50" -H "Authorization: Bearer $LEADINTEL_API_KEY"

Every creating POST takes an Idempotency-Key; repeating it within 24 hours replays the original response. Lists use cursor pagination: { data, next_cursor, has_more }. Failures are problem+json; see errors.

3. Use an SDK

The SDKs add retries, automatic idempotency keys, pagination, typed errors and webhook verification.

Python (PyPI: leadintel)

pip install leadintel

from leadintel_sdk import LeadIntel, ProblemError

with LeadIntel("li_live_...") as client:
    try:
        org = client.lookup(domain="example.com")
    except ProblemError as e:
        print(e.status, e.code, e.request_id)

TypeScript (npm: @leadintel/sdk)

npm install @leadintel/sdk

import { LeadIntel } from "@leadintel/sdk";

const client = new LeadIntel({ apiKey: process.env.LEADINTEL_API_KEY! });
for await (const lead of client.paginate(client.leads)) console.log(lead);

Next: the API reference or the machine-readable openapi.json.