Intégration API Role Fit

Idéal pour

Étapes d'intégration

Différences avec Candidate Intelligence

Role Fit partage l'authentification, l'objet client, language, eu_compliant, les crédits, les limites de débit, les webhooks et les retours avec Candidate Intelligence. Ce qui change :

• Chaque candidat est comparé à un job. Envoyez un poste pour toute la requête, ou un poste par candidat.
• Pas de report_type : Role Fit renvoie le même rapport sur tous les canaux.
• Les lots de 50 candidats au plus fonctionnent directement, sans champ mode. Chaque appel Role Fit s'exécute en arrière-plan.
• Idempotency-Key est pris en charge à la création.
• Le rapport est en snake_case et décrit dans quelle mesure les éléments du candidat couvrent les exigences du poste.
• Une exécution coûte 2 crédits par candidat ; un rapport réutilisé ne coûte rien.

Authentification

X-API-Key: ats_your_api_key_here
Content-Type: application/json
Idempotency-Key: 7b1c9e0a-5d2f-4c8e-9a61-0f3b2d8c4e17   (optional, recommended)

Créer un role fit

Crée un role fit asynchrone par candidat. La réponse arrive immédiatement ; le rapport est prêt en une minute environ.

{
  "language": "en",
  "eu_compliant": null,
  "force_refresh": false,
  "client": {
    "id": "client-42",
    "first_name": "Anna",
    "last_name": "Meier",
    "company": "Acme Recruiting"
  },
  "job": {
    "id": "job-481",
    "title": "Senior Backend Engineer",
    "description": "We are hiring a Senior Backend Engineer to own our payments platform: settlement, reconciliation and payouts. 5+ years of Go and PostgreSQL, Kafka in production, payments experience."
  },
  "candidate": {
    "id": "cand-1001",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "cv": "Ada Lovelace. Senior Backend Engineer, Globex AG (2019 to present): built the card settlement service in Go and PostgreSQL...",
    "company": "Globex AG",
    "role": "Senior Backend Engineer",
    "location": "Zurich, Switzerland"
  }
}

Champs de la requête

Champs de premier niveau

job

Chaque poste exige description ou url. Si les deux sont envoyés, description est utilisé.

candidate

id, first_name et last_name sont obligatoires. Le reste est facultatif ; cv compte le plus.

Lots et poste par candidat

Envoyez candidates au lieu de candidate pour comparer jusqu'à 50 candidats en une requête. Le job de premier niveau s'applique à tous ; un candidat qui porte son propre job utilise celui-ci. Cela couvre tous les candidats d'une réquisition, des postes différents, et un même candidat face à plusieurs postes (répétez le candidat avec un autre poste).

{
  "language": "en",
  "client": {
    "id": "client-42",
    "first_name": "Anna",
    "last_name": "Meier",
    "company": "Acme Recruiting"
  },
  "job": {
    "id": "job-481",
    "title": "Senior Backend Engineer",
    "description": "We are hiring a Senior Backend Engineer to own our payments platform..."
  },
  "candidates": [
    {
      "id": "cand-1001",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "cv": "Ada Lovelace. Senior Backend Engineer, Globex AG..."
    },
    {
      "id": "cand-1002",
      "first_name": "Alan",
      "last_name": "Turing",
      "cv": "Alan Turing. Staff Engineer, Hut 8...",
      "job": {
        "id": "job-502",
        "url": "https://careers.acme.example/jobs/502"
      }
    }
  ]
}

Règles des lots

• Toute la requête est validée avant tout démarrage. Si un candidat n'a pas de poste, ou si une page de poste est illisible, la requête échoue avec un pointeur vers chaque problème : rien n'est créé ni facturé.
• Les crédits de chaque nouvelle exécution sont réservés d'avance. Si votre solde ne suffit pas pour tout le lot, la requête renvoie 402 et rien n'est créé.
• Chaque candidat consomme une unité de votre limite de débit par minute.
• Les exécutions sont traitées quelques-unes à la fois par espace de travail. Les éléments restent en queued jusqu'à leur démarrage.
• Les items de la réponse suivent l'ordre de candidates.

