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

# Search Prospects

> Search for new prospects using advanced filters and criteria

# Search Prospects

Discover new prospects using advanced search filters including company size, industry, location, job titles, and more. Our proprietary database contains millions of verified business contacts.

<Note>
  Requires the `prospecting:search` permission. Each search result consumes
  credits from your account.
</Note>

## Request

<ParamField header="x-api-key" type="string" required>
  Your API key with `prospecting:search` permission
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

### Body Parameters

<ParamField body="filters" type="object" required>
  Search filters to apply when finding prospects

  <Expandable title="Search Filters">
    <ParamField body="company" type="object">
      Company-based filters

      <Expandable title="Company Filters">
        <ParamField body="name" type="string">
          Company name or keyword
        </ParamField>

        <ParamField body="industry" type="array">
          Array of industry strings
        </ParamField>

        <ParamField body="size" type="array">
          Company size ranges (e.g., \["10-50", "100-500"])
        </ParamField>

        <ParamField body="location" type="array">
          Geographic locations
        </ParamField>

        <ParamField body="revenue" type="object">
          Revenue range filter
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="person" type="object">
      Person-based filters

      <Expandable title="Person Filters">
        <ParamField body="title" type="array">
          Job titles or keywords
        </ParamField>

        <ParamField body="seniority" type="array">
          Seniority levels
        </ParamField>

        <ParamField body="department" type="array">
          Departments or functions
        </ParamField>

        <ParamField body="location" type="array">
          Geographic locations
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="technology" type="object">
      Technology stack filters

      <Expandable title="Technology Filters">
        <ParamField body="using" type="array">
          Technologies currently in use
        </ParamField>

        <ParamField body="notUsing" type="array">
          Technologies to exclude
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="limit" type="number" default="25">
  Maximum number of results to return (1-100)
</ParamField>

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

## Examples

### Search by Company and Role

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.buena.ai/api/v2/prospecting/search" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "filters": {
        "company": {
          "industry": ["Technology", "Software"],
          "size": ["100-500", "500-1000"],
          "location": ["San Francisco", "New York", "Austin"]
        },
        "person": {
          "title": ["CTO", "VP Engineering", "Head of Engineering"],
          "seniority": ["Director", "VP", "C-Level"]
        }
      },
      "limit": 50
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.buena.ai/api/v2/prospecting/search", {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      filters: {
        company: {
          industry: ["Technology", "Software"],
          size: ["100-500", "500-1000"],
          location: ["San Francisco", "New York", "Austin"],
        },
        person: {
          title: ["CTO", "VP Engineering", "Head of Engineering"],
          seniority: ["Director", "VP", "C-Level"],
        },
      },
      limit: 50,
    }),
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.buena.ai/api/v2/prospecting/search',
      headers={
          'x-api-key': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'filters': {
              'company': {
                  'industry': ['Technology', 'Software'],
                  'size': ['100-500', '500-1000'],
                  'location': ['San Francisco', 'New York', 'Austin']
              },
              'person': {
                  'title': ['CTO', 'VP Engineering', 'Head of Engineering'],
                  'seniority': ['Director', 'VP', 'C-Level']
              }
          },
          'limit': 50
      }
  )

  print(response.json())
  ```
</CodeGroup>

### Technology-Based Search

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.buena.ai/api/v2/prospecting/search" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "filters": {
        "technology": {
          "using": ["Salesforce", "HubSpot", "Marketo"],
          "notUsing": ["Pipedrive"]
        },
        "company": {
          "size": ["500+"],
          "industry": ["SaaS", "Enterprise Software"]
        },
        "person": {
          "department": ["Sales", "Marketing", "Revenue Operations"]
        }
      },
      "limit": 25
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.buena.ai/api/v2/prospecting/search", {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      filters: {
        technology: {
          using: ["Salesforce", "HubSpot", "Marketo"],
          notUsing: ["Pipedrive"],
        },
        company: {
          size: ["500+"],
          industry: ["SaaS", "Enterprise Software"],
        },
        person: {
          department: ["Sales", "Marketing", "Revenue Operations"],
        },
      },
      limit: 25,
    }),
  });

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean">
  Always `true` for successful requests
</ResponseField>

<ResponseField name="data" type="object">
  Search results and metadata

  <Expandable title="Data Object">
    <ResponseField name="prospects" type="array">
      Array of prospect objects matching the search criteria
    </ResponseField>

    <ResponseField name="total" type="number">
      Total number of prospects matching the filters
    </ResponseField>

    <ResponseField name="creditsUsed" type="number">
      Number of search credits consumed
    </ResponseField>

    <ResponseField name="remainingCredits" type="number">
      Remaining search credits in your account
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "prospects": [
        {
          "id": "prospect_123",
          "firstName": "Sarah",
          "lastName": "Johnson",
          "email": "sarah@techcorp.com",
          "linkedinUrl": "https://linkedin.com/in/sarahjohnson",
          "title": "CTO",
          "company": "Tech Corp",
          "industry": "Technology",
          "location": "San Francisco, CA",
          "companySize": "100-500",
          "technologies": ["React", "AWS", "Kubernetes"],
          "confidence": 0.95
        }
      ],
      "total": 1247,
      "creditsUsed": 25,
      "remainingCredits": 975
    }
  }
  ```
