Intégration de l'API Bypass Monitor

Particulièrement adapté à

Déroulé de l'intégration

Authentification

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

Créer une vérification

Crée une vérification de contournement asynchrone. TieTalent exécute une mise à jour de profil en interne, puis compare les employeurs découverts à votre liste de présentations.

Transmettez des submissions complètes avec leurs dates dès que vous en disposez ; l'analyse des dates repose sur submitted_at.

{
  "candidate": {
    "id": "cand-9911",
    "first_name": "Alex",
    "last_name": "Rivera",
    "email": "alex.rivera@example-corp.com",
    "employer_website": "example-corp.com",
    "role": "Software Engineer",
    "location": "London, UK",
    "profile_urls": [
      "https://linkedin.com/in/alex-rivera-example"
    ],
    "experience": [
      {
        "company": "Previous Corp",
        "role": "Engineer",
        "start_date": "2014-01",
        "end_date": "2016-01",
        "is_current": false
      }
    ],
    "submissions": [
      { "company": "Acme Client Ltd", "submitted_at": "2025-03" },
      { "company": "Beta Industries AG", "submitted_at": "2024-11" }
    ]
  }
}

Champs de la requête

candidate (objet requis)

Contient tous les champs d'identification de Talent Update, plus submissions, ainsi qu'experience sauf si vous fournissez profile_urls. Voir aussi les champs de requête de Talent Update.

Combinaison d'identification (au moins une)

submissions[] object

Champs facultatifs de premier niveau

Non accepté

Ni CV ni fichier. Uniquement des éléments d'identification et des données de présentation structurées.

Règles de validation

Les échecs de validation renvoient un 422 au format application/problem+json.

Précalcul des vérifications

Utilisez POST /api/v1/bypass-checks avec mode: "precompute" pour préparer les vérifications en arrière-plan, avant qu'un recruteur n'ouvre la fiche de présentation.

Précalcul par lot

Envoyez mode: "precompute" avec candidates au lieu de candidate. Chaque candidat doit comporter des submissions, ainsi qu'experience ou profile_urls.

{
  "mode": "precompute",
  "candidates": [
    {
      "id": "cand-9911",
      "first_name": "Alex",
      "last_name": "Rivera",
      "email": "alex.rivera@example-corp.com",
      "experience": [
        { "company": "Previous Corp", "is_current": false }
      ],
      "submissions": [
        { "company": "Acme Client Ltd", "submitted_at": "2025-03" }
      ]
    }
  ]
}

Le volume d'usage est mesuré par vos crédits de plan ; la vitesse à laquelle vous pouvez les dépenser est mesurée par la limite de requêtes par minute de votre forfait, partagée entre les appels live, les appels precompute et l'enrichissement CSV. Un dépassement de la limite de débit renvoie 429 Too Many Requests avec l'erreur rate-limit-exceeded et un Retry-After ; réessayez après ce délai. Voir Limites de débit pour les limites par forfait et les en-têtes de réponse.

Réponse à la création

Une création réussie renvoie 202 Accepted avec status: pending, ainsi que les objets additifs credits (solde restant et débit de cet appel) et plan (plan actuel). Ces champs sont non-breaking et ne nécessitent pas de changement de version. Le précalcul par lot renvoie un tableau items ainsi que credits / plan au niveau racine. Il n'y a pas de booléen cached au niveau racine (contrairement à Talent Update) ; credits.cached est présent et toujours false car les vérifications de contournement ne sont pas réutilisées.

Réponse pour un candidat

{
  "id": "bc_01JCXY",
  "status": "pending",
  "candidate_id": "cand-9911",
  "created_at": "2026-08-28T12:56:44.642Z",
  "credits": {
    "balance": 140,
    "plan_credits": 118,
    "rollover_credits": 22,
    "charged": 2,
    "cached": false
  },
  "plan": {
    "code": "growth",
    "cycle": "monthly",
    "credits_per_cycle": 200,
    "requests_per_minute": 300,
    "period_ends_at": "2026-10-28T12:00:00.000Z"
  }
}

Réponse au précalcul par lot

Chaque élément contient id, status: pending, candidate_id, created_at, ainsi que credits et plan par élément.

