Spotlite API

Ajoutez l'analyse IA de candidats à votre ATS en quelques heures — sans infrastructure ML, sans forfait fixe.

// 1. Analyser la vidéo
const analysis = await fetch('https://europe-west6-spotlite-9da69.cloudfunctions.net/apiAnalyzeVideoApplication', {
  method: 'POST',
  headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ videoUrl: candidate.videoUrl, candidateId: candidate.id, jobDescription: job.description })
}).then(r => r.json());

// 2. Générer le CV structuré
const cv = await fetch('https://europe-west6-spotlite-9da69.cloudfunctions.net/apiBuildCvFromVideo', {
  method: 'POST',
  headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ videoUrl: candidate.videoUrl })
}).then(r => r.json());

// 3. Matcher au poste
const match = await fetch('https://europe-west6-spotlite-9da69.cloudfunctions.net/apiMatchCandidateToJob', {
  method: 'POST',
  headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ cvData: cv.result, jobDescription: job.description })
}).then(r => r.json());

if (match.matchScore >= 75) addToShortlist(candidate); // ~0,50 € / candidat

// 1. Extraire le profil depuis LinkedIn
const profile = await fetch('https://europe-west6-spotlite-9da69.cloudfunctions.net/apiExtractProfileFromUrl', {
  method: 'POST',
  headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ profileUrl: 'https://linkedin.com/in/marie-dupont', language: 'fr' })
}).then(r => r.json());

// 2. Matcher sur un poste
const match = await fetch('https://europe-west6-spotlite-9da69.cloudfunctions.net/apiMatchCandidateToJob', {
  method: 'POST',
  headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ cvData: profile, jobDescription: job.description })
}).then(r => r.json());

// 3. Préparer l'entretien avec le coach IA (SSE streaming)
const coachRes = await fetch('https://europe-west6-spotlite-9da69.cloudfunctions.net/apiCareerCoachEmbed', {
  method: 'POST',
  headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: 'Quelles questions préparer pour un poste Lead Dev React ?',
    jobDescription: job.description
  })
});
// Lire le stream SSE token par token
const reader = coachRes.body.getReader();
// Coût total pipeline : ~0,12 € par profil qualifié

// 1. Extraire l'offre depuis l'URL scrapée
const job = await fetch('https://europe-west6-spotlite-9da69.cloudfunctions.net/apiExtractJobFromUrl', {
  method: 'POST',
  headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ jobUrl: scrapedUrl, language: 'fr' })
}).then(r => r.json());

// 2. Matcher sur les candidats inscrits (en batch)
for (const candidate of candidates) {
  const match = await fetch('https://europe-west6-spotlite-9da69.cloudfunctions.net/apiMatchCandidateToJob', {
    method: 'POST',
    headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ cvData: candidate.profile, jobDescription: job.missionSummary })
  }).then(r => r.json());

  if (match.matchScore >= 70) sendAlert(candidate, job); // notif email/push
}
// Coût : ~0,03 € / offre · 3 crédits extractJob + 7 crédits / match