</ResponseExample>

## Advanced Use Cases

### 1. ICP-Based Prospecting

```javascript theme={null}
async function findIdealCustomerProfiles() {
  const icpFilters = {
    company: {
      industry: ["Enterprise Software", "SaaS", "Technology"],
      size: ["500-1000", "1000+"],
      revenue: {
        min: 50000000, // $50M+
        max: null,
      },
    },
    person: {
      title: [
        "Chief Technology Officer",
        "VP Engineering",
        "Head of Engineering",
      ],
      seniority: ["VP", "C-Level"],
      department: ["Engineering", "Technology"],
    },
    technology: {
      using: ["AWS", "Kubernetes", "React"],
      notUsing: ["Legacy systems", "Monolith"],
    },
  };

  const response = await fetch(
    "https://api.buena.ai/api/v2/prospecting/search",
    {
      method: "POST",
      headers: {
        "x-api-key": process.env.BUENA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        filters: icpFilters,
        limit: 100,
      }),
    }
  );

  const data = await response.json();

  // Score prospects based on additional criteria
  const scoredProspects = data.data.prospects
    .map((prospect) => ({
      ...prospect,
      score: calculateProspectScore(prospect),
    }))
    .sort((a, b) => b.score - a.score);

  return scoredProspects.slice(0, 25); // Top 25 prospects
}

function calculateProspectScore(prospect) {
  let score = 0;

  // Company size scoring
  if (prospect.companySize === "1000+") score += 10;
  else if (prospect.companySize === "500-1000") score += 8;

  // Title scoring
  if (prospect.title.includes("CTO")) score += 10;
  else if (prospect.title.includes("VP")) score += 8;

  // Technology fit
  const targetTech = ["React", "AWS", "Kubernetes", "GraphQL"];
  const matches = prospect.technologies.filter((tech) =>
    targetTech.some((target) => tech.includes(target))
  ).length;
  score += matches * 2;

  return score;
}
```

### 2. Competitive Intelligence

