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

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