Overview

The Lead Generation API provides powerful tools to generate qualified leads based on specific criteria and manage lead lists. This enables you to build targeted prospect lists for your sales and marketing teams.

Generate Leads

GET /leadgen

Generate leads based on customizable criteria.

Parameters

ParameterTypeRequiredDescription
objectivestringYes*Lead generation objective (e.g., “find marketing leaders”)
website/domainstringNoCompany website or domain to filter by
topic/tstringNoTopic filter for lead generation
keyword/kstringNoKeyword filter for more specific targeting
limitintegerNoMaximum leads to return (1-1000, default: 10)
*Required when generating new leads. If no objective is provided, falls back to person intent analysis.

Example: Generate Marketing Leaders

curl -X GET "https://api.intentgpt.ai/leadgen" \
-H "X-API-Key: your_api_key" \
-G --data-urlencode "objective=find marketing leaders in SaaS companies" \
--data-urlencode "domain=saas" \
--data-urlencode "topic=marketing automation" \
--data-urlencode "limit=50"

Response

{
  "status": "success",
  "objective": "find marketing leaders in SaaS companies",
  "leads": [
    {
      "name": "John Smith",
      "title": "VP of Marketing",
      "company": "TechCorp",
      "email": "john.smith@techcorp.com",
      "linkedin": "https://linkedin.com/in/johnsmith",
      "intent_score": "HOT"
    }
  ],
  "count": 50
}

Lead Lists Management

Get Lead Lists

GET /leadgen/lists

Retrieve existing lead lists, optionally filtered by user or specific list ID.

Parameters

ParameterTypeDescription
user_idstringFilter lists by user ID
list_idstringGet a specific list by ID

Example: Get All Lists

curl -X GET "https://api.intentgpt.ai/leadgen/lists" \
-H "X-API-Key: your_api_key"

Example: Get Specific List

curl -X GET "https://api.intentgpt.ai/leadgen/lists?list_id=list_abc123" \
-H "X-API-Key: your_api_key"

Create Lead List

POST /leadgen/lists

Create a new lead list with optional automatic lead generation.

Request Body

{
  "name": "Q1 Marketing Prospects",
  "objective": "Find marketing decision makers in mid-market SaaS",
  "domain": "saas",
  "topic": "marketing automation",
  "keyword": "martech",
  "user_id": "user_123",
  "limit": 100,
  "leads": []  // Optional: pre-existing leads to add
}

Example Request

curl -X POST "https://api.intentgpt.ai/leadgen/lists" \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "name": "Marketing Leaders Q1",
  "objective": "Find CMOs and VPs of Marketing",
  "domain": "enterprise-software",
  "limit": 200
}'

Response

{
  "status": "success",
  "message": "Lead list created successfully",
  "lead_list": {
    "list_id": "list_def456",
    "name": "Marketing Leaders Q1",
    "objective": "Find CMOs and VPs of Marketing",
    "created_date": "2024-01-15T10:30:00Z",
    "lead_count": 200
  }
}

Update Lead List

PUT /leadgen/lists/

Update an existing lead list’s metadata or leads.

Parameters

  • listId (path) - ID of the lead list to update

Request Body

{
  "name": "Updated List Name",
  "objective": "Updated objective",
  "domain": "new-domain",
  "topic": "new-topic",
  "keyword": "new-keyword",
  "user_id": "user_123",
  "leads": [
    {
      "name": "Jane Doe",
      "title": "CMO",
      "company": "NewCorp"
    }
  ],
  "replace_leads": true  // If true, replaces all leads. If false, adds to existing
}

Example Request

curl -X PUT "https://api.intentgpt.ai/leadgen/lists/list_def456" \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "name": "Q1 Marketing Prospects - Updated",
  "replace_leads": false,
  "leads": [
    {
      "name": "Sarah Johnson",
      "title": "Director of Marketing",
      "company": "StartupXYZ",
      "email": "sarah@startupxyz.com"
    }
  ]
}'

Delete Lead List

DELETE /leadgen/lists/

Delete a lead list permanently.

Parameters

  • listId (path) - ID of the lead list to delete

Example Request

curl -X DELETE "https://api.intentgpt.ai/leadgen/lists/list_def456" \
-H "X-API-Key: your_api_key"

Response

{
  "status": "success",
  "message": "Lead list list_def456 deleted successfully"
}

Error Responses

Partial Success (207)

When a lead list is created but leads fail to be added:
{
  "status": "partial_success",
  "error": "Created list but failed to add leads: Invalid lead data",
  "list_id": "list_ghi789"
}

Not Found (404)

{
  "error": "Lead list not found",
  "status": "failed"
}

Bad Request (400)

{
  "error": "Missing required fields: name and objective",
  "status": "failed"
}

Best Practices

Lead Generation Tips

  1. Be Specific with Objectives: Use detailed objectives like “Find CTOs at Series B SaaS companies” rather than just “find executives”
  2. Use Multiple Filters: Combine domain, topic, and keyword filters for more targeted results
  3. Start Small: Begin with smaller limits (10-50) to test your criteria before generating larger lists
  4. Iterate on Criteria: Refine your search criteria based on the quality of initial results

List Management

  1. Organize by Campaign: Create separate lists for different campaigns or time periods
  2. Use Descriptive Names: Include timeframe, target persona, and purpose in list names
  3. Regular Updates: Update lists regularly to maintain data freshness
  4. Backup Important Lists: Export critical lists before making major updates

Use Cases

Sales Prospecting

Generate targeted prospect lists for outbound sales campaigns:
curl -X GET "https://api.intentgpt.ai/leadgen" \
-H "X-API-Key: your_api_key" \
-G --data-urlencode "objective=find sales directors at companies showing CRM intent" \
--data-urlencode "topic=CRM" \
--data-urlencode "keyword=salesforce alternative" \
--data-urlencode "limit=100"

Event Marketing

Build attendee lists for webinars or events:
curl -X POST "https://api.intentgpt.ai/leadgen/lists" \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "name": "AI Webinar Prospects",
  "objective": "Find IT leaders interested in AI and machine learning",
  "topic": "artificial intelligence",
  "limit": 500
}'

Account-Based Marketing

Create targeted lists for specific accounts:
curl -X GET "https://api.intentgpt.ai/leadgen" \
-H "X-API-Key: your_api_key" \
-G --data-urlencode "objective=find decision makers at Fortune 500 companies" \
--data-urlencode "domain=enterprise" \
--data-urlencode "topic=digital transformation" \
--data-urlencode "limit=200"