Talent Update API-Integration

Besonders geeignet für

Ablauf der Integration

Im Vergleich zu Candidate Intelligence

Talent Update nutzt dieselbe Authentifizierung, dieselben Webhooks und dieselben Vorberechnungsgrenzen wie Candidate Intelligence, verfolgt aber ein anderes Ziel: strukturierte Profilanreicherung statt eines von einem Modell verfassten Einstellungsberichts.

• Kein client-Objekt: nur candidate (oder candidates für die Vorberechnung im Stapel).
• Keine Felder language, cv, report_type oder eu_compliant.
• Kein Endpunkt zum Abbrechen. Läufe sind kurze Profilabfragen, keine langen SSE-Analysen.
• Die Antwort besteht aus strukturierten Feldern (identity, work_experience usw.), nicht aus einem report-Objekt oder einem PDF.
• Derselbe X-API-Key-Header und dieselbe Webhook-Signatur X-CI-Signature wie bei Candidate Intelligence.

Authentifizierung

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

Update erstellen

Erstellt einen asynchronen Talent-Update-Lauf. Der Anfragetext akzeptiert ausschließlich Identitätsmerkmale: keinen Lebenslauf, kein Freitextdokument, keinen Datei-Upload.

Optionale Felder wie profile_urls und experience erhöhen die Treffgenauigkeit. Senden Sie Profil-URLs, wann immer Sie sie haben.

{
  "candidate": {
    "id": "cand-9911",
    "first_name": "Alex",
    "last_name": "Rivera",
    "email": "alex.rivera@example-corp.com",
    "employer_website": "example-corp.com",
    "company": "Example Corp",
    "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"
      }
    ]
  }
}

Felder der Anfrage

candidate (erforderliches Objekt)

candidate.id ist immer erforderlich. Zusätzlich muss mindestens eine der folgenden Identitätskombinationen erfüllt sein.

Erforderliche Kombination (mindestens eine)

Optionale Felder auf oberster Ebene

Nicht akzeptiert

Kein Lebenslauf, kein Freitextdokument, kein Datei-Upload an diesem Endpunkt.

Feldregeln

Fehlgeschlagene Validierungen geben 422 im Format RFC 9457 application/problem+json zurück. Verzweigen Sie über status und detail; werten Sie im Produktivbetrieb keinen freien Fehlertext aus.

Updates vorberechnen

Verwenden Sie denselben Endpunkt POST /api/v1/talent-updates mit mode: "precompute". Abfrage und Abruf erfolgen über dasselbe GET /api/v1/talent-updates/{id} wie bei Live-Läufen.

Vorberechnung für eine Person

Senden Sie mode: "precompute" mit einem einzelnen candidate-Objekt.

{
  "mode": "precompute",
  "force_refresh": false,
  "candidate": {
    "id": "cand-9911",
    "first_name": "Alex",
    "last_name": "Rivera",
    "email": "alex.rivera@example-corp.com",
    "employer_website": "example-corp.com"
  }
}

Vorberechnung im Stapel

Senden Sie mode: "precompute" mit candidates (Array) statt candidate. Genau eines von candidate oder candidates angeben. Maximal 50 Kandidaten pro Anfrage. Jeder Kandidat verbraucht eine Einheit Ihres Minuten-Ratenlimits, ein Batch mit 20 Kandidaten also 20.

{
  "mode": "precompute",
  "candidates": [
    {
      "id": "cand-9911",
      "first_name": "Alex",
      "last_name": "Rivera",
      "email": "alex.rivera@example-corp.com"
    },
    {
      "id": "cand-9912",
      "first_name": "Jordan",
      "last_name": "Lee",
      "employer_website": "acme.example",
      "role": "Product Manager"
    }
  ]
}

Verhalten des Caches

• Abgeschlossene Läufe für denselben Partner und denselben Personen-Fingerabdruck können sieben Tage lang wiederverwendet werden.
• Wiederverwendete Läufe geben sofort status: completed und cached: true zurück, sowohl live als auch bei Vorberechnung.
• force_refresh: true übergeht die Wiederverwendung abgeschlossener Läufe (live und vorberechnet). Ein bereits laufender Lauf mit demselben Fingerabdruck wird dennoch zurückgegeben, statt ihn zu duplizieren.

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. Cache-Treffer und wiederverwendete Läufe verbrauchen keine Credits. 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 zurück. Die Antwort enthält den booleschen Wert cached sowie 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 Vorberechnung im Stapel gibt ein items-Array mit einem Eintrag je Person zurück sowie Top-Level-credits / plan.

Antwort für eine Person (neuer Lauf)

{
  "id": "tu_01JCXY",
  "status": "pending",
  "candidate_id": "cand-9911",
  "created_at": "2026-08-28T12:56:44.642Z",
  "cached": false,
  "credits": {
    "balance": 142,
    "plan_credits": 120,
    "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"
  }
}

Antwort für eine Person (Cache-Treffer)

Liegt ein abgeschlossener Lauf innerhalb des Sieben-Tage-Fensters vor und ist force_refresh nicht gesetzt, kann die Antwort auf die Erstellung bereits status: completed mit cached: true lauten. In diesem Fall ist credits.charged 0 und credits.cached true.