Relances idempotentes

Envoyez un en-tête Idempotency-Key (toute chaîne unique de 255 caractères au plus, par exemple un UUID) pour relancer une création sans risque après un délai dépassé ou une erreur réseau.

• Une relance avec la même clé et le même corps renvoie la réponse d'origine avec l'en-tête Idempotent-Replayed: true. Aucune nouvelle exécution n'est créée et rien n'est facturé à nouveau.
• La même clé avec un corps différent renvoie 422 idempotency-key-reused.
• Une relance pendant le traitement de la première requête renvoie 409 idempotency-key-in-progress avec Retry-After.
• Les clés sont conservées 24 heures. Les réponses 429 et 5xx ne sont pas conservées : vous pouvez les relancer avec la même clé.

Réponse à la création

Une création réussie renvoie 202 Accepted. Un candidat seul renvoie un objet et un en-tête Location ; un lot renvoie items, un objet par candidat. Chaque objet porte ses propres credits ; les credits et plan de premier niveau décrivent toute la requête.

En-têtes de réponse

HTTP/1.1 202 Accepted
Location: https://intelligence.tietalent.com/api/v1/role-fits/cmv9r1f2a0000xk0k8m3c2q71
Retry-After: 10
RateLimit-Limit: 300
RateLimit-Remaining: 299
RateLimit-Reset: 60

Un seul candidat

{
  "id": "cmv9r1f2a0000xk0k8m3c2q71",
  "status": "queued",
  "candidate_id": "cand-1001",
  "job_id": "job-481",
  "created_at": "2026-11-03T10:00:00.000Z",
  "credits": {
    "balance": 412,
    "plan_credits": 400,
    "rollover_credits": 12,
    "charged": 2,
    "cached": false
  },
  "plan": {
    "code": "growth",
    "cycle": "monthly",
    "credits_per_cycle": 5000,
    "requests_per_minute": 300,
    "period_ends_at": "2026-11-30T23:59:59.000Z"
  }
}

Lot (le second candidat a réutilisé un rapport existant)

{
  "items": [
    {
      "id": "cmv9r1f2a0000xk0k8m3c2q71",
      "status": "queued",
      "candidate_id": "cand-1001",
      "job_id": "job-481",
      "created_at": "2026-11-03T10:00:00.000Z",
      "credits": { "balance": 412, "plan_credits": 400, "rollover_credits": 12, "charged": 2, "cached": false },
      "plan": { "code": "growth", "cycle": "monthly", "credits_per_cycle": 5000, "requests_per_minute": 300, "period_ends_at": "2026-11-30T23:59:59.000Z" }
    },
    {
      "id": "cmv9r1f2b0001xk0k4n7d9p02",
      "status": "completed",
      "candidate_id": "cand-1002",
      "job_id": "job-502",
      "created_at": "2026-11-03T10:00:00.000Z",
      "credits": { "balance": 412, "plan_credits": 400, "rollover_credits": 12, "charged": 0, "cached": true },
      "plan": { "code": "growth", "cycle": "monthly", "credits_per_cycle": 5000, "requests_per_minute": 300, "period_ends_at": "2026-11-30T23:59:59.000Z" }
    }
  ],
  "credits": {
    "balance": 412,
    "plan_credits": 400,
    "rollover_credits": 12,
    "charged": 2,
    "cached": false
  },
  "plan": {
    "code": "growth",
    "cycle": "monthly",
    "credits_per_cycle": 5000,
    "requests_per_minute": 300,
    "period_ends_at": "2026-11-30T23:59:59.000Z"
  }
}