const API = 'https://europe-west6-spotlite-9da69.cloudfunctions.net';
const H = { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' };
const post = (path, body) => fetch(API + path, { method: 'POST', headers: H, body: JSON.stringify(body) }).then(r => r.json());

async function enrichWithPersonality(candidate, jobDescription) {
  // 1. Bilan passif depuis les écrits du candidat (lettre de motivation, notes...)
  const bilan = await post('/apiAssessPassiveProfile', {
    texts: candidate.writtenTexts,  // [{ date, title, content }, ...]
    framework: 'big5',
    language: 'fr'
  });
  // bilan.scores.openness / conscientiousness / extraversion / agreeableness / neuroticism
  // bilan.scores.dominant_trait, bilan.insights, bilan.career_implications

  // 2. Matching CV ↔ poste
  const match = await post('/apiMatchCandidateToJob', {
    candidateProfile: candidate.profile,
    jobDescription
  });

  // 3. Décision combinée : score technique + fit culturel (conscientiousness + openness)
  const s = bilan.scores;
  const culturalFit = s.conscientiousness > 65 && s.openness > 60;
  return {
    matchScore: match.matchScore,
    dominantTrait: s.dominant_trait,
    confidence: bilan.confidence,   // 0–1 : fiabilité selon volume de texte
    insights: bilan.insights,
    culturalFit,
    shortlisted: match.matchScore >= 70 && culturalFit,
  };
}
// Coût : 30 crédits (bilan) + 7 crédits (match) ≈ 0,37 € par candidat

const BASE = 'https://europe-west6-spotlite-9da69.cloudfunctions.net';
const HEADERS = { 'X-API-Key': process.env.SPOTLITE_API_KEY, 'Content-Type': 'application/json' };
const post = (path, body) =>
  fetch(BASE + path, { method: 'POST', headers: HEADERS, body: JSON.stringify(body) }).then(r => r.json());

async function verifyDocument(fileBase64, mimeType) {
  const result = await post('/apiVerifyProof', { fileBase64, mimeType, language: 'fr' });
  if (!result.accepted) {
    console.warn('Document non accepté :', result.rejectionReason);
    return null;
  }
  console.log('Titulaire :', result.holderName);
  console.log('Intitulé :', result.title);
  console.log('Résumé RH :', result.professionalSummary);
  console.log('Score cohérence :', result.confidenceScore, '/ 100');
  // Injecter dans le dossier ATS
  return {
    atsTitle: result.title,
    holder: result.holderName,
    summary: result.professionalSummary,
    score: result.confidenceScore,
    type: result.type,
    sources: result.sources
  };
}
// Coût : min. 5 crédits · facturation à la consommation réelle

const BASE = 'https://europe-west6-spotlite-9da69.cloudfunctions.net';
const HEADERS = { 'X-API-Key': process.env.SPOTLITE_API_KEY, 'Content-Type': 'application/json' };
const post = (path, body) =>
  fetch(BASE + path, { method: 'POST', headers: HEADERS, body: JSON.stringify(body) }).then(r => r.json());

async function fullEsnPipeline(linkedinUrl, jobUrl) {
  // 1. Extraire le profil candidat
  const profile = await post('/apiExtractProfileFromUrl', { profileUrl: linkedinUrl, language: 'fr' });
  console.log('Profil extrait :', profile.name, '—', profile.headline);

  // 2. Extraire l'offre d'emploi
  const job = await post('/apiExtractJobFromUrl', { jobUrl, language: 'fr' });
  console.log('Offre extraite :', job.jobTitle, 'chez', job.company);

  // 3. Score de matching
  const match = await post('/apiMatchCandidateToJob', {
    cvData: profile,
    jobDescription: job.missionSummary
  });
  console.log('Score :', match.matchScore, '/ 100 —', match.recommendation);

  // 4. Préparer l'entretien avec le coach IA (SSE streaming)
  const coachRes = await fetch(BASE + '/apiCareerCoachEmbed', {
    method: 'POST', headers: HEADERS,
    body: JSON.stringify({
      message: `Quelles questions préparer pour le poste ${job.jobTitle} chez ${job.company} ?`,
      jobDescription: job.missionSummary
    })
  });
  const reader = coachRes.body.getReader();
  const decoder = new TextDecoder();
  process.stdout.write('\nCoach : ');
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    decoder.decode(value, { stream: true }).split('\n').forEach(line => {
      if (!line.startsWith('data:')) return;
      try { const e = JSON.parse(line.slice(5)); if (e.token) process.stdout.write(e.token); } catch {}
    });
  }
  // Coût total : ~13 crédits · profil(3) + offre(3) + match(7) · coach à la consommation
  return { profile, job, match };
}

fullEsnPipeline('https://linkedin.com/in/marie-dupont', 'https://linkedin.com/jobs/view/123456789');

import httpx, asyncio, os, json

BASE = "https://europe-west6-spotlite-9da69.cloudfunctions.net"
HEADERS = {"X-API-Key": os.environ["SPOTLITE_API_KEY"], "Content-Type": "application/json"}

async def post(client, path, body):
    r = await client.post(BASE + path, json=body, headers=HEADERS)
    r.raise_for_status()
    return r.json()

async def full_esn_pipeline(linkedin_url, job_url):
    async with httpx.AsyncClient(timeout=60) as client:
        # 1. Extraire le profil
        profile = await post(client, "/apiExtractProfileFromUrl",
                                {"profileUrl": linkedin_url, "language": "fr"})
        print(f"Profil : {profile['name']} — {profile['headline']}")

        # 2. Extraire l'offre
        job = await post(client, "/apiExtractJobFromUrl",
                          {"jobUrl": job_url, "language": "fr"})
        print(f"Offre : {job['jobTitle']} chez {job['company']}")

        # 3. Matching
        match = await post(client, "/apiMatchCandidateToJob",
                            {"cvData": profile, "jobDescription": job["missionSummary"]})
        print(f"Score : {match['matchScore']}/100 — {match['recommendation']}")

        # 4. Coach IA (SSE streaming)
        async with client.stream("POST", BASE + "/apiCareerCoachEmbed", headers=HEADERS,
            json={"message": f"Questions pour {job['jobTitle']} chez {job['company']} ?",
                  "jobDescription": job["missionSummary"]}) as resp:
            async for line in resp.aiter_lines():
                if line.startswith("data:"):
                    ev = json.loads(line[5:])
                    if "token" in ev: print(ev["token"], end="", flush=True)

        return {"profile": profile, "job": job, "match": match}

