> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kakiyo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Prospects

> Advanced search and filtering across all prospects

## 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

<ParamField query="query" type="string">
  Text search across prospect names and headlines
</ParamField>

<ParamField query="campaignId" type="string">
  Filter prospects by specific campaign ID
</ParamField>

<ParamField query="qualification" type="string">
  Filter by qualification status: `pending`, `qualified`, `disqualified`
</ParamField>

<ParamField query="status" type="number">
  Filter by conversation status (numeric status code)
</ParamField>

<ParamField query="city" type="string">
  Filter prospects by city location
</ParamField>

<ParamField query="country" type="string">
  Filter prospects by country location
</ParamField>

<ParamField query="hasResponded" type="boolean">
  Filter prospects who have responded to outreach
</ParamField>

<ParamField query="isPaused" type="boolean">
  Filter prospects with paused conversations
</ParamField>

<ParamField query="limit" type="number" default="50">
  Maximum number of results to return (max: 100)
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of results to skip for pagination
</ParamField>

## 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

```json theme={null}
{
  "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

```bash theme={null}
curl -X GET "https://api.kakiyo.com/v1/prospects/search?query=VP%20Sales" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Campaign-Specific Search

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

### Location-Based Search

```bash theme={null}
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

```bash theme={null}
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

```javascript theme={null}
// 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

```python theme={null}
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

```javascript theme={null}
const unresponsiveProspects = await fetch(
  'https://api.kakiyo.com/v1/prospects/search?hasResponded=false&status=2',
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
```

### Geographic Analysis

```javascript theme={null}
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

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


## OpenAPI

````yaml GET /prospects/search
openapi: 3.1.0
info:
  title: Kakiyo API
  description: API for automating LinkedIn outreach campaigns with AI-powered conversations
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.kakiyo.com/v1
security:
  - bearerAuth: []
paths:
  /prospects/search:
    get:
      summary: Search Prospects
      description: Advanced search and filtering across all prospects
      operationId: searchProspects
      parameters:
        - name: query
          in: query
          description: Text search across prospect names and headlines
          schema:
            type: string
        - name: campaignId
          in: query
          description: Filter by specific campaign ID
          schema:
            type: string
        - name: qualification
          in: query
          description: Filter by qualification status
          schema:
            type: string
            enum:
              - pending
              - qualified
              - disqualified
        - name: status
          in: query
          description: Filter by conversation status (numeric status code)
          schema:
            type: integer
        - name: city
          in: query
          description: Filter prospects by city location
          schema:
            type: string
        - name: country
          in: query
          description: Filter prospects by country location
          schema:
            type: string
        - name: hasResponded
          in: query
          description: Filter prospects who have responded
          schema:
            type: boolean
        - name: isPaused
          in: query
          description: Filter prospects with paused conversations
          schema:
            type: boolean
        - name: limit
          in: query
          description: Maximum number of results
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: offset
          in: query
          description: Number of results to skip
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  prospects:
                    type: array
                    items:
                      $ref: '#/components/schemas/Prospect'
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                        example: 1250
                      limit:
                        type: integer
                        example: 50
                      offset:
                        type: integer
                        example: 0
                      hasMore:
                        type: boolean
                        example: true
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Prospect:
      type: object
      properties:
        id:
          type: string
          example: chat_12345abcde
        status:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
          example: 2
        qualification:
          type: string
          enum:
            - unqualified
            - needVerification
            - inProgress
            - qualified
          example: inProgress
        paused:
          type: boolean
          example: false
        lastMessage:
          type: string
          format: date-time
          example: '2023-06-15T15:30:00Z'
        prospect:
          type: object
          properties:
            id:
              type: string
              example: prospect_12345abcde
            name:
              type: string
              example: John Smith
            url:
              type: string
              example: https://linkedin.com/in/johnsmith
            headline:
              type: string
              example: VP of Sales at Acme Inc
            currentCompanyName:
              type:
                - string
                - 'null'
              example: Acme Inc
            currentJobTitle:
              type:
                - string
                - 'null'
              example: VP of Sales
            currentCompanyWebsite:
              type:
                - string
                - 'null'
              example: https://www.acme.com
            currentCompanyLinkedInUrl:
              type:
                - string
                - 'null'
              example: https://www.linkedin.com/company/acme
    Error:
      type: object
      properties:
        error:
          type: string
          example: validation_error
        message:
          type: string
          example: The request parameters failed validation
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                example: name
              message:
                type: string
                example: The name field is required
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````