Overview
Perform advanced search and filtering across all prospects in your team. This powerful endpoint allows you to find prospects based on multiple criteria including text search, campaign association, qualification status, location, and engagement metrics.
Query Parameters
Text search across prospect names and headlines
Filter prospects by specific campaign ID
Filter by qualification status: pending, qualified, disqualified
Filter by conversation status (numeric status code)
Filter prospects by city location
Filter prospects by country location
Filter prospects who have responded to outreach
Filter prospects with paused conversations
Maximum number of results to return (max: 100)
Number of results to skip for pagination
Use Cases
- Lead Management: Find specific prospects across campaigns
- Performance Analysis: Identify high-performing prospect segments
- Follow-up Management: Find prospects needing attention
- Geographic Targeting: Analyze prospects by location
- Qualification Review: Review prospects by qualification status
Response Structure
{
"prospects": [
{
"id": "prospect_123",
"name": "John Smith",
"headline": "VP of Sales at TechCorp",
"url": "https://linkedin.com/in/johnsmith",
"location": {
"city": "San Francisco",
"country": "United States"
},
"status": 3,
"qualification": "qualified",
"hasResponded": true,
"isPaused": false,
"lastActivity": "2024-01-20T10:30:00Z",
"campaign": {
"id": "campaign_456",
"name": "Enterprise Outreach Q4"
},
"stats": {
"messages": 5,
"responses": 2,
"lastResponse": "2024-01-19T14:20:00Z"
}
}
],
"pagination": {
"total": 1250,
"limit": 50,
"offset": 0,
"hasMore": true
},
"filters": {
"applied": {
"qualification": "qualified",
"hasResponded": true
},
"available": {
"qualifications": ["pending", "qualified", "disqualified"],
"cities": ["San Francisco", "New York", "London"],
"countries": ["United States", "United Kingdom", "Canada"]
}
}
}
Search Examples
Basic Text Search
curl -X GET "https://api.kakiyo.com/v1/prospects/search?query=VP%20Sales" \
-H "Authorization: Bearer YOUR_API_KEY"
Campaign-Specific Search
curl -X GET "https://api.kakiyo.com/v1/prospects/search?campaignId=campaign_123&qualification=qualified" \
-H "Authorization: Bearer YOUR_API_KEY"
Location-Based Search
curl -X GET "https://api.kakiyo.com/v1/prospects/search?city=San%20Francisco&hasResponded=true" \
-H "Authorization: Bearer YOUR_API_KEY"
Advanced Multi-Filter Search
curl -X GET "https://api.kakiyo.com/v1/prospects/search?qualification=pending&status=2&country=United%20States&limit=25" \
-H "Authorization: Bearer YOUR_API_KEY"
JavaScript Examples
// Basic search
const searchProspects = async (query) => {
const response = await fetch(`https://api.kakiyo.com/v1/prospects/search?query=${encodeURIComponent(query)}`, {
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
});
return await response.json();
};
// Advanced filtering
const findQualifiedProspects = async (campaignId) => {
const params = new URLSearchParams({
campaignId: campaignId,
qualification: 'qualified',
hasResponded: 'true',
limit: '100'
});
const response = await fetch(`https://api.kakiyo.com/v1/prospects/search?${params}`, {
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
});
return await response.json();
};
// Pagination example
const getAllProspects = async (filters = {}) => {
let allProspects = [];
let offset = 0;
const limit = 100;
while (true) {
const params = new URLSearchParams({
...filters,
limit: limit.toString(),
offset: offset.toString()
});
const response = await fetch(`https://api.kakiyo.com/v1/prospects/search?${params}`, {
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
});
const data = await response.json();
allProspects.push(...data.prospects);
if (!data.pagination.hasMore) break;
offset += limit;
}
return allProspects;
};
Python Examples
import requests
from urllib.parse import urlencode
def search_prospects(query=None, **filters):
"""Search prospects with optional filters"""
params = {}
if query:
params['query'] = query
params.update(filters)
response = requests.get(
'https://api.kakiyo.com/v1/prospects/search',
params=params,
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
)
return response.json()
# Usage examples
qualified_prospects = search_prospects(
qualification='qualified',
hasResponded=True,
limit=50
)
sf_prospects = search_prospects(
city='San Francisco',
status=2
)
campaign_prospects = search_prospects(
campaignId='campaign_123',
query='VP Sales'
)
Status Codes Reference
Common conversation status codes:
0: Not contacted1: Initial message sent2: Follow-up sent3: Prospect responded4: Conversation ongoing5: Qualified6: Closed/Won7: Closed/Lost
Best Practices
- Efficient Pagination: Use appropriate limit values (25-100)
- Specific Filters: Combine multiple filters for precise results
- Text Search Optimization: Use relevant keywords for better matches
- Regular Cleanup: Use search to identify prospects needing attention
- Performance Monitoring: Track search patterns for optimization
Common Use Cases
Find Unresponsive Prospects
const unresponsiveProspects = await fetch(
'https://api.kakiyo.com/v1/prospects/search?hasResponded=false&status=2',
{ headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
Geographic Analysis
const regionalProspects = await fetch(
'https://api.kakiyo.com/v1/prospects/search?country=United%20States&qualification=qualified',
{ headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const campaignResults = await fetch(
'https://api.kakiyo.com/v1/prospects/search?campaignId=campaign_123&hasResponded=true',
{ headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Text search across prospect names and headlines
Filter by specific campaign ID
Filter by qualification status
Available options:
pending,
qualified,
disqualified
Filter prospects who have responded
Maximum number of results
Required range: 1 <= x <= 100
Number of results to skip
Required range: x >= 0
