Lead Generation - IntentGPT API

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

Parameter	Type	Required	Description
objective	string	Yes*	Lead generation objective (e.g., “find marketing leaders”)
website/domain	string	No	Company website or domain to filter by
topic/t	string	No	Topic filter for lead generation
keyword/k	string	No	Keyword filter for more specific targeting
limit	integer	No	Maximum 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

Parameter	Type	Description
user_id	string	Filter lists by user ID
list_id	string	Get 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

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

List Management

Organize by Campaign: Create separate lists for different campaigns or time periods
Use Descriptive Names: Include timeframe, target persona, and purpose in list names
Regular Updates: Update lists regularly to maintain data freshness
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"

API Documentation

Core Endpoints

Documentation Index

​Overview

​Generate Leads

​GET /leadgen

​Parameters

​Example: Generate Marketing Leaders

​Response

​Lead Lists Management

​Get Lead Lists

​GET /leadgen/lists

​Parameters

​Example: Get All Lists

​Example: Get Specific List

​Create Lead List

​POST /leadgen/lists

​Request Body

​Example Request

​Response

​Update Lead List

​PUT /leadgen/lists/

​Parameters

​Request Body

​Example Request

​Delete Lead List

​DELETE /leadgen/lists/

​Parameters

​Example Request

​Response

​Error Responses

​Partial Success (207)

​Not Found (404)

​Bad Request (400)

​Best Practices

​Lead Generation Tips

​List Management

​Use Cases

​Sales Prospecting

​Event Marketing

​Account-Based Marketing

Overview

Generate Leads

GET /leadgen

Parameters

Example: Generate Marketing Leaders

Response

Lead Lists Management

Get Lead Lists

GET /leadgen/lists

Parameters

Example: Get All Lists

Example: Get Specific List

Create Lead List

POST /leadgen/lists

Request Body

Example Request

Response

Update Lead List

PUT /leadgen/lists/

Parameters

Request Body

Example Request

Delete Lead List

DELETE /leadgen/lists/

Parameters

Example Request

Response

Error Responses

Partial Success (207)

Not Found (404)

Bad Request (400)

Best Practices

Lead Generation Tips

List Management

Use Cases

Sales Prospecting

Event Marketing

Account-Based Marketing