asyncio.run(full_esn_pipeline(
    "https://linkedin.com/in/marie-dupont",
    "https://linkedin.com/jobs/view/123456789"
))

Spotlite API

L'API Spotlite permet à votre entreprise d'intégrer les capacités d'analyse de candidats directement dans votre ATS, SIRH ou pipeline de recrutement. Toutes les analyses sont propulsées par des modèles IA multimodaux (vidéo, texte, CV).

Base URL :

https://europe-west6-spotlite-9da69.cloudfunctions.net

Obtenir l'accès API

Authentification

Incluez votre clé API dans le header X-API-Key de chaque requête.

# Avec curl
curl -X POST https://europe-west6-spotlite-9da69.cloudfunctions.net/apiMatchCandidateToJob \
  -H "X-API-Key: sk_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

// Avec Node.js / fetch
const response = await fetch('https://europe-west6-spotlite-9da69.cloudfunctions.net/apiMatchCandidateToJob', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.SPOTLITE_API_KEY, // jamais en dur dans le code
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ /* ... */ }),
});

# Avec Python / requests
import requests, os

headers = {
    "X-API-Key": os.environ["SPOTLITE_API_KEY"],
    "Content-Type": "application/json",
}
resp = requests.post(
    "https://europe-west6-spotlite-9da69.cloudfunctions.net/apiMatchCandidateToJob",
    headers=headers,
    json={# ...}
)

🧪 Playground — Tester l'API

Entrez votre clé API ci-dessous et testez chaque endpoint directement depuis votre navigateur. Les crédits sont débités de votre compte réel.

Système de crédits

Chaque appel API consomme des crédits depuis votre wallet Spotlite. Le solde est vérifié avant chaque appel — si insuffisant, l'appel est rejeté avec un 402 sans vous facturer.

⚡ Analyser un bundle multi-médias

{
  "mediaItems": [                  // Requis — 1 à 5 items
    {
      "url": "https://...",        // URL publique de la source
      "type": "video" | "image"   // Optionnel : auto-détecté depuis l'extension
    }
  ],
  "candidateId": "string",        // Optionnel
  "jobDescription": "string",     // Optionnel : active le scoring de correspondance
  "language": "fr"                // Optionnel, défaut "fr"
}

{
  "candidateId": "abc123",
  "sources": [
    { "url": "https://...", "type": "video", "mimeType": "video/mp4" },
    { "url": "https://...", "type": "image", "mimeType": "image/jpeg" }
  ],
  "hardSkills": ["React", "TypeScript", "Node.js"],
  "softSkills": ["Leadership", "Communication"],
  "transferableSkills": ["Gestion de projet"],
  "potentialJobMatches": ["Développeur Full Stack", "Tech Lead"],
  "expertiseLevel": "confirme",
  "employabilityScore": 84,
  "summary": {
    "global": "Candidat avec une solide maîtrise...",
    "perSource": [
      "Vidéo 1 : présentation fluide, expert React...",
      "Image 1 : portfolio structuré, projets variés..."
    ]
  },
  "transcript": "Bonjour, je m'appelle...",
  "detectedTools": ["VS Code", "Figma"],
  "semanticTags": ["frontend", "cloud"],
  "crossSourceInsight": "Les 2 sources confirment une expertise frontend solide. La vidéo révèle une aisance orale que le portfolio ne suggère pas.",
  "moderationScore": 1,
  "primarySector": "Informatique",
  "yearsOfExperienceEstimate": "5-10",

  // Si jobDescription fourni :
  "matchScore": 87,
  "matchedSkills": ["React", "TypeScript"],
  "missingSkills": ["AWS"],
  "matchInsight": "Excellent profil technique, seule la dimension cloud est à renforcer.",

  // Facturation
  "creditsUsed": 7,
  "remainingCredits": 93,
  "tokensUsed": { "input": 47230, "output": 1842, "total": 49072 }
}

🛡️ Vérifier une preuve documentaire

{
  // Mode 1 — fichier encodé en base64
  "fileBase64": "JVBERi0xLjQ...",   // PDF ou image en base64 (sans préfixe data:)
  "mimeType": "application/pdf",     // Requis avec fileBase64

  // Mode 2 — fichier distant (alternatif)
  "fileUrl": "https://.../diplome.pdf",

  // Mode 3 — document décrit en JSON (alternatif)
  "documentJson": {
    "title": "CACES R489 catégorie 3",
    "issuer": "AFTRAL",
    "holder": "Marie Dupont",
    "date": "2024-03-12",
    "referenceNumber": "R489-3-2024-0098"
  },

  "language": "fr"                   // Optionnel : force la langue de sortie
}

{
  "eligible": true,
  "documentQuality": "good",
  "accepted": true,                  // true si éligible, lisible et score > 60
  "type": "license",                 // diploma|certification|license|agreement|attestation|other
  "title": "CACES R489 catégorie 3 — Chariot élévateur frontal",
  "issuer": "AFTRAL",
  "holderName": "Marie Dupont",
  "professionalSummary": "Ce certificat atteste que la personne est habilitée à conduire en sécurité des chariots élévateurs frontaux (catégorie 3). C'est un prérequis réglementaire pour les postes de cariste en entrepôt ou en logistique.",
  "confidenceScore": 88,
  "verdict": "Cohérent",
  "explanation": "Le document présente une structure et une terminologie conformes au référentiel CACES R489...",
  "coherentPoints": ["Organisme certificateur reconnu", "Catégorie valide pour le référentiel R489"],
  "coherenceFlags": [],
  "rejectionReason": "",
  "diploma": null,
  "certification": null,
  "license": {
    "licenseType": "CACES R489",
    "category": "Catégorie 3",
    "authority": "AFTRAL",
    "referenceNumber": "R489-3-2024-0098",
    "issueDate": "2024-03-12",
    "validUntil": "2029-03-12"
  },
  "sources": [{ "title": "Référentiel CACES R489", "url": "https://..." }],
  "language": "fr",
  "creditsUsed": 5,
  "remainingCredits": 95,
  "tokensUsed": { "input": 12430, "output": 920, "total": 13350 }
}

curl -X POST \
  https://europe-west6-spotlite-9da69.cloudfunctions.net/apiVerifyProof \
  -H "X-API-Key: $SPOTLITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"fileBase64\": \"$(base64 -i diplome.pdf)\",
    \"mimeType\": \"application/pdf\"
  }"