credits.balance est votre solde restant ; charged ce que cette exécution a réservé ou facturé ; credits.cached vaut true quand un rapport a été réutilisé sans frais. plan décrit votre forfait actuel. Ces deux objets sont additionnels et peuvent être ignorés.

Lire un role fit

Appelez GET /api/v1/role-fits/{id} pour suivre l'avancement et lire le rapport. Tant que l'exécution est queued ou processing, la réponse porte un en-tête Retry-After.

Valeurs de status

Pendant l'exécution

{
  "id": "cmv9r1f2a0000xk0k8m3c2q71",
  "status": "processing",
  "candidate_id": "cand-1001",
  "job_id": "job-481",
  "created_at": "2026-11-03T10:00:00.000Z",
  "updated_at": "2026-11-03T10:00:14.000Z",
  "completed_at": null,
  "report": null,
  "metadata": null,
  "error": null,
  "credits": {
    "balance": 412,
    "plan_credits": 400,
    "rollover_credits": 12,
    "charged": 2,
    "cached": false
  },
  "plan": {
    "code": "growth",
    "cycle": "monthly",
    "credits_per_cycle": 5000,
    "requests_per_minute": 300,
    "period_ends_at": "2026-11-30T23:59:59.000Z"
  }
}

Exécution terminée (rapport Standard)

{
  "id": "cmv9r1f2a0000xk0k8m3c2q71",
  "status": "completed",
  "candidate_id": "cand-1001",
  "job_id": "job-481",
  "created_at": "2026-11-03T10:00:00.000Z",
  "updated_at": "2026-11-03T10:00:52.000Z",
  "completed_at": "2026-11-03T10:00:52.000Z",
  "report": {
    "candidate_name": "Ada Lovelace",
    "target_role": "Senior Backend Engineer",
    "match": { "score": 81, "level": "good_fit" },
    "recommendation": {
      "decision": "Go with validation",
      "reasoning": "Five years of payments backend work in Go covers the core requirements; Kafka in production is not shown in the CV."
    },
    "summary": "Strong overlap on Go, PostgreSQL and the payments domain. Kafka experience and team leadership could not be verified.",
    "alignment": {
      "strong_matches": ["5 years building payment services in Go and PostgreSQL"],
      "partial_matches": ["Event streaming with RabbitMQ; the role uses Kafka"],
      "gaps": ["No team leadership shown; the role leads three engineers"]
    },
    "seniority": {
      "candidate_level": "Senior",
      "role_level": "Senior",
      "gap_analysis": "Scope and ownership match the senior level the role asks for."
    },
    "experience": {
      "relevant": ["PCI-DSS compliant service design"],
      "not_shown_in_cv": ["Kafka in production"],
      "transferable": ["RabbitMQ event-driven design"]
    },
    "points_to_validate": ["Depth of on-call ownership for the settlement service"],
    "additional_strengths": ["Led a card-tokenisation migration that reduced PCI scope"],
    "open_questions": ["Notice period and current team size"],
    "external_validation": {
      "verified_insights": [],
      "no_data_flags": ["No public code repository found"],
      "impact_on_fit": "No external data changes the picture from the CV."
    },
    "interview_focus": ["Walk us through how you scaled the settlement service."]
  },
  "metadata": {
    "language": "en",
    "eu_compliant": false,
    "cv_provided": true,
    "job_source": "description",
    "generated_at": "2026-11-03T10:00:52.000Z",
    "cached": false,
    "cached_at": null,
    "pdf_download_url": "https://intelligence.tietalent.com/api/ats/reports/cmv9r1f2a0000xk0k8m3c2q71/pdf?t=atsl_...",
    "pdf_download_url_expires_at": "2026-11-04T10:00:52.000Z"
  },
  "error": null,
  "credits": {
    "balance": 412,
    "plan_credits": 400,
    "rollover_credits": 12,
    "charged": 2,
    "cached": false
  },
  "plan": {
    "code": "growth",
    "cycle": "monthly",
    "credits_per_cycle": 5000,
    "requests_per_minute": 300,
    "period_ends_at": "2026-11-30T23:59:59.000Z"
  }
}

