🔍 Advanced Search Guide

📋 Overview

The Advanced Search endpoint enables sophisticated filtering and querying of compromise data across multiple dimensions. This powerful endpoint allows security teams to identify potential threats, monitor specific domains, and analyze breach patterns with granular control.

🚀 Endpoint Details

• URL: /json/v3/advanced-search
• Method: POST
• Content-Type: application/json
• Authentication: 🔐 API Key required
• Permissions: 📋 Requires advanced-search permission
• Rate Limit: ⚡ Standard API limits apply

🔑 Authentication

Include your API key in the request headers:

api-key: your_api_key_here

📝 Request Parameters

⚠️ Required Fields

At least ONE of the following filter parameters must be provided:

🔧 Optional Parameters

📊 Sort Options

• last_employee_compromised - 👥📅 Recent employee breaches
• last_user_compromised - 👤📅 Recent user breaches
• last_employee_uploaded - 👥⬆️ Recent employee data uploads
• last_user_uploaded - 👤⬆️ Recent user data uploads
• compromised_employees - 👥🔢 Employee compromise count
• compromised_users - 👤🔢 User compromise count

💡 Example Requests

🌐 Search by Domains

{
  "domains": ["example.com", "company.org"],
  "sort_by": "compromised_employees",
  "sort_direction": "desc"
}

👥 Filter by Employee Compromises

{
  "min_employees_compromised": 10,
  "max_employees_compromised": 100,
  "sort_by": "last_employee_compromised"
}

📅 Recent Breaches Filter

{
  "last_employee_compromised": "2024-01-01T00:00:00Z",
  "company_sizes": ["501-1000", "1001-5000"],
  "industries": ["Technology", "Financial Services"]
}

🌍 Geographic and Industry Filter

{
  "countries": ["United States", "Canada"],
  "industries": ["Healthcare", "Education"],
  "min_users_compromised": 5
}

📤 Response Format

✅ Success Response (200)

{
  "data": [
    {
      "domain": "example.com",
      "compromised_employees": 25,
      "compromised_users": 150,
      "last_employee_compromised": "2024-03-15T10:30:00Z",
      "last_user_compromised": "2024-03-14T14:22:00Z",
      "company_size": "501-1000",
      "industry": "Technology",
      "country": "United States"
    }
  ],
  "total": 1,
  "nextCursor": "eyJkYXRlIjoiMjAyNC0wMy0xNSIsImlkIjoiNjVmNGE..."
}

❌ Error Responses

400 - Validation Error

{
  "error": "Validation error",
  "message": "At least one filter parameter is required"
}

401 - Authentication Error

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

403 - Permission Error

{
  "error": "Forbidden", 
  "message": "Insufficient permissions"
}

📄 Pagination

• Limit: 500 results per request
• Cursor-based: Use nextCursor from response for next page
• Example:

{
  "domains": ["example.com"],
  "cursor": "eyJkYXRlIjoiMjAyNC0wMy0xNSIsImlkIjoiNjVmNGE..."
}

🎯 Best Practices

⚡ Performance Tips

• Combine filters for more targeted results
• Use pagination for large datasets
• Sort by relevant fields for your use case
• Limit domain lists to 500 or fewer

🔍 Query Strategies

• Recent threats: Use last_employee_compromised with recent dates
• High-risk domains: Filter by min_employees_compromised
• Industry analysis: Combine industries with compromise thresholds
• Geographic focus: Use countries for regional monitoring

📊 Monitoring Recommendations

• Weekly scans: Check recent compromises in your industry
• Domain monitoring: Regular checks on your domain portfolio
• Threshold alerts: Monitor domains exceeding compromise thresholds
• Trend analysis: Use date filters to identify emerging threats

🚨 Error Handling

Always handle these scenarios:

• Validation errors: Check required parameters
• Rate limiting: Implement backoff strategies
• Authentication failures: Verify API key validity
• Permission errors: Ensure proper endpoint access

📚 Additional Resources

• Company filters: Available at [https://api.hudsonrock.com/company-filters.json](https://api.hudsonrock.com/company-filters.json)
• Industries: 147 available options
• Countries: 247 available options
• Company sizes: 8 standard ranges (1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10001+)

🔄 Integration Examples

🐍 Python

import requests

response = requests.post(
    'https://api.hudsonrock.com/json/v3/advanced-search',
    headers={'api-key': 'your_key'},
    json={
        'domains': ['example.com'],
        'min_employees_compromised': 10
    }
)

🟨 JavaScript

const response = await fetch('/json/v3/advanced-search', {
    method: 'POST',
    headers: {
        'api-key': 'your_key',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        domains: ['example.com'],
        sort_by: 'compromised_employees'
    })
});

💡 Pro Tip: Start with broader filters and progressively narrow down based on results to optimize your threat hunting workflow!