{
  "id": "tu_01JCXY",
  "status": "completed",
  "candidate_id": "cand-9911",
  "created_at": "2026-08-28T12:56:44.642Z",
  "cached": true,
  "credits": {
    "balance": 143,
    "plan_credits": 121,
    "rollover_credits": 22,
    "charged": 0,
    "cached": true
  },
  "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

{
  "items": [
    {
      "id": "tu_01JCXY",
      "status": "completed",
      "candidate_id": "cand-9911",
      "created_at": "2026-08-28T12:56:44.642Z",
      "cached": true,
      "credits": {
        "balance": 142,
        "plan_credits": 120,
        "rollover_credits": 22,
        "charged": 0,
        "cached": true
      },
      "plan": {
        "code": "growth",
        "cycle": "monthly",
        "credits_per_cycle": 200,
        "requests_per_minute": 300,
        "period_ends_at": "2026-10-28T12:00:00.000Z"
      }
    },
    {
      "id": "tu_01JCXZ",
      "status": "pending",
      "candidate_id": "cand-9912",
      "created_at": "2026-08-28T12:56:45.102Z",
      "cached": false,
      "credits": {
        "balance": 142,
        "plan_credits": 120,
        "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": 142,
    "plan_credits": 120,
    "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 ist das Restguthaben; plan_credits und rollover_credits sind die Guthaben-Buckets; charged sind für diesen Lauf reservierte oder belastete Credits, oder null wenn bei GET nicht anwendbar; credits.cached ist true bei Wiederverwendung ohne neue Belastung. 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.

Update abrufen

Rufen Sie GET /api/v1/talent-updates/{id} auf, um den Fortschritt zu prüfen und das fertige Profil abzuholen.

Werte von status

Solange status pending ist

{
  "id": "tu_01JCXY",
  "status": "pending",
  "candidate_id": "cand-9911",
  "created_at": "2026-08-28T12:56:44.642Z",
  "completed_at": null,
  "error": null,
  "identity": {
    "confidence": null,
    "full_name": null,
    "headline": null,
    "current_employer": null,
    "location": null
  },
  "work_experience": [],
  "education": [],
  "online_presence": [],
  "credits": {
    "balance": 142,
    "plan_credits": 120,
    "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"
  }
}

Wenn status completed ist

{
  "id": "tu_01JCXY",
  "status": "completed",
  "candidate_id": "cand-9911",
  "created_at": "2026-08-28T12:56:44.642Z",
  "completed_at": "2026-08-28T12:57:26.031Z",
  "error": null,
  "identity": {
    "confidence": "high",
    "full_name": "Alex Rivera",
    "headline": "Software Engineer at Example Corp",
    "current_employer": "Example Corp",
    "location": "London, UK"
  },
  "work_experience": [
    {
      "company": "Example Corp",
      "role": "Software Engineer",
      "start_date": "2016-01",
      "end_date": null,
      "is_current": true,
      "confidence": "high"
    }
  ],
  "education": [
    {
      "institution": "Example University",
      "qualification": "Bachelor of Science",
      "confidence": "high"
    }
  ],
  "online_presence": [
    {
      "platform": "linkedin",
      "url": "https://linkedin.com/in/alex-rivera-example",
      "confidence": "high"
    }
  ],
  "credits": {
    "balance": 142,
    "plan_credits": 120,
    "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"
  }
}

Felder der Antwort

Jede GET-Antwort enthält die Profilstruktur (identity, work_experience, education, online_presence). Solange status den Wert pending hat, sind diese Felder null oder leer; bei completed enthalten sie die ermittelten Daten. GET-Antworten enthalten außerdem dieselben additiven Objekte credits und plan wie Create.

Zeitstempel sind UTC mit Z. Beschäftigungsdaten liegen in der Regel als YYYY-MM vor.

Aufzählungen

Jede Aufzählung kann neue Werte erhalten. Behandeln Sie einen unbekannten Wert als seinen sichersten Nachbarn, nicht als Fehler.

Fehler

Antworten außerhalb von 2xx verwenden application/problem+json (RFC 9457). Verzweigen Sie über status und, wo vorhanden, über stabile Fehlercodes.

Beispiel einer Fehlerantwort

{
  "type": "https://intelligence.tietalent.com/errors/invalid-request",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "A personal email address needs company or employer_website with it. Send first_name and last_name too where you have them."
}

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 Antwortfelder (einschließlich credits und plan) können ohne Versionswechsel hinzukommen.

Webhooks

Abfragen wird unterstützt, Webhooks sind jedoch vorzuziehen, sofern eingerichtet. Die Zustellung erfolgt mindestens einmal; Ihre Handler müssen bezogen auf die Ereignis-id idempotent sein. Betrachten Sie GET /api/v1/talent-updates/{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. Prüfen Sie die Signatur und weisen Sie Zeitstempel zurück, die älter als fünf Minuten sind.

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

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

Die Webhook-Nutzlast ist nur ein Verweis: result_url, talent_update_id und candidate_id. Holen Sie das vollständige Profil über einen authentifizierten GET-Aufruf.

api_environment entspricht der Bezeichnung des API-Schlüssels, mit dem der Lauf authentifiziert wurde (Production, Staging oder Test): derselbe Wert wie in Ihrer Liste der API-Schlüssel.

{
  "id": "evt_01JDABC",
  "type": "talent_update_ready",
  "created_at": "2026-08-28T12:57:26.031Z",
  "api_environment": "Production",
  "data": {
    "candidate_id": "cand-9911",
    "status": "completed",
    "result_url": "https://intelligence.tietalent.com/api/v1/talent-updates/tu_01JCXY",
    "talent_update_id": "tu_01JCXY"
  }
}

{
  "id": "evt_01JDABD",
  "type": "talent_update_failed",
  "created_at": "2026-08-28T12:57:30.031Z",
  "api_environment": "Production",
  "data": {
    "candidate_id": "cand-9911",
    "status": "failed",
    "result_url": "https://intelligence.tietalent.com/api/v1/talent-updates/tu_01JCXY",
    "talent_update_id": "tu_01JCXY",
    "error_code": "internal_error"
  }
}

Bekannte Grenzen

Diese Grenzen offen zu benennen ist das, was die übrigen Angaben vertrauenswürdig macht.