Intégration de l'API Candidate Intelligence

Idéal pour

Avantages partenaire

Pourquoi intégrer Candidate Intelligence ?

Offrez à vos clients un contexte supplémentaire avant les entretiens tout en créant de la valeur au sein de votre plateforme.

Parcours d'intégration

Performances et latence

Candidate Intelligence est conçu pour offrir une expérience réactive directement dans les flux de travail des recruteurs.

Logique de réutilisation des rapports

Les rapports sont identifiés de façon unique par plateforme + entreprise + candidat.

Le cache est limité par recruteur : votre clé API identifie l'intégration partenaire, et client.id identifie le recruteur (utilisateur) au sein de votre plateforme. Des client.id différents ne partagent pas le cache, même avec la même clé API.

Champs de la clé de cache

Hors clé de cache

Les rapports en cache sont réutilisés pendant 6 mois. Les analyses terminées plus anciennes ne sont pas renvoyées depuis le cache.

Forcer l'actualisation

Définissez force_refresh: true sur POST /api/v1/analyses pour ignorer le cache et exécuter le pipeline complet — enrichissement, signaux en direct et génération du rapport LLM.

Omettez force_refresh ou définissez-le à false pour autoriser la réutilisation du cache (par défaut).

Quand définir force_refresh: true

{
  "language": "en",
  "client": {
    "id": "client_company_123",
    "first_name": "Jane",
    "last_name": "Smith",
    "company": "Acme Recruiting"
  },
  "candidate": {
    "id": "candidate_456",
    "first_name": "John",
    "last_name": "Doe",
    "company": "Example Company",
    "location": "London, UK",
    "role": "Software Engineer"
  },
  "force_refresh": true
}

Authentification

X-API-Key: ats_your_api_key_here
Content-Type: application/json

Créer une analyse

Champs optionnels du corps : candidate.cv (CV en texte brut, utilisé uniquement lors d'exécutions fraîches) et force_refresh (booléen, false par défaut — voir Forcer l'actualisation).

{
  "language": "en",
  "client": {
    "id": "client_company_123",
    "first_name": "Jane",
    "last_name": "Smith",
    "company": "Acme Recruiting"
  },
  "candidate": {
    "id": "candidate_456",
    "first_name": "John",
    "last_name": "Doe",
    "company": "Example Company",
    "location": "London, UK",
    "role": "Software Engineer",
    "cv": "Optional plain-text CV content…"
  },
  "force_refresh": false
}

force_refresh (optionnel, false par défaut) ignore la réutilisation des rapports et génère toujours un nouveau rapport — le nouveau rapport est facturé. Omettez-le sauf si le recruteur demande explicitement une actualisation.

202 Accepted

L'en-tête Location pointe vers GET /api/v1/analyses/'{'id'}'. Retry-After: 10 indique quand effectuer le prochain polling.

{
  "id": "cmqp23kgg00067gk0rh6jol5o",
  "status": "queued",
  "candidate_id": "candidate_456",
  "created_at": "2026-06-29T12:00:00.000Z"
}

Polling et résultats progressifs

Après un POST renvoyant 202 Accepted, interrogez GET /api/v1/analyses/'{'id'}' avec le même en-tête X-API-Key. Utilisez l'id de la réponse de création.

Tant que le statut est queued ou processing, chaque réponse GET inclut Retry-After: 10 — attendez au moins 10 secondes avant la requête suivante.

Arrêtez le polling lorsque le statut est completed, failed ou canceled.

{
  "id": "cmqp23kgg00067gk0rh6jol5o",
  "status": "processing",
  "candidate_id": "candidate_456",
  "stage": "enrichment",
  "created_at": "2026-06-29T12:00:00.000Z",
  "updated_at": "2026-06-29T12:00:20.000Z",
  "quick_signal": {
    "level": "Green",
    "reason": "Identity supported by multiple matching signals.",
    "identityConfidence": "Medium"
  },
  "signals": [
    {
      "statement": "Senior engineer at Example Company since 2021.",
      "sourceType": "web",
      "sourceUrl": "https://example.com/…",
      "reliability": "High"
    }
  ],
  "report": null,
  "metadata": null,
  "error": null
}

Champs renseignés pendant le traitement

Valeurs de statut

Annuler une analyse

DELETE /api/v1/analyses/'{'id'}' arrête une analyse en file d'attente ou en cours lorsqu'un recruteur quitte le profil candidat ou ferme un rapport en génération. Utilisez le même en-tête X-API-Key que pour POST et GET.