```python theme={null}
import requests

def find_competitor_customers(competitor_technologies):
    """Find prospects using competitor technologies"""

    filters = {
        'technology': {
            'using': competitor_technologies,
            'notUsing': ['Your Product']  # Exclude existing customers
        },
        'company': {
            'size': ['100+'],  # Focus on larger companies
            'industry': ['Technology', 'SaaS', 'Enterprise Software']
        },
        'person': {
            'seniority': ['Director', 'VP', 'C-Level'],
            'department': ['Engineering', 'Technology', 'Product']
        }
    }

    all_prospects = []
    offset = 0
    limit = 100

    while True:
        response = requests.post(
            'https://api.buena.ai/api/v2/prospecting/search',
            headers={
                'x-api-key': os.getenv('BUENA_API_KEY'),
                'Content-Type': 'application/json'
            },
            json={
                'filters': filters,
                'limit': limit,
                'offset': offset
            }
        )

        data = response.json()
        prospects = data['data']['prospects']

        if not prospects:
            break

        all_prospects.extend(prospects)
        offset += limit

        # Rate limiting
        time.sleep(1)

        # Stop if we've gotten enough or hit credit limits
        if len(all_prospects) >= 500:
            break

    return analyze_competitor_usage(all_prospects)

def analyze_competitor_usage(prospects):
    """Analyze technology usage patterns"""
    tech_analysis = {}

    for prospect in prospects:
        for tech in prospect.get('technologies', []):
            if tech not in tech_analysis:
                tech_analysis[tech] = {
                    'count': 0,
                    'companies': set(),
                    'titles': set()
                }

            tech_analysis[tech]['count'] += 1
            tech_analysis[tech]['companies'].add(prospect['company'])
            tech_analysis[tech]['titles'].add(prospect['title'])

    # Sort by popularity
    sorted_tech = sorted(
        tech_analysis.items(),
        key=lambda x: x[1]['count'],
        reverse=True
    )

    return sorted_tech[:20]  # Top 20 technologies

# Usage
competitor_tech = ['Competitor A', 'Competitor B', 'Legacy Solution']
insights = find_competitor_customers(competitor_tech)
```

### 3. Territory Planning

```javascript theme={null}
async function planSalesTerritory(territory) {
  const filters = {
    company: {
      location: territory.locations,
      size: territory.companySizes,
      industry: territory.industries,
    },
    person: {
      title: territory.targetTitles,
      seniority: ["Director", "VP", "C-Level"],
    },
  };

  let allProspects = [];
  let offset = 0;
  const limit = 100;

  while (true) {
    const response = await fetch(
      "https://api.buena.ai/api/v2/prospecting/search",
      {
        method: "POST",
        headers: {
          "x-api-key": process.env.BUENA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          filters,
          limit,
          offset,
        }),
      }
    );

    const data = await response.json();
    const prospects = data.data.prospects;

    if (prospects.length === 0) break;

    allProspects.push(...prospects);
    offset += limit;

    if (offset >= data.data.total) break;
  }

  // Organize by location for territory assignment
  const territoryMap = {};

  allProspects.forEach((prospect) => {
    const location = prospect.location;
    if (!territoryMap[location]) {
      territoryMap[location] = [];
    }
    territoryMap[location].push(prospect);
  });

  // Calculate territory value
  Object.keys(territoryMap).forEach((location) => {
    const prospects = territoryMap[location];
    const totalValue = prospects.reduce((sum, prospect) => {
      return sum + estimateProspectValue(prospect);
    }, 0);

    territoryMap[location] = {
      prospects,
      count: prospects.length,
      estimatedValue: totalValue,
      averageValue: totalValue / prospects.length,
    };
  });

  return territoryMap;
}

function estimateProspectValue(prospect) {
  // Simple scoring based on company size and title
  let value = 0;

  switch (prospect.companySize) {
    case "1000+":
      value += 10000;
      break;
    case "500-1000":
      value += 7500;
      break;
    case "100-500":
      value += 5000;
      break;
    default:
      value += 2500;
  }

  if (prospect.title.includes("CTO")) value *= 1.5;
  else if (prospect.title.includes("VP")) value *= 1.3;
  else if (prospect.title.includes("Director")) value *= 1.1;

  return value;
}

// Example usage
const westCoastTerritory = {
  locations: ["San Francisco", "Los Angeles", "Seattle", "Portland"],
  companySizes: ["100-500", "500-1000", "1000+"],
  industries: ["Technology", "SaaS"],
  targetTitles: ["CTO", "VP Engineering", "Director of Engineering"],
};

const territoryData = await planSalesTerritory(westCoastTerritory);
console.log("Territory Analysis:", territoryData);
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Lead" icon="plus" href="/api-reference/leads/create">
    Convert prospects to leads
  </Card>

  <Card title="Enrich Prospects" icon="sparkles" href="/api-reference/enrich/leads">
    Get additional data on prospects
  </Card>

  <Card title="Schedule LinkedIn" icon="linkedin" href="/api-reference/linkedin/schedule-action">
    Reach out to prospects
  </Card>

  <Card title="Prospecting Guide" icon="book" href="/guides/prospecting">
    Learn advanced prospecting strategies
  </Card>
</CardGroup>