const res = await fetch('https://europe-west6-spotlite-9da69.cloudfunctions.net/apiVerifyProof', {
  method: 'POST',
  headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ fileUrl: 'https://exemple.com/certificat.png' })
});
const proof = await res.json();
console.log(proof.title, proof.holderName, proof.confidenceScore, proof.professionalSummary);

import requests

res = requests.post(
    "https://europe-west6-spotlite-9da69.cloudfunctions.net/apiVerifyProof",
    headers={"X-API-Key": API_KEY},
    json={"documentJson": {
        "title": "Master Informatique",
        "issuer": "Université de Lille",
        "holder": "Karim Benali",
        "year": "2022",
    }},
)
print(res.json()["professionalSummary"])

Analyser une vidéo de candidature

POST /apiAnalyzeVideoApplication
X-API-Key: sk_live_...
Content-Type: application/json

{
  "videoUrl": "https://storage.mon-ats.com/videos/candidat_42.mp4",
  "candidateId": "candidat_42",
  "jobDescription": "Développeur React senior, 5 ans d'expérience minimum, leadership d'équipe",
  "language": "fr"
}

{
  "jobId": "xK9pL2mNqRt8...",
  "status": "queued",
  "estimatedSeconds": 45,
  "creditsReserved": "variable"
}

// Interrogez GET /apiGetAccountStats ou stockez le jobId
// Résultat disponible dans Firestore : apiJobs/{jobId}
{
  "jobId": "xK9pL2mNqRt8...",
  "status": "completed",
  "result": {
    "overallScore": 78,
    "strengths": ["Communication claire", "Expérience React confirmée"],
    "weaknesses": ["Peu d'expérience management"],
    "recommendation": "hire",
    "transcript": "Bonjour, je m'appelle Marie...",
    "softSkills": {
      "confidence": 82,
      "clarity": 75,
      "enthusiasm": 90
    }
  },
  "creditsUsed": "variable",
  "tokensUsed": { "input": 4200, "output": 820, "total": 5020 }
}

Générer un CV depuis une vidéo

POST /apiBuildCvFromVideo
X-API-Key: sk_live_...
Content-Type: application/json

