Skip to main content
GET
/
prospects
/
search
Search Prospects
curl --request GET \
  --url https://api.kakiyo.com/v1/prospects/search \
  --header 'Authorization: Bearer <token>'
{
  "prospects": [
    {
      "id": "chat_12345abcde",
      "status": 2,
      "qualification": "inProgress",
      "paused": false,
      "lastMessage": "2023-06-15T15:30:00Z",
      "prospect": {
        "id": "prospect_12345abcde",
        "name": "John Smith",
        "url": "https://linkedin.com/in/johnsmith",
        "headline": "VP of Sales at Acme Inc"
      }
    }
  ],
  "pagination": {
    "total": 1250,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

​
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

​
query
string
Text search across prospect names and headlines
​
campaignId
string
Filter prospects by specific campaign ID
​
qualification
string
Filter by qualification status: pending, qualified, disqualified
​
status
number
Filter by conversation status (numeric status code)
​
city
string
Filter prospects by city location
​
country
string
Filter prospects by country location
​
hasResponded
boolean
Filter prospects who have responded to outreach
​
isPaused
boolean
Filter prospects with paused conversations
​
limit
number
default:"50"
Maximum number of results to return (max: 100)
​
offset
number
default:"0"
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"

curl -X GET "https://api.kakiyo.com/v1/prospects/search?campaignId=campaign_123&qualification=qualified" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X GET "https://api.kakiyo.com/v1/prospects/search?city=San%20Francisco&hasResponded=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

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 contacted
  • 1: Initial message sent
  • 2: Follow-up sent
  • 3: Prospect responded
  • 4: Conversation ongoing
  • 5: Qualified
  • 6: Closed/Won
  • 7: Closed/Lost

​
Best Practices

  1. Efficient Pagination: Use appropriate limit values (25-100)
  2. Specific Filters: Combine multiple filters for precise results
  3. Text Search Optimization: Use relevant keywords for better matches
  4. Regular Cleanup: Use search to identify prospects needing attention
  5. 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' } }
);

​
Campaign Performance Review

const campaignResults = await fetch(
  'https://api.kakiyo.com/v1/prospects/search?campaignId=campaign_123&hasResponded=true',
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
query
string

Text search across prospect names and headlines

​
campaignId
string

Filter by specific campaign ID

​
qualification
enum<string>

Filter by qualification status

Available options:
pending,
qualified,
disqualified
​
hasResponded
boolean

Filter prospects who have responded

​
limit
integer
default:50

Maximum number of results

Required range: 1 <= x <= 100
​
offset
integer
default:0

Number of results to skip

Required range: x >= 0

Response

Search results

​
prospects
object[]
​
pagination
object