Floreal Logo
SearchSearch Results

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/:searchId to 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 searches
  • query - Your original search query string
  • searchType - Algorithm used: dense, sparse, hybrid, or builtin-rerank
  • status - Always "completed" when returning results
  • results - Array of matched candidates (detailed below)
  • totalResults - Number of results returned
  • metadata - 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 format
  • score - 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 name
  • lastName - Candidate's last name
  • email - Email address (if present in CV)
  • linkedin - LinkedIn profile URL (if present in CV)
  • location.city - Current city
  • location.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 expertise
  • seniorityLevel - Career level: Junior, Senior, or Executive
  • experienceYears - Total years of professional experience
  • technicalStack - Array of key technologies and tools
  • industries - Array of industry verticals worked in
  • recentExpertise - Array of most recent areas of focus
  • hasManagement - 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 TypeScore RangeMethodInterpretation
Dense0.0 - 1.0Cosine similaritySemantic relevance
SparseVariesBM25Keyword matching
Hybrid0.0 - 1.0Cohere rerankerCombined semantic + keyword
Builtin-Rerank0.0 - 1.0Pinecone rerankerRefined semantic

Score Guidelines

Score RangeQualityRecommendation
0.85 - 1.0ExcellentTop candidates - review immediately
0.75 - 0.84Very goodStrong candidates - prioritize
0.65 - 0.74GoodReview based on requirements
0.50 - 0.64ModerateConsider if needed
< 0.50WeakConsider 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 milliseconds
  • completedAt - ISO 8601 timestamp when search finished
  • createdAt - 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

ParameterDefaultMaximum
Dense/Sparse (top_k)20100
Hybrid/Builtin-Rerank (rerank_top_n)30100

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 searchId for future reference
  • Results never expire
  • Use searchGroupId to compare multiple searches
  • Parse extractedText for custom fields not in structured data

💡 Analysis:

  • extractedText contains complete CV - use for any custom parsing
  • Structured fields provide quick access to common data points
  • Combine both for comprehensive candidate analysis
GET
/v1/public/searches/{searchId}/results
X-API-Key<token>

API key for public API access. Get yours at https://app.floreal.ai?tab=api

In: header

Path Parameters

searchIdstring
Formatuuid

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