LeadsAgent/ Documentation
Connectors
OverviewQuickstartAuthenticationAPI referenceMCPConnect ChatGPTConnect ClaudeCredits & limitsErrors & retriesConnect OpenCodeConnect Claude CodeConnect CodexConnect CursorConnect VS CodeConnect AntigravityConnect n8nAPI, MCP & plugins

Quickstart

Give LeadsAgent a job in plain language, follow it, and read the leads.

Set up with your AI assistant

Paste the prompt into Claude Code. It includes setup steps and a read-only connection check.

1. Check account access

In Connectors → API keys, create a key with Read and start tasks. Save it in your local environment as LEADSAGENT_API_KEY. It is shown once.

Bash · account check
export LEADSAGENT_API_BASE="https://leadsagent.io/api/v1"

curl --fail-with-body "$LEADSAGENT_API_BASE/account" \
  -H "X-API-Key: $LEADSAGENT_API_KEY"

For a local backend, set LEADSAGENT_API_BASE to http://127.0.0.1:8001/api/v1. Use the same requests below. Port 3000 serves the local website.

The curl examples use Bash. In PowerShell, use curl.exe and $env:LEADSAGENT_API_KEY. For a JSON body, save it in a file and use --data-binary @request.json.

2. Start a task

Describe the whole job. max_leads caps the credits the task can spend, follow-ups included.

cURL
curl --fail-with-body "$LEADSAGENT_API_BASE/tasks" \
  -H "X-API-Key: $LEADSAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Find 50 dentists in Austin, TX without a website and get their emails",
       "max_leads": 50, "idempotency_key": "austin-dentists-001"}'

3. Follow it

Save data.id as TASK_ID. Poll GET /tasks/{id} every 10–20 seconds. When the status is needs_input, answer the question; when it is completed, read the reply and the leads.

Bash: check task
curl --fail-with-body "$LEADSAGENT_API_BASE/tasks/$TASK_ID" -H "X-API-Key: $LEADSAGENT_API_KEY"
Example task response
{
  "data": {
    "id": "TASK_ID",
    "status": "needs_input",
    "prompt": "Find 50 dentists in Austin…",
    "source": "API key · CRM sync",
    "max_leads": 50,
    "steps": [
      {
        "name": "search_businesses",
        "label": "Searching Google Maps",
        "status": "done",
        "summary": null,
        "rows": 50
      }
    ],
    "question": {
      "questions": [
        {
          "question": "Verify the emails too?",
          "options": [
            "Yes",
            "No"
          ]
        }
      ]
    },
    "reply": null,
    "lead_count": 50,
    "results_ready": true
  }
}
Answer the question
curl --fail-with-body "$LEADSAGENT_API_BASE/tasks/$TASK_ID/messages" \
  -H "X-API-Key: $LEADSAGENT_API_KEY" -H "Content-Type: application/json" \
  -d '{"answers": ["Yes"]}'

4. Read the leads

cURL
curl "$LEADSAGENT_API_BASE/tasks/$TASK_ID/results?has_email=true&limit=100" \
  -H "X-API-Key: $LEADSAGENT_API_KEY"

# Everything, as a file
curl -o leads.csv "$LEADSAGENT_API_BASE/tasks/$TASK_ID/export?format=csv" \
  -H "X-API-Key: $LEADSAGENT_API_KEY"

Each task is also a chat in your LeadsAgent sidebar, labeled with the key or app that started it.

Structured search

Use POST /find when the job fits categories, locations and conditions. It runs without the LeadsAgent agent.

Bash · structured search
curl --fail-with-body "$LEADSAGENT_API_BASE/find" \
  -H "X-API-Key: $LEADSAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"categories":["dentist"],"locations":["Austin, TX"],"max_research_leads":20,"wait_seconds":0,"idempotency_key":"austin-find-001"}'

202 means accepted. Check data.status until work stops. Use poll_after_seconds when present.

Agent documentation indexOpenAPI JSONMarkdown quickstart