LeadGenius Pro — CLI & Automation API Skill

This skill teaches AI agents how to operate the LeadGenius Pro Automation API and the lgp CLI tool. It covers the full lifecycle of B2B lead management — from ICP (Ideal Customer Profile) definition and automated lead generation through enrichment, scoring, qualification, and email delivery via the FSD (Full-Stack Demand) pipeline.

Documentation-only package. The lgp CLI script (lgp.py) is part of the LeadGenius Pro application repository and is not included in this skill package. Obtain the CLI from your LeadGenius Pro deployment.

Base URL

https://api.leadgenius.app

All API endpoints live under /api/automation/.

Authentication

Every request must include an API key in the X-API-Key header:

X-API-Key: lgp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Keys are prefixed with lgp_ and tied to a specific company.
• The key determines company_id, owner identity, and rate limits.
• Keys are created via POST /api/automation/users/provision — the plain-text key is returned only once at creation time.
• Test your key with GET /api/automation/auth/test.

Required Environment Variables

Rate Limits

Prerequisites Checklist

Before running enrichment, copyright, scoring, or FSD pipelines, the following configuration records must exist. Create them via the Tables API (POST /api/automation/tables/{tableName}).

UrlSettings (required for enrichment)

AgentSettings (required for copyright / AI content generation)

SdrAiSettings (required for SDR AI scoring)

ICP with Apify Config (required for lead generation)

Client (required for data isolation)

EmailPlatformSettings (required for email delivery)

Quick-Reference: Endpoint Map

Quick-Reference: CLI Map

Maintenance CLI (Standalone Node.js Scripts)

Standalone scripts for managing maintenance items (bugs, enhancements). These use raw GraphQL over HTTPS with API key auth from amplify_outputs.json — they do NOT go through the Automation API or lgp CLI.

Create a maintenance item

node scripts/create-maintenance-item.js --type=BUG --description="Login fails on mobile"
node scripts/create-maintenance-item.js --type=ENHANCEMENT --description="Add bulk export feature"

List maintenance items

node scripts/list-maintenance-items.js
node scripts/list-maintenance-items.js --type=BUG
node scripts/list-maintenance-items.js --type=BUG --status=OPEN
node scripts/list-maintenance-items.js --company-id=company-xxx

Update a maintenance item

node scripts/update-maintenance-item.js --id=\x3CUUID> --status=RESOLVED
node scripts/update-maintenance-item.js --id=\x3CUUID> --status=CLOSED --description="Fixed in v2.1"

Maintenance REST API

There is also a REST API at /api/maintenance supporting full CRUD with JWT or API key auth. See the leadgenius-api skill for details.

Documentation Site

Docsify-based docs are served at /docs (e.g., https://api.leadgenius.app/docs). Source files in /docs/, copied to public/docs-content/ at build time.

API Behavioral Notes (2026-03-27)

Important behavioral changes that affect CLI and API consumers:

Leads List Pagination (GET /api/automation/leads)

• Max page size capped at 50. The limit parameter is clamped to 50 regardless of the value passed. Callers must paginate via nextToken to retrieve all leads.
• Orphaned leads mode: Pass client_id=__orphaned__ to find leads with null/empty client_id within your company. These leads are invisible to normal GSI queries.
• Cross-tenant validation: The API now validates that the requested client_id belongs to your company before querying. Foreign client_id values return 403.

Lead Import Upsert (POST /api/automation/leads/import)

• Idempotent by email: If a lead with the same email already exists in the same client_id, the import updates the existing record instead of creating a duplicate. This makes retries after ECONNRESET safe.
• Explicit ID upsert: If the payload includes an id field that matches an existing lead, it updates instead of crashing with a DynamoDB conditional error.
• Empty strings → null: Empty string values ("") are automatically converted to null before write to prevent DynamoDB GSI ValidationException errors.
• Response always includes errors and warnings arrays (even when empty) for consistent CLI parsing.

Lead Transfer (POST /api/automation/leads/transfer)

• skipSourceValidation: true — Allows transferring from an orphaned/deleted source client that no longer has a Client record.
• fromClientId: "__orphaned__" — Transfers leads with null/empty client_id to a valid target client.

Generic Tables (POST /api/automation/tables/{tableName})

• Client table auto-generates client_id if not provided in the body, matching the behavior of POST /api/clients.
• Tables without client_id (Maintenance, Company, CompanyUser, etc.) no longer crash — the field is automatically stripped before the GraphQL mutation.
• Table-specific fields are now included in list/create responses (e.g., clientName for Client, name for ICP, type/description/status for Maintenance).

Cross-Tenant Safety

• Single lead GET (GET /api/automation/leads/{id}) flags cross-tenant client_id references with a _clientWarning field and prefixes the value with __foreign:.
• All lead PUT/DELETE operations cascade across EnrichLeads, B2BLeads, and SourceLeads tables transparently.