LeadGenius Pro API — Skill Reference

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

Base URL: https://last.leadgenius.app/api
Full Reference: See docs/API_REFERENCE.md

Authentication

LeadGenius supports three authentication methods, tried in order by getAuthContext:

Getting a JWT Token

# Option 1: Use the test/auth script
python3 scripts/auth.py --email your@email.com

# Option 2: Direct API call
curl -X POST https://last.leadgenius.app/api/auth \
  -H "Content-Type: application/json" \
  -d '{"username": "your@email.com", "password": "YourPassword"}'

Response:

{
  "success": true,
  "tokens": {
    "accessToken": "eyJra...",
    "idToken": "eyJra...",
    "refreshToken": "eyJj...",
    "expiresIn": 3600
  }
}

Use tokens.accessToken as the Bearer token for all subsequent API calls. Tokens expire after 1 hour.

Using Bearer JWT in API Calls

# All API calls use the accessToken in the Authorization header
curl -H "Authorization: Bearer <accessToken>" \
     -H "Content-Type: application/json" \
     https://last.leadgenius.app/api/clients

The getAuthContext middleware (src/utils/apiAuthHelper.ts) decodes the JWT, extracts the sub claim as the owner, and resolves the company_id for multi-tenant isolation — all automatically.

Auth Credentials Storage

Tokens are saved to ~/.leadgenius_auth.json by the auth scripts:

{
  "token": "<accessToken>",
  "id_token": "<idToken>",
  "refresh_token": "<refreshToken>",
  "email": "your@email.com",
  "base_url": "https://last.leadgenius.app"
}

Core Workflows (E2E Tested ✅)

The following operations have been validated end-to-end with the test suite.

1. Client Management ✅

All client operations are scoped by company_id (resolved from JWT).

Create Client Payload

{
  "clientName": "Acme Corp",
  "companyURL": "https://acme.com",
  "description": "Enterprise client for B2B leads"
}

Response (201):

{
  "success": true,
  "client": {
    "id": "edd5c738-...",
    "client_id": "5b9cb5db-...",
    "clientName": "Acme Corp",
    "companyURL": "https://acme.com",
    "description": "Enterprise client for B2B leads",
    "owner": "4428a4f8-...",
    "company_id": "company-177..."
  }
}

Note: id is the DynamoDB record ID. client_id is the unique business identifier used in lead operations.

Update Client Payload

{
  "id": "<dynamodb-id>",
  "clientName": "Updated Name",
  "description": "Updated description"
}

2. Lead Management ✅

Leads are stored as EnrichLeads in DynamoDB and are scoped by client_id and company_id.

Create Single Lead Payload

{
  "client_id": "5b9cb5db-...",
  "firstName": "John",
  "lastName": "Smith",
  "email": "john.smith@example.com",
  "companyName": "Acme Corp",
  "companyDomain": "acme.com",
  "title": "VP Engineering",
  "linkedinUrl": "https://linkedin.com/in/johnsmith"
}

Create Batch Leads Payload

{
  "leads": [
    {
      "client_id": "5b9cb5db-...",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane@example.com",
      "companyName": "BatchCorp",
      "title": "CTO"
    },
    {
      "client_id": "5b9cb5db-...",
      "firstName": "Bob",
      "lastName": "Wilson",
      "email": "bob@example.com",
      "companyName": "BatchCorp",
      "title": "VP Sales"
    }
  ]
}

Batch Response (201):

{
  "success": true,
  "created": 2,
  "skipped": []
}

Update Single Lead Payload

{
  "id": "<lead-dynamodb-id>",
  "title": "Senior VP Engineering",
  "notes": "Updated via API"
}

Batch Update Payload

{
  "leads": [
    { "id": "<id-1>", "notes": "Updated lead 1" },
    { "id": "<id-2>", "notes": "Updated lead 2" }
  ]
}

Batch Delete Payload (body)

{
  "ids": ["<id-1>", "<id-2>"]
}

List Leads Query Parameters

• client_id (required) — The client_id field from Client (not the DynamoDB id)
• limit — 1 to 1000 (default: 100)
• nextToken — Pagination token

3. Bulk Data Extraction

High-volume extraction bypasses standard auth for raw GSI performance.

Bulk List Query Parameters

• companyId (required) — Multi-tenant isolation
• clientId (optional) — Filter by client. Use ALL/DEFAULT or omit for all
• limit (optional) — Default 1000, max 5000
• nextToken (optional) — Pagination token
• fields (optional) — Comma-separated field projection (reduces payload)

4. Company Management

5. Search History

Track and manage lead search operations (e.g., Apify scraping runs).

List Query Parameters

• client_id, status (initiated/running/completed/failed), icpId, category, limit, cursor

Create Payload

{
  "searchName": "Tech Companies in SF",
  "searchDescription": "Looking for SaaS companies",
  "searchCriteria": { "industry": "Technology", "location": "San Francisco" },
  "searchFilters": { "companySize": "50-200" },
  "client_id": "client-123",
  "clientName": "Acme Corp",
  "icpId": "icp-456",
  "icpName": "Enterprise SaaS",
  "apifyActorId": "actor-789",
  "category": "prospecting",
  "tags": ["enterprise", "saas"]
}

6. Webhook Management

Create and manage inbound webhooks for third-party integrations.

Supported Platforms: heyreach, woodpecker, lemlist, generic

Create Webhook Payload

{
  "name": "My Webhook",
  "platform": "heyreach",
  "description": "Webhook for lead capture",
  "platformConfig": "{\"field_mapping\": {}}",
  "client_id": "client-123"
}

Returns: webhookUrl with embedded secret key for the external platform to call.

7. Territory Workbench

Aggregated company-level analytics for territory planning.

List Query Parameters