Si l'analyse est déjà completed, failed ou canceled, l'endpoint renvoie la ressource actuelle sans modification — aucun frais supplémentaire ni effet de bord.

// Aucun corps de requête — en-tête X-API-Key uniquement

200 OK

Renvoie la ressource d'analyse avec le statut canceled. Des quick_signal ou signals partiels peuvent être présents si l'annulation a eu lieu en cours de pipeline. Arrêtez le polling dès que le statut est canceled.

{
  "id": "cmqp23kgg00067gk0rh6jol5o",
  "status": "canceled",
  "candidate_id": "candidate_456",
  "stage": "enrichment",
  "created_at": "2026-06-29T12:00:00.000Z",
  "updated_at": "2026-06-29T12:00:25.000Z",
  "quick_signal": null,
  "signals": [],
  "report": null,
  "metadata": null,
  "error": null
}

Analyse terminée

Retournée lorsque le statut est completed. Le rapport ci-dessous est abrégé — consultez la Référence de l'objet rapport pour la liste complète des champs.

Rapport frais (metadata.cached: false)

{
  "id": "clx_analysis_id",
  "status": "completed",
  "candidate_id": "candidate_456",
  "stage": "done",
  "created_at": "2026-06-29T12:00:00.000Z",
  "updated_at": "2026-06-29T12:00:45.000Z",
  "quick_signal": {
    "level": "Green",
    "reason": "Identity supported by multiple matching signals.",
    "identityConfidence": "Medium"
  },
  "signals": [
    {
      "statement": "…",
      "sourceType": "web",
      "sourceUrl": "https://example.com/…",
      "reliability": "High"
    }
  ],
  "report": {
    "candidateName": "John Doe",
    "profileHeadline": "Software Engineer",
    "profileCompany": "Example Company",
    "profileLocation": "London, UK",
    "identity": {
      "status": "Confirmed",
      "confidence": "High",
      "confidenceReason": "…",
      "risk": { "level": "Low", "reason": "…" }
    },
    "sourcesCheckedCount": 24,
    "recommendation": {
      "decision": "Go with validation",
      "confidence": "Medium",
      "confidenceNote": "Identity verified · signals consistent",
      "reason": "…",
      "evidence": ["…"],
      "nextStepPills": [
        { "variant": "confirmed", "label": "Role and tenure verified" },
        { "variant": "validate", "label": "Validate team leadership scope" }
      ]
    },
    "summary": "…",
    "externalProfileSummary": "…",
    "externalProfileTags": [
      { "kind": "catalog", "id": "linkedin_verified" },
      { "kind": "catalog", "id": "signals_highly_consistent" },
      { "kind": "custom", "group": "source_presence", "label": "Open-source contributor" }
    ],
    "strengths": ["…"],
    "signals": {
      "verified": [
        {
          "statement": "…",
          "sourceType": "web",
          "sourceReference": "…",
          "reliability": "High"
        }
      ],
      "weak": [],
      "unverifiedClaims": [],
      "noSignificantExternalData": false
    },
    "highImpactFindings": [
      {
        "type": "Career",
        "title": "…",
        "summary": "…",
        "evidenceBadge": "validate",
        "confidence": "Medium",
        "polarity": "Concern"
      }
    ],
    "topDecisionDrivers": ["…"],
    "expectationGap": {
      "expectedSignals": ["…"],
      "missingOrWeaker": ["…"],
      "assessment": "…"
    },
    "impactAssessment": {
      "summary": "…",
      "riskLevel": "Low",
      "overallRiskLabel": "Low validation needed",
      "implications": ["…"]
    },
    "whatToValidate": ["…"],
    "nextStep": {
      "action": "…",
      "focusAreas": ["…"],
      "reasoning": "…"
    },
    "alertLevel": "Green",
    "externalDataConfidence": "Medium"
  },
  "metadata": {
    "report_id": "clx_analysis_id",
    "candidate_id": "candidate_456",
    "language": "en",
    "generated_at": "2026-06-29T12:00:45.000Z",
    "pdf_download_url": "https://intelligence.tietalent.com/api/ats/reports/{id}/pdf?sig=…",
    "cached": false,
    "cached_at": null
  },
  "error": null
}

Rapport en cache (metadata.cached: true)