{
  "videoUrl": "https://storage.mon-ats.com/intros/marie_dupont.mp4",
  "candidateId": "marie_dupont_001",
  "language": "fr"
}

{
  "status": "completed",
  "result": {
    "fullName": "Marie Dupont",
    "summary": "Data scientist avec 5 ans d'expérience en NLP et ML appliqué au RH",
    "skills": ["Python", "TensorFlow", "SQL", "NLP"],
    "experience": [
      { "title": "Data Scientist", "company": "BNP Paribas", "duration": "3 ans" }
    ],
    "education": [
      { "degree": "Master IA", "school": "Paris-Saclay", "year": "2020" }
    ]
  }
}

Matcher un candidat à un poste

POST /apiMatchCandidateToJob
X-API-Key: sk_live_...
Content-Type: application/json

{
  "candidateProfile": {
    "skills": ["Python", "Machine Learning", "SQL"],
    "experience": "4 ans data scientist chez des startups fintech",
    "education": "Master Intelligence Artificielle, Paris-Saclay"
  },
  "jobDescription": "Data Scientist senior, spécialité NLP, 5 ans minimum, Python, gestion d'équipe souhaitée"
}

{
  "matchScore": 82,
  "matchedSkills": ["Python", "Machine Learning"],
  "missingSkills": ["NLP", "leadership"],
  "insight": "Bon profil technique, solide expérience Python/ML. Manque d'expérience NLP spécifique et de gestion d'équipe.",
  "creditsUsed": 7,
  "remainingBalance": 478
}

Analyser un dossier de candidature

POST /apiAnalyzeCandidateBundle
X-API-Key: sk_live_...
Content-Type: application/json

{
  "cvText": "Marie Dupont — Data Scientist\n5 ans d'expérience...",
  "coverLetter": "Madame, Monsieur, Passionnée par le NLP...",
  "jobDescription": "Data Scientist NLP senior",
  "candidateId": "marie_001"
}

{
  "overallScore": 85,
  "cvScore": 88,
  "motivationScore": 79,
  "strengths": ["Expérience très pertinente", "Lettre personnalisée et convaincante"],
  "recommendation": "shortlist",
  "creditsUsed": "variable",
  "tokensUsed": { "input": 3200, "output": 600, "total": 3800 }
}

Career Coach (embed)

POST /apiCareerCoachEmbed
X-API-Key: sk_live_...
Content-Type: application/json

{
  "message": "Comment améliorer mon profil LinkedIn pour attirer des recruteurs tech ?",
  "candidateContext": "Développeur backend 3 ans, Python et Node.js, recherche poste senior",
  "language": "fr"
}

{
  "reply": "Pour attirer des recruteurs tech, misez sur 3 points clés : 1) Mettez vos technologies en titre (ex: 'Backend Engineer — Python & Node.js'), 2) Détaillez l'impact de vos projets en chiffres, 3) Contribuez à des projets open source et liez-les...",
  "creditsUsed": 1
}

Extraire une offre d'emploi

POST /apiExtractJobFromUrl
X-API-Key: sk_live_...
Content-Type: application/json

{
  "jobUrl": "https://www.linkedin.com/jobs/view/123456789",
  "jobTitle": "Développeur React Senior",
  "language": "fr"
}

{
  "jobTitle": "Développeur React Senior",
  "company": "TechCorp Paris",
  "location": "Paris, France",
  "contractType": "CDI",
  "salary": "55 000 € – 70 000 € / an",
  "requiredSkills": ["React", "TypeScript", "Node.js"],
  "niceToHave": ["GraphQL", "AWS"],
  "experienceYears": 5,
  "missionSummary": "Développer et maintenir des applications React haute performance...",
  "creditsUsed": 3,
  "remainingCredits": 475
}

Extraire un profil candidat

POST /apiExtractProfileFromUrl
X-API-Key: sk_live_...
Content-Type: application/json

{
  "profileUrl": "https://linkedin.com/in/marie-dupont",
  "candidateName": "Marie Dupont",
  "language": "fr"
}

{
  "name": "Marie Dupont",
  "headline": "Développeuse Full-Stack • 5 ans XP",
  "skills": ["React", "Node.js", "Python"],
  "experiences": [
    { "title": "Lead Dev", "company": "StartupXYZ", "years": 3 }
  ],
  "education": [{ "degree": "Master Informatique", "school": "EPITA" }],
  "languages": ["Français", "Anglais"],
  "creditsUsed": 3,
  "remainingCredits": 472
}

Bilan de personnalité passif

