INinstantly
AILeadFinderAgent

Create an AI Lead Finder Agent

Changed on

Create an AI Lead Finder Agent that keeps a campaign topped up with fresh leads. The agent immediately runs its first check after creation.

Requires one of the following scopes: ai_agents:create, ai_agents:all, all:create, all:all

post/api/v2/ai-agents/lead-finder

Request

  • Base URL
    https://api.instantly.ai
  • URL
    https://api.instantly.ai/api/v2/ai-agents/lead-finder
  • Auth
    HTTP bearer

Request body

namestring required

Name of the agent

campaign_idstring uuid required

Campaign the agent keeps topped up. A campaign can have at most one active agent.

min_active_leadsnumber required

Threshold below which the agent tops up the campaign

on_exhaustion'pause' | 'fallback' | 'broaden' required

What the agent does when the search runs out of new leads

show_one_lead_per_companyboolean

Deliver at most one lead per company in each top-up. Defaults to true.

source'agents_page' | 'campaign_banner' | 'supersearch' | 'announcement' | 'campaign_setup'

Entry point the agent was created from, for adoption attribution.

ai_enrichmentobject

AI enrichment columns filled on every top-up, keyed by output column name. Leads are held back until they are filled.

ai_enrichment_workflowstring

Workflow template the enrichment chain was loaded from — a built-in key or custom:<id>. Display-only.

Example request

{
  "name": "Lead Finder - Outbound US",
  "campaign_id": "01a19e6f-7f20-73d7-9ec4-6aaec47512ac",
  "min_active_leads": 50,
  "on_exhaustion": "broaden",
  "show_one_lead_per_company": true,
  "source": "campaign_banner",
  "ai_enrichment_workflow": "custom:0198c2a4-3f1e-7000-8000-000000000000"
}

Response

The created AI Lead Finder Agent

idstring uuid required

Unique identifier for the AI agent

organization_idstring uuid required

Organization ID

namestring required

Name of the AI Agent

type6 nullable

Type of the AI Agent

timestamp_createdstring required

Timestamp when the AI agent was created

timestamp_updatedstring required

Timestamp when the AI agent was updated

status-1 | 0 | 1 required

Status of the AI Agent

is_auto_createdboolean nullable

Whether the AI agent was auto-created

created_bystring uuid nullable

User ID who created the AI agent

descriptionstring nullable

Description of the AI agent

Example response

{
  "id": "01a19e6f-5074-7a90-9d10-535a367c0bf1",
  "organization_id": "01a19e6f-5074-7a90-9d10-535b0a6d005c",
  "name": "Test AI Agent",
  "payload": {
    "campaign_id": "01a19e6f-5074-7a90-9d10-5358888d7c91",
    "campaign_name": "Outbound US",
    "min_active_leads": 50,
    "on_exhaustion": "pause",
    "ai_enrichment_workflow": "custom:0198c2a4-3f1e-7000-8000-000000000000"
  },
  "type": 6,
  "timestamp_created": "2026-11-02T22:44:17.652Z",
  "timestamp_updated": "2026-11-02T22:44:17.652Z",
  "status": 1,
  "created_by": "01a19e6f-5074-7a90-9d10-535cef352927",
  "description": "Optional agent description"
}

Changes