{
  "items": [
    {
      "id": "bc_01JCXY",
      "status": "pending",
      "candidate_id": "cand-9911",
      "created_at": "2026-08-28T12:56:44.642Z",
      "credits": {
        "balance": 138,
        "plan_credits": 116,
        "rollover_credits": 22,
        "charged": 2,
        "cached": false
      },
      "plan": {
        "code": "growth",
        "cycle": "monthly",
        "credits_per_cycle": 200,
        "requests_per_minute": 300,
        "period_ends_at": "2026-10-28T12:00:00.000Z"
      }
    },
    {
      "id": "bc_01JCXZ",
      "status": "pending",
      "candidate_id": "cand-9912",
      "created_at": "2026-08-28T12:56:45.102Z",
      "credits": {
        "balance": 138,
        "plan_credits": 116,
        "rollover_credits": 22,
        "charged": 1,
        "cached": false
      },
      "plan": {
        "code": "growth",
        "cycle": "monthly",
        "credits_per_cycle": 200,
        "requests_per_minute": 300,
        "period_ends_at": "2026-10-28T12:00:00.000Z"
      }
    }
  ],
  "credits": {
    "balance": 138,
    "plan_credits": 116,
    "rollover_credits": 22,
    "charged": 3,
    "cached": false
  },
  "plan": {
    "code": "growth",
    "cycle": "monthly",
    "credits_per_cycle": 200,
    "requests_per_minute": 300,
    "period_ends_at": "2026-10-28T12:00:00.000Z"
  }
}

credits.balance est le solde restant ; plan_credits et rollover_credits sont les compartiments de solde ; charged est le nombre de crédits réservés ou débités pour cette vérification (souvent proportionnel aux entreprises présentées uniques), ou null si non applicable sur GET ; credits.cached vaut toujours false pour les vérifications de contournement. plan inclut code (free, starter, growth ou custom), cycle (monthly, annual ou null), credits_per_cycle et period_ends_at. Ignorez ces champs s'ils ne vous sont pas utiles.

Récupérer une vérification

Appelez GET /api/v1/bypass-checks/{id} pour récupérer le résultat de la vérification.

Valeurs de status

Tant que status vaut pending

{
  "id": "bc_01JCXY",
  "status": "pending",
  "candidate_id": "cand-9911",
  "created_at": "2026-08-28T12:56:44.642Z",
  "completed_at": null,
  "bypass": {
    "detected": false,
    "note": null,
    "matches": []
  },
  "talent_update": null,
  "error": null,
  "credits": {
    "balance": 140,
    "plan_credits": 118,
    "rollover_credits": 22,
    "charged": 2,
    "cached": false
  },
  "plan": {
    "code": "growth",
    "cycle": "monthly",
    "credits_per_cycle": 200,
    "requests_per_minute": 300,
    "period_ends_at": "2026-10-28T12:00:00.000Z"
  }
}

Lorsque status vaut completed

{
  "id": "bc_01JCXY",
  "status": "completed",
  "candidate_id": "cand-9911",
  "created_at": "2026-08-28T12:56:44.642Z",
  "completed_at": "2026-08-28T12:58:12.441Z",
  "error": null,
  "bypass": {
    "detected": true,
    "note": "Confirmed: Alex Rivera was found working at Acme Client Limited, another name for Acme Client Ltd, the company the candidate was put forward to in March 2025, having joined in April 2025.",
    "matches": [
      {
        "submitted_company": "Acme Client Ltd",
        "found_company": "Acme Client Limited",
        "match_type": "variant",
        "submitted_at": "2025-03",
        "employment_start": "2025-04",
        "timing": "joined_after_submission",
        "confidence": "confirmed"
      }
    ]
  },
  "talent_update": {
    "identity": {
      "confidence": "high",
      "full_name": "Alex Rivera",
      "headline": "Software Engineer at Acme Client Limited",
      "current_employer": "Acme Client Limited",
      "location": "London, UK"
    },
    "work_experience": [
      {
        "company": "Acme Client Limited",
        "role": "Software Engineer",
        "start_date": "2025-04",
        "end_date": null,
        "is_current": true,
        "confidence": "high"
      }
    ],
    "education": [],
    "online_presence": []
  },
  "credits": {
    "balance": 140,
    "plan_credits": 118,
    "rollover_credits": 22,
    "charged": 2,
    "cached": false
  },
  "plan": {
    "code": "growth",
    "cycle": "monthly",
    "credits_per_cycle": 200,
    "requests_per_minute": 300,
    "period_ends_at": "2026-10-28T12:00:00.000Z"
  }
}

