LeadGenius Pro Agent API

This skill provides a comprehensive interface for interacting with the LeadGenius Pro Agent API.

Core Workflows

1. Lead Management

• •Bulk List (EnrichLeads): Use GET /enrich-leads/list for high-volume data extraction from the enriched leads table (requires Amplify API key).
• •Bulk List (SourceLeads): Use GET /source-leads/list for raw source data extraction (requires Amplify API key).
• •Update Status: Use PUT /leads/{id}/status to track progress (New -> Qualified -> Contacted).
• •Batch Operations: Create or delete multiple leads simultaneously with POST /leads/batch or DELETE /leads/batch.

2. Campaign Operations

• •Overview: List all active ABM campaigns with GET /campaigns.
• •Performance: Monitor ROI with GET /campaigns/{id}/metrics.
• •Creation: Launch new initiatives with POST /campaigns.

3. Targeted ABM

• •Account Lists: Manage high-value targets with GET /target-accounts.
• •Scoring: Update account intent and fit scores with PUT /target-accounts/{id}/score.

4. Outreach & Engagement

• •Sequences: List communication sequences with GET /sequences.
• •Enrollment: Enroll leads into a specific sequence with POST /sequences/{id}/enroll.

5. Automation & Workflows

• •Custom Workflows: Manage automated processes and agent handoffs with GET /workflows.
• •Status Jobs: Monitor long-running processes (like enrichment or exports) with GET /enrichment/status/{jobId}.

6. Analytics & Insights

• •Pipeline Health: Total visibility into conversion rates and pipeline velocity with GET /analytics/pipeline.

7. Maintenance & System Health

• •Bug Reporting: Use POST /maintenance/bugs to report issues discovered by agents.
• •Enhancement Requests: Use POST /maintenance/enhancements to suggest features.

8. Master Administration

• •Global Visibility: List all companies and users across the platform (Admin only).
• •API Key Management: Generate and rotate API keys for agent access.

Technical Reference

Base URLs

The API uses separate root paths depending on the operation scope. Standard agent interaction occurs via the Agent Scope, while high-volume extraction uses the System Scope.

1. •Agent API Operations: /api/agent (e.g., https://last.leadgenius.app/api/agent/leads). Requires X-API-Key (lgp_...).
2. •Bulk Data Extraction (System Scope): /api (e.g., https://last.leadgenius.app/api/enrich-leads/list). Requires x-api-key (Amplify API key).
3. •Admin Scope: /api/admin (e.g., .../api/admin/companies).

Unified CLI (lgp.py)

The primary way to interact with LeadGenius is via the lgp CLI tool.

1. Setup & Auth

Authentication is a two-step process:

1. •Login: Authenticate with your email and password to get a temporary session (JWTokens are stored).
2. •Generate Key: Create a long-lived API Key (lgp_...) for your scripts/agent using the session.

# 1. Login to get session (email/password)
python3 scripts/lgp.py auth --email your@email.com

# 2. Generate an API Key (this will be automatically saved)
python3 scripts/lgp.py generate-key --name "Production Agent"

Once generated, the key is saved to ~/.leadgenius_auth.json and will be automatically used by the CLI. You can also explicitly set it via LGP_API_KEY environment variable.

2. Manage Leads

# List leads
python3 scripts/lgp.py leads list

# Find specific leads
python3 scripts/lgp.py leads find --full-name "Hugo Sanchez"

# Enrich specific leads
python3 scripts/lgp.py leads enrich --ids lead_1 lead_2

3. Manage Campaigns

# List active campaigns
python3 scripts/lgp.py campaigns list

# Create a new campaign
python3 scripts/lgp.py campaigns create --name "Q3 Expansion"

4. Insights & Analytics

# Show pipeline health for a specific period
python3 scripts/lgp.py pipeline --start 2026-01-01 --end 2026-02-08

5. Maintenance & Support

# List and report bugs
python3 scripts/lgp.py maintenance bugs list
python3 scripts/lgp.py maintenance bugs report --desc "Enrichment fails on LinkedIn URLs"

# List and request enhancements
python3 scripts/lgp.py maintenance enhancements list
python3 scripts/lgp.py maintenance enhancements request --desc "Add support for Google Maps leads"

6. Global Administration (Admin Only)

# View system-wide data
python3 scripts/lgp.py admin companies
python3 scripts/lgp.py admin users

Reference Material

• •API Reference: See api_reference.md for detailed endpoint descriptions.
• •OpenAPI Spec: See openapi.json for machine-readable schemas.

Helper Scripts

• •scripts/lgp.py: Unified CLI for all common operations.
• •scripts/api_call.py: Low-level utility for custom raw API requests.
• •scripts/auth.py: Standalone auth utility.

Common Payloads

Create Campaign

{
  "name": "Q1 ABM Tech Giants",
  "description": "Targeting top 50 tech firms for SaaS expansion",
  "campaignType": "abm",
  "status": "active"
}

Enrich Leads

{
  "leadIds": ["lead_123", "lead_456"],
  "enrichmentType": "technographic",
  "priority": "high"
}

Data Architecture & Logic

1. Multi-Tenant Isolation

All data is strictly isolated by company_id. Even though agents use their own API keys, the system enforces that they only see leads associated with their assigned company_id.

2. Search Logic (LeadService)

The standard lead listing (GET /leads) uses a dual-query strategy to ensure no leads are missed:

• •By Company: Queries the company_id-GSI to find all company-level leads.
• •By Owner: Queries the owner-GSI to find leads specifically created by/assigned to the agent.
• •Merging: Results are deduplicated and merged to provide a unified view.

3. Bulk Data Access

High-volume extraction (GET /enrich-leads/list) bypasses standard CRM logic in favor of raw GSI performance, requiring an explicit companyId parameter and matching Amplify API key.

4. Guardrails & Limits

• •Rate Limits:
  • •Minute: 60 requests.
  • •Hour: 1,000 requests.
  • •Day: 10,000 requests.
• •Batching:
  • •Lead Creation: Max 100 leads per request.
  • •Enrichment Trigger: Max 500 leads per request.
• •Pagination:
  • •Standard API: Default 20, Max 100 per page.
  • •Bulk API: Default 1,000, Max 5,000 per page.
• •Search Depth: LeadService scans up to 1,000 records per GSI before in-memory merging.