Candidate Intelligence API-Integration

Ideal für

Partnervorteile

Warum Candidate Intelligence integrieren?

Bieten Sie Ihren Kunden zusätzlichen Kontext vor Interviews und schaffen Sie gleichzeitig neuen Mehrwert in Ihrer Plattform.

Integrationsablauf

Leistung und Latenz

Candidate Intelligence ist darauf ausgelegt, Recruitern ein reaktionsschnelles Erlebnis direkt in ihren Workflows zu bieten.

Logik zur Berichtswiederverwendung

Berichte werden eindeutig über Plattform + Unternehmen + Kandidat identifiziert.

Der Cache gilt pro Recruiter: Ihr API-Schlüssel identifiziert die Partnerintegration, client.id identifiziert den Recruiter (Benutzer) in Ihrer Plattform. Unterschiedliche client.id-Werte teilen keinen Cache, auch nicht unter demselben API-Schlüssel.

Cache-Schlüsselfelder

Nicht Teil des Cache-Schlüssels

Zwischengespeicherte Berichte werden bis zu 6 Monate wiederverwendet. Ältere abgeschlossene Analysen werden nicht aus dem Cache zurückgegeben.

Aktualisierung erzwingen

Setzen Sie force_refresh: true bei POST /api/v1/analyses, um die Cache-Suche zu überspringen und die vollständige Analyse-Pipeline auszuführen — Anreicherung, Live-Signale und LLM-Berichtserstellung.

Lassen Sie force_refresh weg oder setzen Sie es auf false, um Cache-Wiederverwendung zuzulassen (Standard).

Wann force_refresh: true setzen

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

Authentifizierung

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

Analyse erstellen

Optionale Body-Felder: candidate.cv (Klartext-CV, nur bei frischen Läufen) und force_refresh (Boolean, Standard false — siehe Aktualisierung erzwingen).

{
  "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 (optional, Standard false) überspringt die Berichtswiederverwendung und erstellt immer einen neuen Bericht — der neue Bericht wird abgerechnet. Lassen Sie das Feld weg, sofern der Recruiter nicht ausdrücklich eine Aktualisierung anfordert.

202 Accepted

Der Location-Header verweist auf GET /api/v1/analyses/'{'id'}'. Retry-After: 10 gibt an, wann das nächste Polling erfolgen soll.

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

Polling und progressive Ergebnisse

Nach einem POST mit 202 Accepted rufen Sie GET /api/v1/analyses/'{'id'}' mit demselben X-API-Key-Header ab. Verwenden Sie die ID aus der Erstellungsantwort.

Solange der Status queued oder processing ist, enthält jede GET-Antwort Retry-After: 10 — warten Sie mindestens 10 Sekunden vor der nächsten Anfrage.

Beenden Sie das Polling, wenn der Status completed, failed oder canceled ist.

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

Felder, die während der Verarbeitung befüllt werden

Statuswerte

Analyse abbrechen

DELETE /api/v1/analyses/'{'id'}' stoppt eine wartende oder laufende Analyse, wenn ein Recruiter das Kandidatenprofil verlässt oder einen laufenden Bericht verwirft. Verwenden Sie denselben X-API-Key-Header wie bei POST und GET.

Ist die Analyse bereits completed, failed oder canceled, gibt der Endpunkt die aktuelle Ressource unverändert zurück — keine zusätzlichen Kosten oder Nebenwirkungen.

// Kein Request-Body — nur X-API-Key-Header

200 OK

Gibt die Analyse-Ressource mit Status canceled zurück. Teilweise quick_signal oder signals können vorhanden sein, wenn der Abbruch mitten in der Pipeline erfolgte. Beenden Sie das Polling, sobald der Status canceled ist.

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

Abgeschlossene Analyse

Wird zurückgegeben, wenn der Status completed ist. Der Bericht unten ist gekürzt — die vollständige Feldliste finden Sie in der Referenz des Berichtsobjekts.

Frischer Bericht (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
}

Zwischengespeicherter Bericht (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
}

Das metadata-Objekt

metadata.pdf_download_url ist ein signierter Link, der den vollständigen gehosteten TieTalent-Bericht öffnet (dasselbe Berichtsdesign wie in der Web-App); der PDF-Export kann aus dieser Ansicht heruntergeladen werden. Behandeln Sie den Link vertraulich — jeder, der ihn besitzt, kann den Bericht öffnen.

metadata.cached ist true, wenn ein vorhandener Bericht wiederverwendet wurde, anstatt einen neuen zu erstellen (siehe Logik zur Berichtswiederverwendung); cached_at enthält dann den Zeitstempel der Wiederverwendung, andernfalls ist es null.

Verdicts und Kompatibilität

report.recommendation.decision ist das zentrale Urteil des Berichts. Es ist immer einer der vier folgenden Werte.

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

Ordnen Sie jedes Verdict einem von drei UI-Zuständen zu:

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

Referenz des Berichtsobjekts

report wird nur befüllt, wenn der Status completed ist. Feldnamen sind in camelCase. Die Struktur entspricht dem aktuellen Berichtsdesign, das auf allen TieTalent Intelligence-Oberflächen verwendet wird (Web-App, Extension und gehosteter Bericht).

Kernfelder (immer vorhanden)

Optionale Felder

Diese Felder können fehlen. Behandeln Sie sie als nullable und ignorieren Sie Felder, die Ihre Oberfläche nicht nutzt.

Feedback zu einem Bericht senden

POST /api/v1/analyses/'{'id'}'/feedback ermöglicht es Ihren Recruitern, einen abgeschlossenen Bericht zu bewerten — 1 bis 5 Sterne, optionale Tags und optionaler Freitext — damit TieTalent die Berichtsqualität auf Ihrer Seite der Integration nachverfolgen kann.

Der Endpunkt führt ein Upsert auf client.id plus die Bericht-id durch: Ein erneutes Senden für denselben Client und Bericht überschreibt die vorherige Bewertung, Tags und den Text — es gibt keinen Versionsverlauf.

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

Anfragefelder

Feedback-Tag-Katalog

Tags sind nach Bewertungsband gruppiert und ändern sich je nach gesendeter Bewertung — gestalten Sie Ihre eigene Oberfläche, senden Sie aber nur die kanonischen Ids, damit Feedback sprachübergreifend analysierbar bleibt.

// 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

Gibt das gespeicherte Feedback zurück und spiegelt die aktuelle Bewertung, Tags und den Text für diesen Client und Bericht wider.

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

Empfohlene Partner-Oberfläche

Schaltfläche in Kandidatenprofilen hinzufügen

Fügen Sie eine Schaltfläche „Candidate Intelligence-Bericht starten“ in Kandidatenprofilen hinzu. Beim Klick wechselt sie zu „Bericht wird erstellt...“ während der Generierung. Sobald der Bericht fertig ist, öffnet er sich automatisch und die Schaltfläche wird zu „✕ Bericht schließen“. Nach dem Schließen wechselt sie zu „Intelligence-Bericht ansehen“, um einen bereits gespeicherten Bericht erneut zu öffnen — ohne erneut POST aufzurufen.

Datenschutz und Sicherheit