{
  "id": "clx_new_analysis_id",
  "status": "completed",
  "candidate_id": "candidate_456",
  "stage": "done",
  "created_at": "2026-07-15T12:00:00.000Z",
  "updated_at": "2026-07-15T12:00:00.500Z",
  "quick_signal": { "…": "…" },
  "signals": [{ "…": "…" }],
  "report": { "…": "…" },
  "metadata": {
    "report_id": "clx_new_analysis_id",
    "candidate_id": "candidate_456",
    "language": "en",
    "generated_at": "2026-07-15T12:00:00.500Z",
    "pdf_download_url": "https://intelligence.tietalent.com/api/ats/reports/{id}/pdf?sig=…",
    "cached": true,
    "cached_at": "2026-07-15T12:00:00.500Z"
  },
  "error": null
}

L'objet metadata

metadata.pdf_download_url est un lien signé qui ouvre le rapport TieTalent hébergé complet (le même design de rapport que l'application web) ; l'export PDF est téléchargeable depuis cette vue. Traitez ce lien comme confidentiel — toute personne qui le détient peut ouvrir le rapport.

metadata.cached vaut true lorsqu'un rapport existant a été réutilisé au lieu d'en générer un nouveau (voir la Logique de réutilisation des rapports) ; cached_at porte alors l'horodatage de la réutilisation, sinon il vaut null.

Verdicts et compatibilité

report.recommendation.decision est le verdict principal du rapport. Il s'agit toujours de l'une des quatre valeurs ci-dessous.

"Proceed with confidence"
"Go with validation"
"Requires Validation (Signals flagged)"
"Requires Validation (Insufficient data)"

Associez chaque verdict à l'un des trois états d'interface :

function toUiState(decision) {
  switch (decision) {
    case "Proceed with confidence":
      return "proceed";
    case "Go with validation":
      return "validation";
    case "Requires Validation (Signals flagged)":
    case "Requires Validation (Insufficient data)":
      return "requires_validation";
    default:
      return "requires_validation";
  }
}

Référence de l'objet rapport

report n'est renseigné que lorsque le statut est completed. Les noms de champs sont en camelCase. La structure reflète le design de rapport actuel utilisé sur toutes les surfaces TieTalent Intelligence (application web, extension et rapport hébergé).

Champs principaux (toujours présents)

Champs optionnels

Ces champs peuvent être absents. Traitez-les comme nullables et ignorez tout champ que votre interface n'utilise pas.

Envoyer un avis sur un rapport

POST /api/v1/analyses/'{'id'}'/feedback permet à vos recruteurs de noter un rapport terminé — de 1 à 5 étoiles, avec des tags optionnels et un texte libre optionnel — afin que TieTalent puisse suivre la qualité des rapports de votre côté de l'intégration.

L'endpoint effectue un upsert sur client.id et l'id du rapport : envoyer à nouveau une requête pour le même client et le même rapport écrase la note, les tags et le texte précédents — il n'y a pas d'historique des révisions.

{
  "client": {
    "id": "client_company_123",
    "first_name": "Jane",
    "last_name": "Smith",
    "company": "Acme Recruiting"
  },
  "rating": 4,
  "feedback": "Helped me shortlist quickly, would have liked more sourcing links.",
  "tags": ["saved_me_time", "good_signal_quality"]
}

Champs de la requête

Catalogue des tags de feedback

Les tags sont regroupés par tranche de note et changent selon la note envoyée — construisez votre propre interface, mais n'envoyez que les identifiants canoniques afin que les avis restent analysables entre les langues.

// 1-2 stars
missing_info · something_was_wrong · signals_felt_weak
too_generic · hard_to_trust

// 3 stars
useful_but_missing_detail · right_idea_wrong_emphasis
some_signals_felt_off · wanted_more_sources

// 4-5 stars
saved_me_time · helped_me_decide · good_signal_quality
easy_to_read · trustworthy

200 OK

Renvoie l'avis enregistré, avec la note, les tags et le texte actuellement en base pour ce client et ce rapport.

{
  "report_id": "cmqp23kgg00067gk0rh6jol5o",
  "rating": 4,
  "feedback": "Helped me shortlist quickly, would have liked more sourcing links.",
  "tags": ["saved_me_time", "good_signal_quality"],
  "updated_at": "2026-07-21T12:00:00.000Z"
}

Interface partenaire recommandée

Ajouter un bouton dans les profils candidats

Ajoutez un bouton « Lancer le rapport Candidate Intelligence » dans les profils candidats. Au clic, il devient « Génération du rapport en cours... » pendant la génération. Une fois prêt, le rapport s'ouvre automatiquement et le bouton devient « ✕ Fermer le rapport ». À la fermeture, il repasse à « Voir le rapport Intelligence » pour rouvrir un rapport déjà enregistré — sans rappeler POST.

Confidentialité et sécurité