Search API

🎯 Quick Overview

3-Step Process:

1. Initiate - Choose algorithm and submit query → Get searchId
2. Poll - Check status every 2-3s → Wait for completed
3. Retrieve - Fetch results → Get candidate matches

Processing Time: 5-30 seconds depending on algorithm

🔍 Search Methods

Execute searches using different algorithms:

When to Use Each Algorithm

Dense Search - Semantic understanding

• "experienced frontend developer who loves React"
• Understands meaning and context
• Handles typos and synonyms

Sparse Search - Keyword matching

• "Python, FastAPI, PostgreSQL, Docker"
• Exact term matches
• Perfect for technical skills

Hybrid Search - Best quality

• "senior engineer who knows Python and can lead teams"
• Combines semantic + keywords
• Highest accuracy

Builtin Rerank - Balanced approach

• "creative developer who loves building user experiences"
• Dense search with quality boost
• Faster than hybrid

📊 Monitor & Retrieve

Check Search Status

• Get Search Status - Poll for completion

Get Results

• Get Search Results - Retrieve matched candidates with profiles and scores

🆚 Compare Algorithms

Compare multiple search algorithms side-by-side:

• List Search Groups - Browse all comparison groups
• Get Search Group - View group status and searches
• Get Group Results - Compare results across algorithms

Why Compare?

• A/B test which algorithm finds better candidates
• Evaluate speed vs quality tradeoffs
• Analyze candidate overlap between algorithms
• Choose optimal algorithm for production

⚡ Quick Start Example

# 1. Initiate search
POST /v1/public/searches/dense
{
  "query": "senior backend engineer with Python",
  "top_k": 20
}

# Returns immediately
{
  "searchId": "abc-123",
  "status": "processing",
  "estimatedTime": "5-10 seconds"
}

# 2. Poll for completion
GET /v1/public/searches/abc-123

# 3. Get results when completed
GET /v1/public/searches/abc-123/results

🎯 Algorithm Selection Guide

Choose Dense if:

• Natural language queries are common
• Speed matters (5-10s)
• Semantic relevance more important than exact keywords

Choose Sparse if:

• Keyword matching is sufficient
• Technical skill searches dominate
• Speed is critical (5-10s)

Choose Hybrid if:

• Quality matters most
• Complex queries mixing concepts and keywords
• Can accept slower processing (15-30s)

Choose Builtin-Rerank if:

• Need good middle-ground
• Semantic search with quality boost
• Cost-conscious (no external reranking APIs)

📚 Common Parameters

All search methods accept:

• query (required) - Search query (1-500 characters)
• top_k (optional) - Number of results (default: 20, max: 100)
• searchGroupId (optional) - Group for comparison
• explicit_filters (optional) - Location/seniority filters

Smart Filtering: Floreal automatically extracts filters from your natural language query.