Exécution en échec

{
  "id": "cmv9r1f2a0000xk0k8m3c2q71",
  "status": "failed",
  "candidate_id": "cand-1001",
  "job_id": "job-481",
  "report": null,
  "metadata": null,
  "error": {
    "type": "https://intelligence.tietalent.com/errors/internal-error",
    "title": "Role fit failed",
    "status": 500,
    "detail": "The role fit could not be completed. No credits were charged."
  },
  ...
}

metadata.pdf_download_url ouvre le rapport hébergé, d'où le PDF peut être téléchargé. Toute personne disposant du lien peut ouvrir le rapport jusqu'à son expiration, 24 heures après son émission (pdf_download_url_expires_at). Ne conservez pas le lien : conservez l'id du role fit et appelez GET quand un recruteur ouvre le rapport pour obtenir un lien valide.

Champs de la réponse

Tous les champs sont toujours présents. Les listes peuvent être vides ; report et metadata valent null tant que l'exécution n'est pas terminée.

report

metadata

Conforme UE ou Standard

Role Fit évalue des candidats pour un poste, un usage que l'AI Act européen classe à haut risque et qui exige une supervision humaine. Les deux modes servent uniquement d'aide à la décision : le recruteur décide. Les rapports conformes UE vont plus loin pour ne jamais présenter le résultat comme un jugement sur la personne :

"report": {
  "candidate_name": "Ada Lovelace",
  "target_role": "Senior Backend Engineer",
  "match": null,
  "recommendation": {
    "decision": "Go with validation",
    "reasoning": "The CV evidences the Go, PostgreSQL and payments requirements; Kafka in production is not evidenced."
  },
  ...
},
"metadata": {
  "eu_compliant": true,
  ...
}

Libellés d'affichage suggérés pour recommendation.decision sur les rapports conformes UE :

// Suggested display labels for EU-compliant reports
const EU_LABELS = {
  "Proceed with confidence": "Requirements well evidenced",
  "Go with validation": "Some points to validate",
  "Requires Validation (Signals flagged)": "Conflicting evidence to review",
  "Requires Validation (Insufficient data)": "Not enough information",
};

Réutilisation des rapports

Un rapport est réutilisé gratuitement quand votre espace en possède déjà un pour les mêmes données.

• La correspondance porte sur le texte du CV (ou, sans CV, les informations du candidat), le texte du poste, le mode de conformité et la langue. Les rapports sont réutilisés pendant six mois.
• Une exécution réutilisée est completed dès sa création, avec credits.charged: 0 et metadata.cached: true.
• Chaque requête reçoit tout de même son propre id, avec votre candidate_id et votre job_id.
• force_refresh: true génère toujours un nouveau rapport.

Annuler un role fit

DELETE /api/v1/role-fits/{id} arrête une exécution queued ou processing et rembourse ses crédits. La réponse renvoie le role fit avec status: canceled. Une exécution déjà terminée est renvoyée inchangée.

200 OK : la ressource role fit, avec "status": "canceled"

Retour

Envoyez l'évaluation d'un recruteur sur un rapport terminé (1 à 5, avec texte et tags facultatifs). Un nouvel envoi pour le même client.id et le même role fit met le retour à jour. Même contrat que les retours Candidate Intelligence.

{
  "client": {
    "id": "client-42",
    "first_name": "Anna",
    "last_name": "Meier",
    "company": "Acme Recruiting"
  },
  "rating": 4,
  "feedback": "Spot on for seniority.",
  "tags": []
}

{
  "role_fit_id": "cmv9r1f2a0000xk0k8m3c2q71",
  "rating": 4,
  "feedback": "Spot on for seniority.",
  "tags": [],
  "updated_at": "2026-11-03T10:05:00.000Z"
}

