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",
        "currentCompanyName": "Acme Inc",
        "currentJobTitle": "VP of Sales",
        "currentCompanyWebsite": "https://www.acme.com",
        "currentCompanyLinkedInUrl": "https://www.linkedin.com/company/acme"
      }
    }
  ],
  "pagination": {
    "total": 1250,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

GET

prospects

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",
        "currentCompanyName": "Acme Inc",
        "currentJobTitle": "VP of Sales",
        "currentCompanyWebsite": "https://www.acme.com",
        "currentCompanyLinkedInUrl": "https://www.linkedin.com/company/acme"
      }
    }
  ],
  "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. Each result’s prospect object includes current company data when available: currentCompanyName, currentJobTitle, currentCompanyWebsite, and currentCompanyLinkedInUrl.

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",
      "currentCompanyName": "TechCorp",
      "currentJobTitle": "VP of Sales",
      "currentCompanyWebsite": "https://www.techcorp.com",
      "currentCompanyLinkedInUrl": "https://www.linkedin.com/company/techcorp",
      "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 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

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' } }
);

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

status

integer

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

isPaused

boolean

Filter prospects with paused conversations

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[]

Show child attributes

pagination

object

Show child attributes

Last modified on May 19, 2026

Add prospects batch (Round Robin)Get prospect details

Documentation Index

​Overview

​Query Parameters

​Use Cases

​Response Structure

​Search Examples

​Basic Text Search

​Campaign-Specific Search

​Location-Based Search

​Advanced Multi-Filter Search

​JavaScript Examples

​Python Examples

​Status Codes Reference

​Best Practices

​Common Use Cases

​Find Unresponsive Prospects

​Geographic Analysis

​Campaign Performance Review

Authorizations

Query Parameters

Response

Overview

Query Parameters

Use Cases

Response Structure

Search Examples

Basic Text Search

Campaign-Specific Search

Location-Based Search

Advanced Multi-Filter Search

JavaScript Examples

Python Examples

Status Codes Reference

Best Practices

Common Use Cases

Find Unresponsive Prospects

Geographic Analysis

Campaign Performance Review