Skip to main content
POST
/
api
/
v2
/
prospecting
/
search
Search Prospects
curl --request POST \
  --url https://api.buena.ai/api/v2/prospecting/search \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "filters": {
    "company": {
      "name": "<string>",
      "industry": [
        {}
      ],
      "size": [
        {}
      ],
      "location": [
        {}
      ],
      "revenue": {}
    },
    "person": {
      "title": [
        {}
      ],
      "seniority": [
        {}
      ],
      "department": [
        {}
      ],
      "location": [
        {}
      ]
    },
    "technology": {
      "using": [
        {}
      ],
      "notUsing": [
        {}
      ]
    }
  },
  "limit": 123,
  "offset": 123
}
'
{
  "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
  }
}

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

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.
Requires the prospecting:search permission. Each search result consumes credits from your account.

Request

x-api-key
string
required
Your API key with prospecting:search permission
Content-Type
string
required
Must be application/json

Body Parameters

filters
object
required
Search filters to apply when finding prospects
limit
number
default:"25"
Maximum number of results to return (1-100)
offset
number
default:"0"
Number of results to skip for pagination

Examples

Search by Company and Role

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

Response

success
boolean
Always true for successful requests
data
object
Search results and metadata
{
  "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
  }
}

Advanced Use Cases

1. ICP-Based Prospecting

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

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

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

Create Lead

Convert prospects to leads

Enrich Prospects

Get additional data on prospects

Schedule LinkedIn

Reach out to prospects

Prospecting Guide

Learn advanced prospecting strategies