Analyse passive de la personnalité d'un candidat à partir de son journal de carrière. Aucun questionnaire — tout est inféré depuis l'écriture, les thèmes récurrents et le style rédactionnel.

POST /apiAssessPassiveProfile
X-API-Key: sk_live_your_key
Content-Type: application/json

{
  "texts": [
    { "date": "2025-11-03", "title": "Nouvelle mission", "content": "J'ai accepté cette mission data science malgré les process rigides — la liberté technique et le sujet m'ont convaincu. J'ai besoin de construire quelque chose de réel." },
    { "date": "2025-12-02", "title": "Fin de sprint", "content": "Sprint intense. J'ai refactorisé tout le preprocessing sans qu'on me le demande. L'équipe a apprécié mais certains auraient préféré avancer plus vite. La perfectibilité a un coût." },
    { "date": "2026-01-08", "title": "Offre refusée", "content": "J'ai refusé un poste de lead tech. 70% management, ce n'est pas ce que je veux. Je préfère des missions techniques pointues et garder ma liberté." }
  ],
  "framework": "big5",
  "language": "fr"
}

{
  "framework": "big5",
  "scores": {
    "openness": 82,
    "conscientiousness": 74,
    "extraversion": 41,
    "agreeableness": 68,
    "neuroticism": 29,
    "dominant_trait": "openness",
    "description": "Profil très ouvert aux idées nouvelles et créatif, avec une stabilité émotionnelle marquée. L'introversion modérée suggère un travail en profondeur plutôt qu'en réseau.",
    "confidence": 0.78,
    "data_points": 17,
    "insights": [
      "Exploration intellectuelle intense : 73% des entrées mentionnent des apprentissages ou lectures",
      "Faible névrosisme malgré 3 périodes de pression intense détectées",
      "Tendance à structurer ses pensées par écrit avant d'agir"
    ],
    "career_implications": [
      "Idéal pour des rôles nécessitant créativité et autonomie intellectuelle",
      "Éviter les environnements très procéduraux ou répétitifs",
      "Bon candidat pour le télétravail ou les missions longues sur un même projet"
    ]
  },
  "confidence": 0.78,
  "data_points": 17,
  "period_days": 90,
  "insights": ["..."],
  "career_implications": ["..."],
  "creditsUsed": 30,
  "remainingCredits": 470
}

{
  "texts": [ /* même format... */ ],
  "framework": "schein",
  "language": "en"
}

{
  "error": {
    "code": "insufficient_data",
    "message": "Données insuffisantes : 2 entrée(s) valide(s). Minimum 3 requis pour une analyse fiable.",
    "data_points": 2
  }
}

Compte & statistiques

GET /apiGetAccountStats
X-API-Key: sk_live_...

{
  "companyName": "TalentCorp SAS",
  "creditBalance": 478,
  "totalCreditsUsed": 1243,
  "allowedActions": ["analyzeVideoApplication", "matchCandidateToJob"],
  "usageByAction": {
    "analyzeVideoApplication": { "callCount": 52, "totalCredits": 936 },
    "matchCandidateToJob":     { "callCount": 44, "totalCredits": 308 }
  },
  "recentUsage": [
    { "action": "matchCandidateToJob",    "creditsUsed": 7,  "at": 1747700000000 },
    { "action": "analyzeVideoApplication", "creditsUsed": 18, "at": 1747690000000 }
  ]
}

Tests de personnalité (questionnaire)