Champs de la réponse

La réponse contient toujours un objet bypass. Une fois la vérification terminée, un profil talent_update imbriqué peut également être présent. Les réponses GET incluent aussi les mêmes objets additifs credits et plan que la création.

timing compare le mois de présentation au mois de début d'emploi : joined_after_submission, already_employed, ou not_determinable lorsque les dates manquent. Si le candidat a rejoint l'entreprise correspondante plus d'un an avant votre présentation, la correspondance n'est pas signalée et bypass.note en explique la raison.

confidence indique le niveau de vérification nécessaire. confirmed : fortement corroboré, les noms d'entreprise concordent et la date de début est postérieure à votre soumission. likely : corroboré, mais la correspondance porte sur une société mère ou une filiale, ou l'identité était moins certaine. needs_review : corroboration plus faible, société sœur du même groupe que l'entreprise à laquelle vous avez soumis le profil, date d'emploi inexploitable, candidat déjà en poste avant votre soumission, ou identité moins fiable. Vérifiez vous-même un résultat needs_review avant d'agir.

Énumérations

Les énumérations peuvent accueillir de nouvelles valeurs au fil du temps.

Erreurs

Les réponses non 2xx utilisent application/problem+json (RFC 9457).

Exemple de réponse d'erreur

{
  "type": "https://intelligence.tietalent.com/errors/invalid-request",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Provide a corporate email, or first_name and last_name together with company, employer_website or profile_urls, or a personal email with company or employer_website, or employer_website with role."
}

Limites de débit et versionnage

Limites de débit

Votre forfait définit la vitesse à laquelle vous pouvez appeler l'API, en requêtes par minute : Free 10, Starter 60, Growth 300. Sur un forfait Custom, la limite est définie avec vous. Une unité correspond à une unité de travail : un lot en consomme une par candidat. Candidate Intelligence, Talent Update, Bypass Monitor et l'enrichissement CSV partagent cette même réserve. Les réponses réussies et les 429 contiennent RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset ; un 429 ajoute Retry-After (secondes). Appliquez un back-off exponentiel avec jitter. Voir Candidate Intelligence › Limites de débit pour la référence complète. Les crédits sont un contrôle distinct : ils mesurent combien vous pouvez consommer, pas à quelle vitesse.

Retry-After: 42

Versionnage

La version figure dans le chemin (/v1). Des champs supplémentaires (y compris credits et plan) peuvent apparaître sans changement de version.

Webhooks

Livraison au moins une fois. Vos gestionnaires doivent être idempotents sur l'id de l'événement. Considérez GET /api/v1/bypass-checks/{id} comme la source de vérité à tout moment.

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}", en HMAC-SHA256 avec votre secret whsec_.... Même schéma que pour Candidate Intelligence et Talent Update.

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

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

La charge utile contient result_url, bypass_check_id et candidate_id. Récupérez le résultat complet par un GET authentifié.

api_environment reprend le libellé de la clé d'API ayant authentifié l'exécution (Production, Staging ou Test).

{
  "id": "evt_01JDABC",
  "type": "bypass_check_ready",
  "created_at": "2026-08-28T12:58:12.441Z",
  "api_environment": "Production",
  "data": {
    "candidate_id": "cand-9911",
    "status": "completed",
    "result_url": "https://intelligence.tietalent.com/api/v1/bypass-checks/bc_01JCXY",
    "bypass_check_id": "bc_01JCXY"
  }
}

{
  "id": "evt_01JDABD",
  "type": "bypass_check_failed",
  "created_at": "2026-08-28T12:58:15.441Z",
  "api_environment": "Production",
  "data": {
    "candidate_id": "cand-9911",
    "status": "failed",
    "result_url": "https://intelligence.tietalent.com/api/v1/bypass-checks/bc_01JCXY",
    "bypass_check_id": "bc_01JCXY",
    "error_code": "internal_error"
  }
}

Limites connues

Connaître ces limites permet d'avoir les bonnes attentes.