Énumérations

Toute énumération peut recevoir de nouvelles valeurs. Traitez une valeur inconnue comme sa voisine la plus prudente, pas comme une erreur.

Erreurs

Les réponses non 2xx utilisent application/problem+json (RFC 9457). Basez-vous sur status et sur la dernière partie de type. Les erreurs de validation ajoutent un tableau errors avec un pointeur JSON vers chaque problème.

Exemple : un candidat sans poste

{
  "type": "https://intelligence.tietalent.com/errors/invalid-body",
  "title": "Invalid request body",
  "status": 400,
  "detail": "Provide job, or a job on this candidate.",
  "errors": [
    { "pointer": "/candidates/1/job", "detail": "Provide job, or a job on this candidate." }
  ]
}

Exemple : une page de poste illisible

{
  "type": "https://intelligence.tietalent.com/errors/invalid-job",
  "title": "Invalid job",
  "status": 422,
  "detail": "A job page could not be read. Send the job description as text, or a public https link that does not need a login.",
  "errors": [
    { "pointer": "/candidates/1/job/url", "code": "job_unreadable" }
  ]
}

Limites de débit et versions

Limites de débit

Votre forfait fixe le débit d'appels autorisé, en requêtes par minute : Free 10, Starter 60, Growth 300 ; les forfaits Custom sont définis avec vous. Un lot consomme une unité par candidat, et toutes les API TieTalent partagent la même enveloppe. Les réponses portent RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset ; une 429 ajoute Retry-After en secondes. Les crédits sont distincts : ils mesurent ce que vous consommez, pas à quelle vitesse.

Retry-After: 42

Versions

La version figure dans le chemin (/v1). De nouveaux champs de réponse et de nouvelles valeurs d'énumération peuvent apparaître sans changement de version.

Webhooks

Au lieu d'interroger l'API, recevez une notification signée quand un role fit se termine. La livraison est au moins une fois : dédupliquez sur l'id de l'événement. GET /api/v1/role-fits/{id} reste la source de vérité.

Types d'événements

Vérification de la signature

Chaque livraison porte un en-tête X-CI-Signature : t=<unix>,v1=<hmac-sha256> calculé sur "{t}.{raw_body}" avec votre secret whsec_.... Vérifiez-la et rejetez les horodatages de plus de cinq minutes.

X-CI-Signature: t=<unix>,v1=<hmac-sha256>

# Signed over "{t}.{raw_body}". Reject timestamps older than five minutes.

Le contenu n'est qu'un pointeur : role_fit_id, candidate_id, job_id et result_url. Aucun contenu de rapport ni donnée personnelle ne transite par le webhook ; récupérez le rapport par un GET authentifié.

{
  "id": "evt_01JDABC",
  "type": "role_fit_ready",
  "created_at": "2026-11-03T10:00:52.000Z",
  "api_environment": "Production",
  "data": {
    "candidate_id": "cand-1001",
    "status": "completed",
    "result_url": "https://intelligence.tietalent.com/api/v1/role-fits/cmv9r1f2a0000xk0k8m3c2q71",
    "role_fit_id": "cmv9r1f2a0000xk0k8m3c2q71",
    "job_id": "job-481"
  }
}

{
  "id": "evt_01JDABD",
  "type": "role_fit_failed",
  "created_at": "2026-11-03T10:01:30.000Z",
  "api_environment": "Production",
  "data": {
    "candidate_id": "cand-1001",
    "status": "failed",
    "result_url": "https://intelligence.tietalent.com/api/v1/role-fits/cmv9r1f2a0000xk0k8m3c2q71",
    "role_fit_id": "cmv9r1f2a0000xk0k8m3c2q71",
    "job_id": "job-481",
    "error_code": "internal_error"
  }
}

Limites connues

Les publier ouvertement est ce qui rend le reste de la documentation fiable.