Contrairement au bilan passif (qui déduit un profil d'un CV), ces trois endpoints vous laissent administrer un vrai test dans votre interface : vous récupérez les items, vous posez les questions, vous envoyez les réponses. Les clés de scoring ne quittent jamais nos serveurs.

Frameworks : mbti (choix forcé), big5, disc, enneagram (échelle de Likert 1-5).

{
  "framework": "big5",
  "format": "likert5",
  "scale": [ { "value": 1, "label": "Pas du tout d'accord" } ],
  "items": [ { "id": "b5_01", "label": "Je me lie facilement…" } ]
}

{
  "framework": "big5",
  "scores": { "openness": 72, "conscientiousness": 64 },
  "interpretation": {
    "headline": "Curieuse et méthodique",
    "summary": "…",
    "typeCode": "INTJ",
    "dimensions": [ { "key": "openness", "label": "Ouverture" } ]
  }
}

{
  "narrative": "Marie combine une forte ouverture…",
  "creditsCharged": 4,
  "remainingCredits": 474
}

🏢 API ATS — piloter un espace de recrutement

Tout ce que fait l'espace recruteur Spotlite (recruiter.spotlite-app.com) passe par ces endpoints : le site n'a aucun privilège que votre clé n'ait pas. Candidats, offres, candidatures, évaluations, rendez-vous, visio, signatures — vous pouvez reconstruire l'outil entier, ou n'en brancher qu'un morceau dans le vôtre.

Candidats

Fiches candidats du compte : création, mise à jour, import en lot, enrichissement IA et partage anonymisé.

Offres d'emploi

Brouillons, publication sur Spotlite, pages publiques de candidature et matching.

Candidatures

Ce que reçoivent vos offres, publiées ou partagées par lien.

Clients & prospection

Entreprises pour lesquelles vous recrutez, et signaux faibles détectés à leur sujet.

Notes & tâches

Le tableau de pilotage : notes, tâches, rattachements et positions.

Évaluations

Tests de personnalité envoyés aux candidats. 10 envois par mois offerts, illimité avec un pass payant (au-delà, la réponse est un 402 pass_required).

Rendez-vous

Calendriers publics façon prise de rendez-vous. 30 réservations par mois offertes, illimité avec un pass payant. Les pages de réservation elles-mêmes s'appuient sur des endpoints anonymes, non documentés ici.

Visio & entretiens

Salles P2P natives et entretiens IA. Jusqu'à 4 participants : gratuit. 5 à 6 participants : pass payant.

Signatures électroniques

Envoi de documents à signer. 3 envois par mois offerts, puis 10 crédits par document. Le parcours du signataire passe par des endpoints anonymes, non documentés ici.

Sourcing & vivier

Le vivier « Open to work » ne contient que des candidats qui ont explicitement accepté d'y figurer. Aucune capture de profil depuis un site tiers n'est possible, par conception.

Collaboration & Copilot

Équipe, droits et discussion interne. Aucune clé API n'est jamais partagée avec un collaborateur : les invitations créent des accès distincts.

Compte & solde IA

État du compte et conversion de crédits Spotlite en solde IA.

Politique d'utilisation acceptable

L'API Spotlite est mise à disposition dans le cadre d'un usage professionnel légitime lié au recrutement et à l'évaluation de candidats. En utilisant l'API, vous acceptez les conditions suivantes.

Pour toute question : formulaire de contact

Codes d'erreur

Exemple complet — Pipeline ATS

Intégration typique : présélection automatique de 100 candidats avec scoring vidéo + matching.

// Node.js — Pipeline complet : upload vidéo → analyse → match → shortlist
const SPOTLITE_API = 'https://europe-west6-spotlite-9da69.cloudfunctions.net';
const API_KEY = process.env.SPOTLITE_API_KEY;

async function processCandidate(candidate) {
  // 1. Vérifier le solde avant de commencer
  const stats = await fetch(`${SPOTLITE_API}/apiGetAccountStats`, {
    headers: { 'X-API-Key': API_KEY }
  }).then(r => r.json());

  if (stats.walletCredits < 22) { // 15 (vidéo) + 7 (match)
    throw new Error('Solde insuffisant pour traiter ce candidat');
  }

  // 2. Lancer l'analyse vidéo (async)
  const videoJob = await fetch(`${SPOTLITE_API}/apiAnalyzeVideoApplication`, {
    method: 'POST',
    headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      videoUrl: candidate.videoUrl,
      candidateId: candidate.id,
      jobDescription: candidate.jobDescription,
      language: 'fr'
    })
  }).then(r => r.json());

  // 3. Matcher le profil CV (sync, pendant que la vidéo est traitée)
  const matchResult = await fetch(`${SPOTLITE_API}/apiMatchCandidateToJob`, {
    method: 'POST',
    headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      candidateProfile: candidate.profile,
      jobDescription: candidate.jobDescription
    })
  }).then(r => r.json());

  // 4. Décision finale
  const shouldShortlist = matchResult.matchScore >= 70;
  console.log(`Candidat ${candidate.id} — match: ${matchResult.matchScore}% — jobId vidéo: ${videoJob.jobId}`);

  return {
    candidateId: candidate.id,
    matchScore: matchResult.matchScore,
    videoJobId: videoJob.jobId,
    shortlisted: shouldShortlist,
    missingSkills: matchResult.missingSkills,
  };
}

// Traitement de 100 candidats en parallèle (10 par batch)
async function processBatch(candidates) {
  const results = [];
  for (let i = 0; i < candidates.length; i += 10) {
    const batch = candidates.slice(i, i + 10);
    const batchResults = await Promise.allSettled(batch.map(processCandidate));
    results.push(...batchResults);
  }
  return results;
}

