Retrieve Search Results
Get completed search results with candidate CV data
This endpoint returns the full results of a completed search, including matched candidate profiles with complete CV text, relevance scores, professional summaries, and detailed attributes.
Prerequisites:
- Search must have status "completed"
- Use
GET /v1/public/searches/:searchIdto check status first - Results remain available for retrieval using the searchId
Response Structure
Top-Level Fields
searchId- Unique search identifier (UUID)searchGroupId- Optional group ID for comparing multiple searchesquery- Your original search query stringsearchType- Algorithm used:dense,sparse,hybrid, orbuiltin-rerankstatus- Always"completed"when returning resultsresults- Array of matched candidates (detailed below)totalResults- Number of results returnedmetadata- Processing time and timestamps
Result Items (Candidates)
Each item in the results[] array represents a matched candidate with the following structure:
Document Information
documentId- Unique CV document identifier (UUID)documentName- CV filename (e.g., "John_Doe_CV.pdf")documentDate- CV date in MM-YYYY formatscore- Relevance score (0-1, higher = better match)
Full CV Text
extractedText- Complete text extracted from the CV (5-15KB per document)- Contains the full, unredacted CV content
- Use for: full-text search, AI analysis, custom parsing, document preview
- Includes all original information from the candidate's CV
AI-Generated Summary
summary- Concise AI-generated professional summary including:- Name and location
- Years of experience
- Educational background
- Key technical skills
- Domain expertise
- Recent specializations
- Leadership experience
- Industry experience
Contact Information
{
"contact": {
"firstName": "Pierre",
"lastName": "Rognion",
"email": "pierre@example.com",
"linkedin": "linkedin.com/in/pierrerognion",
"location": {
"city": "Paris, Île-de-France",
"country": "FRA"
}
}
}Fields:
firstName- Candidate's first namelastName- Candidate's last nameemail- Email address (if present in CV)linkedin- LinkedIn profile URL (if present in CV)location.city- Current citylocation.country- Country code (ISO format)
Professional Profile
{
"profile": {
"domain": "Technology",
"specialization": "AI Engineering",
"seniorityLevel": "Senior",
"experienceYears": 11,
"technicalStack": ["Javascript", "Ruby", "Artificial Intelligence", "HTML"],
"industries": ["Edtech", "Fintech", "Consulting", "AI Industry"],
"recentExpertise": ["Generative AI", "AI Product Strategy", "AI Prototyping"],
"hasManagement": true
}
}Fields:
domain- Primary professional domain (e.g., "Technology", "Sales Marketing", "Business Operations")specialization- Specific area of expertiseseniorityLevel- Career level:Junior,Senior, orExecutiveexperienceYears- Total years of professional experiencetechnicalStack- Array of key technologies and toolsindustries- Array of industry verticals worked inrecentExpertise- Array of most recent areas of focushasManagement- Boolean indicating management/leadership experience
Detailed Attributes
The attributes object contains cleaned, structured data extracted from the CV:
Languages
{
"languages": {
"french": 1,
"english": 1,
"english_fluent": 1,
"languages_count": 2,
"cv_language_detected": "French"
}
}Market & Client Experience
{
"market_client": {
"emea": 1,
"startup": 1,
"b2b_focus": 1,
"enterprise": 1,
"north_america": 1,
"market_segments_count": 5,
"geographic_markets_count": 2
}
}Certifications
{
"certifications": {
"certifications_count": 4,
"continuing_education": 1,
"professional_certifications_count": 4
}
}Domain Analysis
{
"domain_analysis": {
"primary_domain": "technology",
"specializations": [
"Generative AI Product Leadership",
"AI Strategy and Implementation",
"AI Training and Adoption"
],
"secondary_domains": ["business-operations", "education-training"],
"primary_specialization": "AI Engineering",
"secondary_specializations": ["LLM Development", "Generative AI"]
}
}Technical Skills
{
"technical_skills": {
"ruby_experience": 1,
"html_css_experience": 1,
"javascript_experience": 1,
"artificial_intelligence": 1,
"programming_languages_count": 3
}
}Industry Verticals
{
"industry_verticals": {
"edtech": 1,
"fintech": 1,
"consulting": 1,
"ai_industry": 1,
"marketplace": 1,
"verticals_count": 5
}
}Performance Impact
{
"performance_impact": {
"innovation": 1,
"training_others": 1,
"knowledge_sharing": 1,
"system_performance": 1,
"process_improvement": 1,
"technical_leadership_impact": 1
}
}Education Indicators
{
"education_indicators": {
"highest_degree": "Master",
"coding_bootcamp": 1,
"education_field": ["International Relations", "Business"],
"first_school_name": "Sciences Po Aix",
"last_school_name": "Le Wagon",
"multiple_degrees": 1,
"education_prestige_score": 2
}
}Business Specialization
{
"business_specialization": {
"proof_of_concept": 1,
"technical_strategy": 1,
"product_development": 1,
"technical_mentoring": 1,
"business_orientation": 3,
"technical_innovation": 1,
"cross_functional_collaboration": 1
}
}Professional Experience Summary
{
"professional_experience": {
"total_experience_years": 11,
"number_of_employers": 8,
"average_tenure_months": 16,
"current_position_duration": 6,
"management_experience": 1,
"job_stability_score": 3,
"career_progression_score": 5,
"international_experience": 1
}
}Understanding Scores
Score Interpretation
The score field indicates relevance to your search query. Higher scores = better matches.
| Search Type | Score Range | Method | Interpretation |
|---|---|---|---|
| Dense | 0.0 - 1.0 | Cosine similarity | Semantic relevance |
| Sparse | Varies | BM25 | Keyword matching |
| Hybrid | 0.0 - 1.0 | Cohere reranker | Combined semantic + keyword |
| Builtin-Rerank | 0.0 - 1.0 | Pinecone reranker | Refined semantic |
Score Guidelines
| Score Range | Quality | Recommendation |
|---|---|---|
| 0.85 - 1.0 | Excellent | Top candidates - review immediately |
| 0.75 - 0.84 | Very good | Strong candidates - prioritize |
| 0.65 - 0.74 | Good | Review based on requirements |
| 0.50 - 0.64 | Moderate | Consider if needed |
| < 0.50 | Weak | Consider filtering out |
Metadata
{
"metadata": {
"processingTimeMs": 383,
"completedAt": "2025-11-04T11:35:14.010Z",
"createdAt": "2025-11-04T11:35:13.309Z"
}
}processingTimeMs- Total search processing time in millisecondscompletedAt- ISO 8601 timestamp when search finishedcreatedAt- ISO 8601 timestamp when search started
Status Handling
Search Still Processing
If search status is NOT "completed", the API returns HTTP 202 with:
{
"searchId": "uuid",
"searchGroupId": "uuid",
"status": "processing",
"message": "Search still processing",
"statusUrl": "/v1/public/searches/{searchId}"
}Status Codes:
- 202 - Search still processing (poll again)
- 400 - Search failed (check error message)
Empty Results
If totalResults: 0:
Possible Reasons:
- No candidates match your criteria
- Filters too restrictive
- No documents in your organization
Solutions:
- Use broader search terms
- Reduce explicit filters
- Try different search type
- Verify documents exist
Result Limits
| Parameter | Default | Maximum |
|---|---|---|
Dense/Sparse (top_k) | 20 | 100 |
Hybrid/Builtin-Rerank (rerank_top_n) | 30 | 100 |
Data Access
What's Included:
- ✅ Complete extracted CV text (
extractedText) - ✅ Full contact information (email, LinkedIn, phone if present in CV)
- ✅ Professional summaries and attributes
- ✅ Skills, experience, and education details
- ✅ All candidate-provided information
Security:
- Only returns CVs from your organization
- API key required for authentication
- Results are company-scoped
Use Cases
1. Display Search Results
const response = await fetch(`/v1/public/searches/${searchId}/results`, {
headers: { 'X-API-Key': 'your-key' }
});
const data = await response.json();
data.results.forEach(candidate => {
console.log(`${candidate.contact.firstName} ${candidate.contact.lastName}`);
console.log(`Score: ${candidate.score}`);
console.log(`Summary: ${candidate.summary}`);
});2. Filter by Score
const topCandidates = data.results.filter(c => c.score > 0.75);3. Full-Text Search in CV Content
const pythonExperts = data.results.filter(c =>
c.extractedText.toLowerCase().includes('python')
);4. Custom AI Analysis
// Send full CV text to your own AI for custom analysis
const analysis = await analyzeCV(candidate.extractedText);5. Group by Location
const byLocation = data.results.reduce((acc, c) => {
const city = c.contact.location.city;
acc[city] = acc[city] || [];
acc[city].push(c);
return acc;
}, {});Error Responses
404 - Search Not Found
{
"error": "Search not found",
"searchId": "uuid"
}Reasons:
- Invalid searchId
- Search doesn't belong to your company
- Search was deleted
500 - Server Error
{
"error": "Failed to get results"
}Action: Retry request or contact support
Best Practices
1. Poll for Completion First
// Check status before requesting results
const statusRes = await fetch(`/v1/public/searches/${searchId}`);
const { status } = await statusRes.json();
if (status === 'completed') {
const resultsRes = await fetch(`/v1/public/searches/${searchId}/results`);
const data = await resultsRes.json();
}2. Filter Low-Quality Matches
// Only show candidates with score > 0.7
const qualified = data.results.filter(c => c.score > 0.7);3. Handle Empty Results
if (data.totalResults === 0) {
console.log('No matches found. Try broader search terms.');
}4. Use extractedText for Advanced Features
// Full-text search
// Custom parsing
// AI-powered analysis
// Document generation
const fullCV = candidate.extractedText;5. Cache Results
// Results don't change - safe to cache
localStorage.setItem(`search-${searchId}`, JSON.stringify(data));Performance
Response Size:
- Without
extractedText: ~5-10KB per candidate - With
extractedText: ~15-25KB per candidate - 10 results: ~150-250KB total
Optimization Tips:
- Results are cached server-side
- No rate limits on this endpoint
- Multiple requests for same searchId are fast
Pro Tips
💡 Quality:
- Dense search: Best for natural language queries
- Sparse search: Best for exact skill matching
- Hybrid search: Best overall quality
- Use score thresholds (>0.7) to filter results
💡 Integration:
- Store
searchIdfor future reference - Results never expire
- Use
searchGroupIdto compare multiple searches - Parse
extractedTextfor custom fields not in structured data
💡 Analysis:
extractedTextcontains complete CV - use for any custom parsing- Structured fields provide quick access to common data points
- Combine both for comprehensive candidate analysis
API key for public API access. Get yours at https://app.floreal.ai?tab=api
In: header
Path Parameters
uuidResponse Body
curl -X GET "https://api.floreal.ai/v1/public/searches/497f6eca-6276-4993-bfeb-53cbbbba6f08/results"{
"searchId": "9b1a67f9-9477-48e5-8a6c-11b70245e1d9",
"searchGroupId": "6057d3c7-e3bb-4624-80c0-432d9633004b",
"query": "string",
"searchType": "dense",
"status": "completed",
"results": [
{
"documentId": "4704590c-004e-410d-adf7-acb7ca0a7052",
"documentName": "string",
"documentDate": "string",
"score": 0,
"extractedText": "string",
"summary": "string",
"contact": {
"firstName": "string",
"lastName": "string",
"email": "string",
"linkedin": "string",
"location": {
"city": "string",
"country": "string"
}
},
"profile": {
"domain": "string",
"specialization": "string",
"seniorityLevel": "string",
"experienceYears": 0,
"technicalStack": [
"string"
],
"industries": [
"string"
],
"recentExpertise": [
"string"
],
"hasManagement": true
},
"attributes": {}
}
],
"totalResults": 0,
"metadata": {
"processingTimeMs": 0,
"completedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z"
}
}{
"error": "string",
"message": "string"
}{
"error": "string"
}{
"error": "string",
"message": "string"
}