Bypass Monitor API-Integration

Besonders geeignet für

Ablauf der Integration

Authentifizierung

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

Prüfung erstellen

Erstellt eine asynchrone Bypass-Prüfung. TieTalent führt intern ein Talent Update aus und vergleicht anschließend die gefundenen Arbeitgeber mit Ihrer Vorstellungsliste.

Senden Sie vollständige submissions mit Vorstellungsdaten, wann immer Sie sie haben; die zeitliche Einordnung beruht auf 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" }
    ]
  }
}

Felder der Anfrage

candidate (erforderliches Objekt)

Enthält alle Identitätsfelder von Talent Update sowie submissions und experience, sofern Sie keine profile_urls übermitteln. Siehe auch die Anfragefelder von Talent Update.

Identitätskombination (mindestens eine)

submissions[] object

Optionale Felder auf oberster Ebene

Nicht akzeptiert

Kein Lebenslauf, kein Datei-Upload. Nur Identitätsmerkmale und strukturierte Angaben zur Vorstellung.

Feldregeln

Fehlgeschlagene Validierungen geben 422 mit application/problem+json zurück.

Prüfungen vorberechnen

Verwenden Sie POST /api/v1/bypass-checks mit mode: "precompute", um Prüfungen im Hintergrund vorzubereiten, bevor eine Recruiterin oder ein Recruiter den Vorstellungsdatensatz öffnet.

Vorberechnung im Stapel

Senden Sie mode: "precompute" mit candidates statt candidate. Jede Person muss submissions enthalten sowie entweder experience oder 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" }
      ]
    }
  ]
}

Das Nutzungsvolumen wird über Ihre Plan-Credits gemessen; wie schnell Sie sie ausgeben dürfen, über das Anfragen-pro-Minute-Limit Ihres Tarifs, das Live-Aufrufe, Precompute-Aufrufe und die CSV-Anreicherung gemeinsam nutzen. Ein Überschreiten des Ratenlimits liefert 429 Too Many Requests mit dem Fehler rate-limit-exceeded und einem Retry-After; versuchen Sie es danach erneut. Die Limits pro Tarif und die Antwort-Header finden Sie unter Ratenlimits.

Antwort auf die Erstellung

Eine erfolgreiche Erstellung gibt 202 Accepted mit status: pending zurück, plus die additiven Objekte credits (Restguthaben und Belastung für diesen Aufruf) und plan (aktueller Plan). Diese Felder sind nicht-breaking und erfordern keinen Versionswechsel. Die Stapelvorberechnung gibt ein items-Array sowie Top-Level-credits / plan zurück. Es gibt kein Top-Level-Boolean cached (anders als bei Talent Update); credits.cached ist vorhanden und immer false, weil Bypass-Prüfungen nicht wiederverwendet werden.

Antwort für eine Person

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

Antwort auf die Vorberechnung im Stapel

Jeder Eintrag enthält id, status: pending, candidate_id, created_at sowie credits und plan pro Eintrag.

{
  "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 ist das Restguthaben; plan_credits und rollover_credits sind die Guthaben-Buckets; charged sind für diese Prüfung reservierte oder belastete Credits (oft skaliert nach eindeutigen vorgestellten Unternehmen), oder null wenn bei GET nicht anwendbar; credits.cached ist bei Bypass-Prüfungen immer false. plan enthält code (free, starter, growth oder custom), cycle (monthly, annual oder null), credits_per_cycle und period_ends_at. Ignorieren Sie diese Felder, wenn ungenutzt.

Prüfung abrufen

Rufen Sie GET /api/v1/bypass-checks/{id} auf, um das Ergebnis der Prüfung abzuholen.

Werte von status

Solange status pending ist

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

Wenn status completed ist

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

Felder der Antwort

Die Antwort enthält immer ein bypass-Objekt. Nach Abschluss kann zusätzlich ein verschachteltes talent_update-Profil enthalten sein. GET-Antworten enthalten außerdem dieselben additiven Objekte credits und plan wie Create.

timing vergleicht den Monat der Vorstellung mit dem Monat des Beschäftigungsbeginns: joined_after_submission, already_employed oder not_determinable, wenn Datumsangaben fehlen. Hat die Person beim gefundenen Unternehmen mehr als ein Jahr vor Ihrer Vorstellung begonnen, wird die Übereinstimmung nicht gemeldet und bypass.note erklärt den Grund.

confidence zeigt, wie viel Prüfung ein Treffer benötigt. confirmed: gut belegt, die Firmennamen stimmen überein und das Startdatum liegt nach Ihrer Übermittlung. likely: belegt, aber der Treffer betrifft eine Mutter- oder Tochtergesellschaft, oder die Identität war weniger eindeutig. needs_review: schwächere Belege, eine Schwestergesellschaft im selben Konzern wie das Unternehmen, bei dem Sie eingereicht haben, kein verwertbares Beschäftigungsdatum, der Kandidat war vor Ihrer Übermittlung bereits dort tätig, oder geringere Identitätssicherheit. Prüfen Sie einen needs_review-Treffer selbst, bevor Sie handeln.

Aufzählungen

Aufzählungen können mit der Zeit neue Werte erhalten.

Fehler

Antworten außerhalb von 2xx verwenden application/problem+json (RFC 9457).

Beispiel einer Fehlerantwort

{
  "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."
}

Ratenbegrenzung und Versionierung

Ratenbegrenzung

Ihr Tarif legt fest, wie schnell Sie die API aufrufen dürfen, in Anfragen pro Minute: Free 10, Starter 60, Growth 300. Bei einem Custom-Tarif wird das Limit mit Ihnen vereinbart. Eine Einheit ist eine Arbeitseinheit, ein Batch verbraucht also eine pro Kandidat. Candidate Intelligence, Talent Update, Bypass Monitor und die CSV-Anreicherung teilen sich dieses eine Kontingent. Erfolgreiche Antworten und 429-Antworten enthalten RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset; ein 429 ergänzt Retry-After (Sekunden). Stufen Sie exponentiell mit Jitter zurück. Die vollständige Referenz finden Sie unter Candidate Intelligence › Ratenlimits. Credits sind ein getrennter Kontrollmechanismus: Sie messen, wie viel Sie verbrauchen dürfen, nicht wie schnell.

Retry-After: 42

Versionierung

Die Version steht im Pfad (/v1). Zusätzliche Felder (einschließlich credits und plan) können ohne Versionswechsel hinzukommen.

Webhooks

Zustellung mindestens einmal. Handler müssen bezogen auf die Ereignis-id idempotent sein. Betrachten Sie GET /api/v1/bypass-checks/{id} jederzeit als maßgeblich.

Ereignistypen

Signatur prüfen

Jede Zustellung trägt einen X-CI-Signature-Header: t=<unix>,v1=<hmac-sha256> über "{t}.{raw_body}", HMAC-SHA256 mit Ihrem whsec_...-Geheimnis. Gleiches Verfahren wie bei Candidate Intelligence und Talent Update.

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

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

Die Nutzlast enthält result_url, bypass_check_id und candidate_id. Holen Sie das vollständige Ergebnis über einen authentifizierten GET-Aufruf.

api_environment entspricht der Bezeichnung des API-Schlüssels, mit dem der Lauf authentifiziert wurde (Production, Staging oder 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"
  }
}

Bekannte Grenzen

Diese Grenzen zu kennen sorgt für die richtigen Erwartungen.