# Python — Même pipeline
import requests, os, time

API_BASE = "https://europe-west6-spotlite-9da69.cloudfunctions.net"
HEADERS = {
    "X-API-Key": os.environ["SPOTLITE_API_KEY"],
    "Content-Type": "application/json",
}

def match_candidate(candidate_profile: dict, job_description: str) -> dict:
    resp = requests.post(
        f"{API_BASE}/apiMatchCandidateToJob",
        headers=HEADERS,
        json={"candidateProfile": candidate_profile, "jobDescription": job_description},
        timeout=30
    )
    resp.raise_for_status()
    return resp.json()

# Gestion des erreurs
try:
    result = match_candidate(profile, job_desc)
    print(f"Score: {result['matchScore']}% — Crédits restants: {result['remainingBalance']}")
except requests.HTTPError as e:
    error = e.response.json().get("error", {})
    if error.get("code") == "insufficient_credits":
        print("Solde épuisé — recharger le wallet Spotlite")
    else:
        print(f"Erreur API: {error.get('message')}")

Pipeline enrichi — Bilan personnalité + Matching

Cas d'usage RH : enrichir chaque candidat avec un profil de personnalité passif avant le matching, sans questionnaire.

// Node.js — Pipeline : profil texte → bilan personnalité → matching
const SPOTLITE_API = 'https://europe-west6-spotlite-9da69.cloudfunctions.net';
const HEADERS = { 'X-API-Key': process.env.SPOTLITE_API_KEY, 'Content-Type': 'application/json' };

async function enrichAndMatch(candidate, jobDescription) {
  // 1. Bilan de personnalité passif depuis les textes du candidat
  const personality = await fetch(`${SPOTLITE_API}/apiAssessPassiveProfile`, {
    method: 'POST', headers: HEADERS,
    body: JSON.stringify({
      texts: candidate.writtenTexts,  // lettres de motivation, notes, journal...
      framework: 'big5',
      language: 'fr'
    })
  }).then(r => r.json());

  // 2. Matching CV ↔ poste (en parallèle si plusieurs candidats)
  const match = await fetch(`${SPOTLITE_API}/apiMatchCandidateToJob`, {
    method: 'POST', headers: HEADERS,
    body: JSON.stringify({
      candidateProfile: candidate.profile,
      jobDescription: jobDescription
    })
  }).then(r => r.json());

  // 3. Décision combinée : score technique + fit culturel
  const scores = personality.scores;
  const culturalFit = scores.conscientiousness > 65 && scores.openness > 60;

  return {
    candidateId: candidate.id,
    matchScore: match.matchScore,
    personality: {
      dominant: scores.dominant_trait,
      confidence: personality.confidence,
      insights: personality.insights,
    },
    culturalFit,
    shortlisted: match.matchScore >= 70 && culturalFit,
  };
}

# Python — Bilan passif depuis une liste de textes
import requests, os

API_BASE = "https://europe-west6-spotlite-9da69.cloudfunctions.net"
HEADERS = { "X-API-Key": os.environ["SPOTLITE_API_KEY"], "Content-Type": "application/json" }

def assess_personality(texts: list[dict], framework: str = "big5") -> dict:
    resp = requests.post(
        f"{API_BASE}/apiAssessPassiveProfile",
        headers=HEADERS,
        json={"texts": texts, "framework": framework, "language": "fr"},
        timeout=60
    )
    resp.raise_for_status()
    return resp.json()

# Exemple d'appel
texts = [
    {"date": "2025-11-03", "title": "Mission freelance", "content": "J'ai accepté cette mission data science..."},
    {"date": "2025-12-02", "title": "Sprint terminé",  "content": "J'ai refactorisé tout le preprocessing..."},
    {"date": "2026-01-08", "title": "Offre refusée",   "content": "J'ai refusé un poste 70% management..."},
]

result = assess_personality(texts, framework="big5")

# Résultat complet :
# result["scores"]["openness"]             → 85  (0-100)
# result["scores"]["conscientiousness"]    → 74
# result["scores"]["dominant_trait"]       → "openness"
# result["scores"]["description"]          → "Profil très ouvert..."
# result["insights"]                       → ["Exploration intellectuelle intense...", ...]
# result["career_implications"]            → ["Idéal pour rôles autonomes...", ...]
# result["confidence"]                     → 0.52  (6 entrées = confiance modérée)
print(f"Dominant trait: {result['scores']['dominant_trait']} — confidence: {result['confidence']}")
print(f"Insights: {result['insights']}")