• client_id (required), sortBy, sortDirection, industry, minLeads, maxLeads, search, startDate, endDate

8. Settings Management ⚙️

Settings drive all Lead Processing endpoints. Configure settings first, then trigger processing.

All settings endpoints require JWT auth and are scoped by company_id.

URL Settings (Enrichment Service URLs)

Available URL/key pairs: companyUrl, emailFinder, enrichment1 through enrichment10 (each with _Apikey).

Agent Settings (EpsimoAI Agent IDs for Copyright)

Available fields: projectId, enrichment1AgentId through enrichment10AgentId.

SDR AI Settings (EpsimoAI Agent IDs for SDR AI)

Available fields: projectId, plus <fieldName>AgentId for all SDR fields.

9. Lead Processing 🚀

Settings-driven execution routes that trigger enrichment, copyright, and SDR AI processing on individual leads.

Enrichment Processing

{
  "leadId": "enrich-lead-id",
  "services": ["companyUrl", "enrichment1", "enrichment3"],
  "overwrite": false
}

Copyright Processing

{
  "leadId": "enrich-lead-id",
  "processes": [1, 3, 5],
  "overwrite": false
}

SDR AI Processing

{
  "leadId": "enrich-lead-id",
  "fields": ["message1", "aiLeadScore", "aiQualification"],
  "overwrite": false
}

Response Format (all three)

{
  "success": true,
  "runIds": ["run-abc-123", "run-def-456"],
  "batchTag": "enrich-process-1707654321-x8k2m1",
  "triggered": ["companyUrl", "enrichment1"],
  "skipped": ["enrichment3"],
  "leadId": "enrich-lead-id"
}

Processing Workflow

1. Configure (one-time per company): POST /api/settings/url, POST /api/settings/agent, POST /api/settings/sdr-ai
2. Trigger (per lead): POST /api/leads/process/enrich, .../copyright, .../sdr
3. Track: Use runIds → GET /api/trigger-task-status?runId=...

10. Background Tasks (Trigger.dev)

11. Email Services

12. Integration APIs

Data Architecture

Multi-Tenant Isolation

All data is strictly isolated. Three isolation layers are enforced:

1. Owner-based — Data filtered by authenticated user’s owner ID (JWT sub)
2. Company-based — Data filtered by user’s company_id (resolved from CompanyMember table)
3. Client-based — Data filtered by client_id

Key ID Fields

• Client id — DynamoDB record ID (used for update/delete)
• Client client_id — Business identifier (used in lead operations as client_id)
• Lead id — DynamoDB record ID (used for update/delete)
• owner — Cognito user sub (UUID), set automatically from JWT

Data Operations Auth Mode

After getAuthContext resolves the owner, all data queries use generateClient<Schema>({ authMode: 'apiKey' }) — meaning the Amplify API key handles DynamoDB access while the JWT provides identity and isolation.

Error Handling

All errors follow a consistent format:

{
  "success": false,
  "error": "Error message",
  "errorType": "authentication_error",
  "details": "Additional error details",
  "recommendation": "Suggested action"
}

Common Error Types

• Authentication — no_valid_credentials, token_expired, federated_jwt, no_valid_tokens
• Authorization — insufficient_permissions, owner_mismatch
• Validation — missing_required_field, invalid_format, invalid_value
• Resource — not_found, already_exists, conflict

Rate Limits & Pagination

Rate Limits

Pagination

• Standard API: Cursor-based (limit + nextToken)
• Bulk API: Token-based (limit default 1000, max 5000 + nextToken)

Helper Scripts

Running the E2E Test Suite

python3 scripts/test_api.py \
  --username your@email.com \
  --password YourPassword \
  --base-url https://last.leadgenius.app

Options:

• --base-url — Override base URL (default: https://last.leadgenius.app)
• --skip-cleanup — Keep test data after run

The test creates a temporary client and leads, exercises all CRUD operations, and cleans up automatically.

CLI Usage (lgp.py)

# Auth
python3 scripts/lgp.py auth --email your@email.com

# Leads
python3 scripts/lgp.py leads list
python3 scripts/lgp.py leads find --full-name "Hugo Sanchez"
python3 scripts/lgp.py leads enrich --ids lead_1 lead_2

# Campaigns
python3 scripts/lgp.py campaigns list
python3 scripts/lgp.py campaigns create --name "Q3 Expansion"

# Pipeline analytics
python3 scripts/lgp.py pipeline --start 2026-01-01 --end 2026-02-08

# Maintenance
python3 scripts/lgp.py maintenance bugs list
python3 scripts/lgp.py maintenance bugs report --desc "Enrichment fails on LinkedIn URLs"
python3 scripts/lgp.py maintenance enhancements list
python3 scripts/lgp.py maintenance enhancements request --desc "Add support for Google Maps leads"

# API Key generation
python3 scripts/lgp.py generate-key --name "Production Agent" --desc "Key for main auto-agent"

# Admin (admin only)
python3 scripts/lgp.py admin companies
python3 scripts/lgp.py admin users

Quick Start

# 1. Authenticate and get JWT
python3 scripts/auth.py --email your@email.com

# 2. Run the full E2E test suite
python3 scripts/test_api.py --username your@email.com --password YourPassword

# 3. Or make individual API calls
python3 scripts/api_call.py GET /clients
python3 scripts/api_call.py GET /leads?client_id=your-client-id
python3 scripts/api_call.py POST /leads --data '{"client_id": "...", "firstName": "Test", "lastName": "User"}'

Reference Material

• API Reference: See docs/API_REFERENCE.md for detailed endpoint descriptions, payloads, and response schemas
• Auth Helper: See src/utils/apiAuthHelper.ts for the 3-layer auth implementation
• OpenAPI Spec: See references/openapi.json for machine-readable schemas